Initiate Outbound Call

POSThttps://api.trillet.ai/v1/api/call

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Request Body

tostringrequired

The phone number to which the call will be made.

call_agent_idstringrequired

The ID of the agent assigned to make the call. Required unless you send call_flow_id instead.

call_flow_idstring

The ID of the call flow to call with, accepted in place of call_agent_id. The call runs on the agent that the call flow belongs to, and the portal lists both IDs together, so you can send whichever one you have.

Send one or the other. Sending both is allowed only when they refer to the same agent; if they do not, the request is rejected.

The call flow must be the live one for its agent. An archived or inactive call flow is rejected rather than silently falling back to the agent's current call flow.

from_phone_number_idstring

The ID of the phone number to call from. When omitted, one of the agent's numbers is chosen automatically.

callback_urlstring

A URL to receive webhook events about the call. If provided, this URL will be used for notifications.

dynamic_variablesobject

Values to fill in on this call, as a flat object of strings. The keys are your own: there is no fixed list, so name them to match what your call flow uses.

To use a value, write its key in double curly braces, such as {{first_name}}, in any of these call flow settings:

the call flow prompt
the greeting, as either the custom message or the AI greeting prompt. Calls placed with this endpoint use the call flow's Outbound greeting.
the voicemail message

Spell each key exactly as you send it, including upper and lower case, and put no spaces inside the braces. A first_name key fills in {{first_name}}, but not {{firstName}}, {{First_Name}} or {{ first_name }}.

Send every variable your call flow uses. An unfilled placeholder is spoken as written, except in the AI greeting prompt, where it is left out.

The request example on this page suits a call flow whose Outbound greeting is the custom message {{greeting_text}}, whose voicemail message is {{voicemail_message}}, and whose prompt refers to the person as {{first_name}}. Because the text is sent per call, each call can have its greeting and voicemail in a different language.

metadataobject

Any fields passed here will be sent to the call agent and directly passed to the webhook triggered by the agent under its 'metadata' header, but they will not be included in the call agent's context.

reject_outside_hoursbooleandefault: false

Refuse the call, instead of queueing it, when the call flow is outside its calling hours. The hours are checked when the request is received and again when the call is about to dial:

If the call flow is outside its hours when the request is received, the API returns 409 with code OUTSIDE_CALLING_HOURS. No call is queued and nothing is added to Call History.
If the hours close before the call dials, the call is marked Failed in Call History with callEndReason outside_calling_hours, and it is not queued again.

With the default, false, a call outside calling hours is queued for the next window. See Calling hours. Calls from a WhatsApp number do not use calling hours, so this option does not affect them. Send true or false; any other value returns 400.

Calling hours

When the call flow has calling hours turned on, a call requested outside them is queued by default and dials when the next window opens. Until then it shows in Call History as Scheduled, with the reason "Outside office hours", and its call history record has status pending and pendingReason office_hours. If no window opens in the next 30 days, the call is marked Failed instead, with callEndReason outside_calling_hours. A queued call cannot be cancelled yet. To have the API refuse these calls instead, send reject_outside_hours: true.

If our servers can't start a call the API accepted, for example because its call flow was deactivated after the request, the call is marked Failed in Call History. Its status is failed, callEndReason gives the reason, such as no_active_call_flow, and error explains it. These calls do not trigger callback_url. A system error while the call is connecting can leave it Scheduled instead.

To check on a call, read its record with Get a Specific Call History using the callId from the response.

Response Fields

statusstring

The status of the request, indicating the success or failure of the call initiation.

messagestring

A message providing feedback about the call initiation process, typically confirming successful initiation or describing an error.

call_agent_idstring

The agent the call was placed with. Useful when you sent a call_flow_id and want to confirm which agent it resolved to.

callIdstring

A unique identifier assigned to the initiated call. This ID can be used to track the call's progress or retrieve its details later.

roomNamestring

The name of the session room created for this call session.

jobIdstring

The identifier of the background job scheduled to execute the outbound call.

errorstring

Returned when the call could not be initiated. Explains why, in text you can show to your users. Some 400 responses have no error and give the reason in message instead: a missing field, a field of the wrong type, or a call_agent_id and call_flow_id that refer to different agents.

codestring

Returned with some errors, so you can handle them in code:

OUTSIDE_CALLING_HOURS (409): the call flow is outside its calling hours and you sent reject_outside_hours: true.
NO_ACTIVE_CALL_FLOW (422): the agent has no live call flow. Use an agent whose call flow is live.
CALL_FLOW_INBOUND_ONLY (422): the agent's call flow only takes inbound calls.

With these codes, no call is queued and nothing is added to Call History.

next_available_atstring

Returned with OUTSIDE_CALLING_HOURS. When the call flow's next calling window opens, as an ISO 8601 time in UTC. It is null when there is no calling window in the next 30 days.

Personalized greeting and voicemail

{
  "to": "+1234567890",
  "call_agent_id": "a1b2c3d4e5f6a7b8c9d0e1f2",
  "dynamic_variables": {
    "first_name": "Maria",
    "greeting_text": "Hi Maria, this is Alex from Acme Plumbing. Is now a good time to confirm your appointment for tomorrow?",
    "voicemail_message": "Hi Maria, this is Alex from Acme Plumbing, calling to confirm your appointment for tomorrow. Please call us back when you can."
  }
}

{
  "status": "success",
  "message": "Outbound call job scheduled for agent a1b2c3d4e5f6a7b8c9d0e1f2 to number +1234567890",
  "call_agent_id": "a1b2c3d4e5f6a7b8c9d0e1f2",
  "callId": "f9e8d7c6b5a4f3e2d1c0b9a8",
  "roomName": "a1b2c3d4e5f6a7b8c9d0e1f2-x7k2m9p4q1",
  "jobId": "123"
}