Starting calls from your own software

• An API key created by the person who created the clinic account. AlloMia refuses calls started with a key created by anyone else. See Keys for connecting other software.
• An AI agent set up for this kind of call. Its instructions say what to do on the call. The tips in Reminder and follow-up call campaigns apply here too.
• One of your clinic’s phone numbers to call from. The patient sees it as the caller ID. A number bought in AlloMia is ready. A number from your own provider needs an outbound trunk: see Connecting your clinic’s phone system. A SIP address made with Create SIP can’t be used.
• Each answered call counts toward your clinic’s minutes, like any other call. A call that is never answered doesn’t.

• assistantId, the AI agent: in the menu on the left, click Voice Agents. In the My Agents list, point at the agent, click the three dots (⋮), then Copy ID.
• phoneNumberId, the number to call from: click Phone Numbers. At the end of the number’s row, click the three dots (⋮), then Copy ID.

Send POST https://allomia.com/api/outbound with the header Authorization: Bearer followed by your key, and the header Content-Type: application/json. The JSON body has these fields:

• phoneNumber (required): the number to call, in E.164 format, for example +15145551234. A 10-digit number without + is treated as a Canadian or US number.
• assistantId (required): the AI agent that makes the call.
• phoneNumberId (required): the clinic number to call from.
• customerName (optional): the patient’s name, up to 40 characters. It’s kept with the call request, but the AI agent doesn’t see it.
• dynamicVariables (optional): details for this call, as names with text values, for example first_name and appointment_date. In the AI agent’s instructions, write a name between double curly braces, such as {{first_name}}, and AlloMia puts the value in its place. Details work in the instructions, not in the greeting. To let the agent use the patient’s name, send it here too.
• callbackUrl (optional): an HTTPS address where AlloMia sends the result when the call ends.

When the request is accepted, the answer is HTTP 200 with outboundCallId, contactId, status and message. Keep outboundCallId: you need it to check the call.

• status is calling: AlloMia is placing the call.
• status is failed, with the message “Outbound call failed to dispatch”: the call couldn’t be placed, even though the HTTP status is 200. No callback follows. Check the number you call from, then try again.

Check the status. Send GET https://allomia.com/api/outbound/OUTBOUND_CALL_ID/status, with your outboundCallId in place of OUTBOUND_CALL_ID. The status is pending or calling while the call is under way, then one of these final values:

• completed: the call was answered, by a person or by voicemail. AlloMia can’t tell the two apart.
• no-answer or busy: nobody answered, or the line was busy. AlloMia doesn’t call again.
• failed: the call couldn’t be made, or ended with an error.

Once the status is final, callDetails gives startedAt, endedAt, duration in seconds and endedReason, for example customer-ended-call. Before that, it’s null.

Or wait for the callback. If you sent a callbackUrl, AlloMia sends one POST with a JSON body when the call reaches a final status. The body has event (always call.completed), outboundCallId, contactId, status, timestamp, callDetails and dynamicVariables (the details you sent).

• Answer with any 2xx status within 10 seconds. Otherwise AlloMia tries again after 1, 5 and 30 seconds, 4 tries in all, then stops.
• AlloMia sends it at most once per call. It isn’t sent when the first answer already said failed.
• Use a hard-to-guess HTTPS address. Before you act on a callback, check that the outboundCallId is one you started and confirm the result with the status request.

The call also shows in Call Logs & Analytics with the type Outbound, like any other call.

With a key from your clinic, your software can also list your clinic’s calls and read one call, with its summary and links to its transcript and recording. See List Calls and Get Call on the developer site.

Errors come back as JSON, with the message in an error field.

• 401 “Unauthorized”: the key is missing, wrong or deleted.
• 403 “Insufficient permissions”: the key wasn’t created by the person who created the clinic account.
• 400 “Invalid request data”: the details list names each field with a problem, for example a missing assistantId or a name over 40 characters.
• 404 “Phone number not found” or “Assistant not found”: the ID is wrong or belongs to another clinic. Copy it again.
• 422 “Organization is inactive or not found”: the clinic account isn’t active. Write to AlloMia support.
• 500 with “Phone number format is invalid”: fix phoneNumber. 500 with “This number cannot be used as an outbound caller ID”: for phoneNumberId, choose a phone number, not a SIP address. These two are problems with the request, even though the status is 500 for now.
• The status request gets 401 “Organization ID not found in authorization”: the status request accepts only a clinic key, made in Organization Settings. Use one, or rely on the callback.
• Other 500 errors: try again a little later. If it keeps happening, write to support@allomia.com with the time of the request and the outboundCallId, if you have one.

For the full field list and examples, see Create Outbound Call on the developer site.