Connecting your clinic software

A tool is one HTTP request to your software’s API. During a call, your AI agent:

1. decides to use the tool, based on its Description;
2. fills in the values the request needs from the conversation (AlloMia calls them variables);
3. sends the request and reads what your API returns;
4. answers the patient in its own words.

The Tools page is only for these connections. Text messages, call transfers, clinic documents and call campaigns have their own pages under Tools & Actions, for clinic managers. See Setting up your AI agent.

• A sign-in to your clinic’s AlloMia dashboard. Anyone in the clinic account, with the Owner or User role, can create, change and delete tools.
• Your software’s API documentation: the endpoint URL, the HTTP method, how to authenticate, and the JSON it expects and returns.
• An endpoint that’s reachable from the internet, ideally over HTTPS. Requests come from AlloMia’s servers, not from your clinic’s network. If your firewall accepts only known addresses, write to support@medfarsolutions.com before you start.
• Credentials made for AlloMia only, with only the access the agent needs.
• A test environment, if your software has one. Tests and test calls send real requests.

1. In the menu on the left, click Tools & Actions, then Tools.
2. Click + Tool. A new tool opens on the Details tab.
3. In Name, type 3 to 64 characters: start with a lowercase letter and use only letters and numbers, for example checkAvailability. This rule passes every check in the dashboard. Give each tool its own name.
4. In Description, tell the agent when to use the tool and what it returns (see the next section).
5. Leave Asynchronous Execution and Strict Validation off. They currently have no effect on calls.

The agent reads the description to decide when to use the tool, so write it as an instruction:

• When to use it, and what the agent must know first.
• What it returns.
• When not to use it, if another tool does something close.

Example: “Use this to find open appointment times. Call it once the patient has said which day they want. Returns the open times for that day.”

1. On the Authentication tab, choose how AlloMia signs in to your API, and add any HTTP headers it needs. See Securing a connection to your clinic software.
2. On the Connection tab, choose the HTTP Method: GET, POST, PUT, PATCH or DELETE.
3. In URL Endpoint, type the full URL, for example https://api.example.com/v1/slots?date={{date}}.
4. In Timeout, set how many seconds AlloMia waits for an answer (3 by default, up to 300). Choose a little more than your API’s slowest normal answer.
5. In Retry Count, set how many times AlloMia may send the request again (3 by default, up to 5). See “Good to know” below.
6. Add the variables (next section).
7. For POST, PUT and PATCH, write the body on the Request Body tab (see below).
8. Click Save Settings at the bottom right. It stays grey until Name and a valid URL Endpoint are filled in.

A variable is a value the agent collects during the call and puts into the request. On the Connection tab, under Variables, click Add variable, then fill in:

• Variable Name: the name you use in placeholders, for example date.
• Type: String, Number, Boolean, Array (choose the type of its Items) or Object (add its Properties). Simple types are the most reliable.
• Description: what the agent should put in it, and in what format. For example: “The day the patient wants, as YYYY-MM-DD.”
• Required: on if the agent must have this value before it uses the tool.
• Value: a sample value for the Testing tab. During calls, AlloMia also uses it when the agent leaves an optional variable out, so use harmless test data, never a real patient’s details.

To use a variable, write its name between double braces: {{date}}. Placeholders work in the URL, in header values and in the request body.

• In the URL, the value is inserted as is, without URL encoding. Keep free text, such as names, in the body.
• For GET requests, put every variable in the URL yourself. During calls, AlloMia doesn’t add them to the query string.
• You can also use {{callId}}, an ID AlloMia gives each call, for example to match requests in your logs.

On the Request Body tab, write the JSON your API expects, with placeholders without quotes:

{ "date": {{date}}, "reason": {{reason}} }

AlloMia adds quotes around text values and leaves numbers and true or false as they are. Once the values are filled in, the body must be valid JSON. AlloMia sends Content-Type: application/json unless you choose another type under HTTP Headers, on the Authentication tab. GET requests have no body.

• When your API answers with a 2xx status, the agent receives the response body, JSON or text, and uses it to answer.
• With any other status, the agent receives the status and the body as an error, and answers according to its instructions.
• The agent reads the whole response. Return only what it needs, with clear field names, for example "openTimes": ["09:00", "10:30"].
• What your API returns is saved with the call: it shows in the call’s transcript in Call Logs & Analytics.

In the agent’s instructions, say what to do when the tool fails, for example: “If you can’t check the schedule, offer to have the clinic call the patient back.” See Writing instructions for your AI agent.

• AlloMia may send the same request more than once: when your API answers with a temporary error such as 429, 500, 502, 503 or 504, and, for a tool that uses authentication, when your API doesn’t answer within the Timeout. Make sure a repeated request can’t create a second booking. A Retry Count of 0 is treated as 3.
• If your API doesn’t answer within the Timeout, the request fails and the agent is told so.
• You can choose what the agent says while it waits. See What the agent says while it looks something up.

1. In the menu on the left, click Voice Agents, then click the AI agent in the My Agents list.
2. Click the Tools & Actions tab.
3. Find your tool: it has a Function label. Turn on its switch.
4. Click Save Settings. Calls that start after that can use the tool.

See Turning actions on or off for your AI agent.

1. On the tool’s Testing tab, click Test Tool. See Testing a connection.
2. On the AI agent, click Speak with Agent and ask something that needs the tool, for example “Do you have anything on Tuesday morning?” If the tool books appointments, the booking is real: cancel it afterwards.
3. In Call Logs & Analytics, open the test call. In the Conversation Transcript, a Tool Call line shows the values the agent sent, and a Tool Result line shows your API’s answer. Click them to see the details.

• Save Settings stays grey: fill in Name and a full URL Endpoint that starts with https:// or http://.
• “Please fill in all mandatory fields” appears although Name, Description and URL Endpoint are filled in: the message covers the other tabs too. Check that every variable has a name, a type and a description, every header has a key and a value, and every authentication field is filled in.
• The agent never uses the tool: check its switch on the agent’s Tools & Actions tab, then make the description say more clearly when to use it.
• The agent sends wrong values: make the variable descriptions more precise, with the expected format.
• The test works but calls fail: for GET, check that every variable is in the URL. Then compare the Tool Call and Tool Result lines in the call’s transcript with your API logs.
• Two tools behave as one: two tools turned on for the same agent have the same name. Rename one.