Skip to content
TriedDocs
Deploy

Outbound calls

Have an agent call a phone number from the dashboard or with POST /v2/create-phone-call, with per-call variables, overrides and SIP headers.

An outbound call is placed from one of your numbers to any phone number. The number's Outbound Call Agent speaks unless you override it. Use single outbound calls for reminders, call-backs and follow-ups triggered by your systems. For lists of numbers, use Batch calls.

Needs keys

Dialling the phone network needs LiveKit SIP (LIVEKIT_URL, LIVEKIT_SIP_URI) and a working outbound trunk on the number. In mock mode the call is created and runs against the mock providers, but nothing rings.

From the dashboard#

Set an outbound agent#

On Phone Numbers, select the number and pick an agent under Outbound Call Agent, Call Agent.

Open the call dialog#

Click Make an outbound call at the top right of the number.

Fill in the call#

From is the selected number. Enter To in E.164 format (for example +61412345678). Agent defaults to the number's outbound agent; pick another to override it for this call. Tick Don't call numbers on the do-not-call list to refuse contacts flagged do-not-call. Add Dynamic variables as key and value pairs.

Call#

Click Call. A toast shows the new call_id with a View link to Call History.

From the API#

curl -X POST https://api.tried.com.au/v2/create-phone-call \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+61255501234",
    "to_number": "+61412345678",
    "retell_llm_dynamic_variables": { "first_name": "Sam", "appointment_time": "Tuesday 3pm" },
    "metadata": { "crm_id": "12345" },
    "idempotency_key": "reminder-12345-2026-10-21"
  }'

POST /create-phone-call is an alias of the same endpoint.

Field Type Default Description
from_number string required A number in your workspace. It is also the caller ID.
to_number string required Destination in E.164.
override_agent_id string none Use this agent instead of the number's outbound_agents.
override_agent_version integer or string none Version number. On /v2/create-phone-call it may also be latest, latest_published or an environment tag name.
retell_llm_dynamic_variables object {} Dynamic variables for the prompt. Non-string values are converted to strings.
metadata object {} Stored on the call and sent in webhooks.
custom_sip_headers object none Headers on the INVITE. Values may use {{variables}}. See SIP headers.
honor_internal_dnc boolean false Return 400 if the destination's contact is flagged do-not-call.
idempotency_key string, 1 to 200 chars none Repeat requests with the same key within 1 hour return the first call instead of dialling again.
ignore_e164_validation boolean false Skip the E.164 check on to_number, for internal extensions or SIP-specific numbering.
agent_override object none { agent?, retell_llm?, conversation_flow? } fields merged over the stored config for this call only.

The response is HTTP 201 with the call object: call_status starts at registered and moves to ongoing when the callee answers.

What the API checks, in order#

  1. to_number is E.164 (unless ignore_e164_validation).
  2. The workspace business profile is approved, when TRIED_KYC_REQUIRED=1.
  3. from_number belongs to the workspace.
  4. custom_sip_headers names are valid header tokens.
  5. The credit balance is above zero.
  6. The destination is not do-not-call (only with honor_internal_dnc).
  7. The destination is in allowed_outbound_country_list, when the number has one.
  8. An agent is chosen: override_agent_id, or a weighted pick from outbound_agents.
  9. A concurrency slot is free, leaving reserved inbound slots alone. See Concurrency.
  10. A calls-per-second token is free for the number. The request waits up to 5 seconds (CPS_MAX_WAIT_MS) for one.

Then the API creates the room, dispatches the agent, and asks LiveKit SIP to dial on the number's outbound trunk with the caller ID set to from_number. The ring timeout is the agent's ring_duration_ms (default 30000, range 5000 to 300000).

Errors#

Status When
400 Invalid to_number, invalid SIP header name, destination on the do-not-call list, destination country not allowed, or no outbound agent and no override_agent_id
402 Credit balance is zero
403 Business profile not approved (TRIED_KYC_REQUIRED=1)
404 from_number is not in this workspace, or the agent does not exist
409 Another request with the same idempotency_key is still being processed
429 Concurrency limit reached, or the number's calls-per-second limit was not free within the wait
500 The room or dial could not be started; the call ends with dial_failed

When the callee does not answer#

A failed dial ends the call with call_status: "not_connected" and a disconnection_reason mapped from the SIP response:

SIP response disconnection_reason
486, 600 dial_busy
480, 408, 487 or ring timeout dial_no_answer
404, 484, 485, 604, 400, 410 invalid_destination
401, 403, 407 telephony_provider_permission_denied
502, 503, 504 telephony_provider_unavailable
603 user_declined
608 marked_as_spam (also sets spam_flagged on the number)
anything else dial_failed

Voicemail, IVRs and call screening#

For the first 3 minutes of an outbound call, the agent checks whether it reached a voicemail box, an IVR or a call screening service and follows the agent's voicemail_option, ivr_option and call_screening_option. These are agent settings, configured in the agent builder.

Calls per second#

Each number has a token bucket that limits how fast calls start. Set Calls per second under Routing and SIP, or cps_limit in the API (0.1 to 150). Without a value, Telnyx and Twilio numbers use 4 per second (DEFAULT_CPS_TELNYX) and your own trunks use 10 (DEFAULT_CPS_CUSTOM). The dashboard caps the field at the carrier's ceiling: Twilio 5, Telnyx 16, your own trunk 150. Batch calls are paced by the same bucket.