Create outbound call
Start a call.
Get outbound call status
Check where a call stands.
Call-completed callback
Get the result sent to your server.
Which keys work
These endpoints accept fewer keys than the rest of the API. Who created the key matters.
A key created by anyone else gets
403 Insufficient permissions. A partner key on the status endpoint gets 401. See Authentication for how keys work.
How a call works
1
Start the call
Send
POST /api/outbound with the number to call, the AI agent (assistantId), and the clinic number to call from (phoneNumberId). You can add the person’s name, details for the agent (dynamicVariables) and a callbackUrl. AlloMia checks the request, records the call and starts dialing before it answers. See Create outbound call.2
Read the immediate response
A successful request returns HTTP 200 with an
outboundCallId and a status. Check status, not only the HTTP code:calling: AlloMia started dialing.failed: the call couldn’t be placed, even though the HTTP status is 200. No callback follows.
outboundCallId. You need it to check the call.3
Wait for the call to end
The status stays
calling while the phone rings and during the conversation. When the call ends, the status becomes final: completed, busy, no-answer or failed.4
Get the result
If you sent a
callbackUrl, AlloMia sends one call.completed callback to it when the status becomes final. See Call-completed callback. You can also check the status at any time with GET /api/outbound/{id}/status. See Get outbound call status.Statuses
AlloMia doesn’t tell a person from voicemail: a call picked up by voicemail ends as
completed. AlloMia doesn’t call again after busy or no-answer. To try again, start a new call.
A call can occasionally stay
calling and never reach a final status. If a call is still calling well after it should have ended, treat its result as unknown.How the end reason sets the status
Once a call is final,callDetails.endedReason says why it ended. It sets the status like this:
A call that failed before dialing (the
failed status in the first response) has no endedReason. See How a call can end for what each reason means.
Usage
Only calls that connect count toward the clinic’s usage. A call that is never answered (busy or no-answer) records no billable time, and neither does a call that couldn’t be placed.
Reading the conversation
The status and the callback tell you how the call ended. The summary, transcript and recording are on the call’s record in the Calls, withcallType set to Outbound. The status and callback don’t include that record’s ID. To find it:
- Call List calls with
callType=Outbound,searchset to the number you called (digits only, such as5145550187), andfromset tocallDetails.startedAt. - Take the matching call’s
idand call Get call.
null when the callback arrives. If they are, try again a little later. A call that was never answered has no record in List calls, and no summary, transcript or recording.