Trillet AI logo

Initiate Outbound Call

Send an AI-driven phone call to a given number.

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

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Request Body

tostringrequired

The number to call, in E.164 format, for example +14155550123. It must be a real, valid number: a number that only looks like E.164, such as +14155550123, is refused with 400 and code INVALID_PHONE_NUMBER. Digits without the + are accepted when they form a valid number with it.

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. It must be one of the agent's numbers. When omitted, one of the agent's numbers is picked at random (WhatsApp numbers are used only when you name them here). An agent with no phone numbers can't place calls.

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.

Rate limit

Outbound calls are limited per workspace, in a fixed 60-second window:

  • 1 call per minute for a workspace with no paid plan and no wallet top-up
  • 20 calls per minute for a workspace on Studio or Agency Plus, or one that has topped up its wallet
  • No limit on Enterprise pricing

Calls placed by a batch are counted separately. Over the limit, the call is rejected with error "Rate limit exceeded: You have limit of N calls per minute. Please wait S seconds before making another call." Wait the number of seconds in the message before retrying.

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:

  • INVALID_PHONE_NUMBER (400): to is not a valid phone number.
  • AGENT_FLOW_MISMATCH (400): call_agent_id and call_flow_id refer to different agents.
  • CALL_FLOW_NOT_LIVE (400): the call_flow_id you sent is archived or inactive.
  • AGENT_NOT_FOUND (404): no agent or call flow with that ID in this workspace.
  • FREE_PLAN_OUTBOUND_BLOCKED (403): outbound calling is not included on the free plan.
  • SERVICE_ENDED (403): the account's plan has ended.
  • workspace_suspended (403): the workspace's traffic is suspended.
  • 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.

Before the call is checked, the workspace's balance is checked. These responses use a different body, {"error", "code", "message"}:

  • INSUFFICIENT_FUNDS (400): the balance is spent. The body also has balance and walletScope.
  • WORKSPACE_ID_REQUIRED (400): no x-workspace-id.
  • SPEND_CAP_REACHED (402): the monthly spend cap has been reached.
  • WALLET_NOT_FOUND (403): the workspace has no wallet.
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.

timezonestring

Returned with OUTSIDE_CALLING_HOURS. The call flow's IANA timezone, or null.

Personalized greeting and voicemail
{
  "to": "+14155550123",
  "call_agent_id": "e9e9e9e9e9e9e9e9e9e9e9e9",
  "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 e9e9e9e9e9e9e9e9e9e9e9e9 to number +14155550123",
  "call_agent_id": "e9e9e9e9e9e9e9e9e9e9e9e9",
  "callId": "f1f1f1f1f1f1f1f1f1f1f1f1",
  "roomName": "e9e9e9e9e9e9e9e9e9e9e9e9-x7k2m9p4q1",
  "jobId": "123"
}

Last updated on