Skip to main content
Outbound Calls let you place phone calls programmatically: your system makes one API request, a Telzino AI agent dials the number, holds the conversation, and the result — status, duration, AI summary, and transcript reference — is delivered back to you.

​
How it works

1

Trigger the call

POST /v1/agents/{agentId}/outbound-calls with the destination number. You can include per-call context for the agent, opaque metadata, and a webhook URL for the result. The API responds immediately with 202 Accepted and a call ID — the call is queued, not yet ringing.
2

The platform places the call

The dispatcher picks up your queued call (typically within a couple of seconds), assigns an agent worker, and dials the number. The agent speaks its greeting as soon as the callee answers — never while the phone is still ringing.
3

The agent has the conversation

The agent uses its full configuration: system prompt (plus your per-call call_context), voice, tools, integrations, and after-call webhooks — identical capabilities to inbound calls.
4

You receive the result

When the call reaches a terminal state, the result webhook fires (if you provided callback_url) and the call record is finalized with duration, AI summary, and a transcript reference. You can also poll the call at any time.

​
Call lifecycle

Every outbound call moves through these statuses: completed, voicemail_left, no_answer, busy, and failed are terminal — the result webhook fires exactly when one of these is reached. If the call has a retry policy, a terminal voicemail_left, no_answer, busy or failed may be followed by a new scheduled call with the next attempt_number.

​
The result webhook

If you pass a callback_url when triggering the call, Telzino POSTs the result to it on every terminal status:
  • metadata is your own payload from the trigger request, echoed back verbatim — use it to correlate the result with records in your system. On a retry it also carries a reserved _telzino_retry key with parent_call_id and attempt_number.
  • transcript_id links to the full transcript, retrievable via the Call Logs API.
  • For unanswered or failed calls, summary_text and transcript_id are null and sip_status_code carries the SIP failure code (e.g. 486 busy, 480 no answer).
  • answer_type is who Answering Machine Detection found on the line — human, machine, ivr or silence_unknown — and null when detection is off for the call. voicemail_left is true when the agent left its voicemail message.
  • ivr_navigation_outcome reports how menu navigation ended, or null when the call never navigated a menu.
  • opt_out_detected is true when the callee asked not to be contacted again; every scheduled retry to that number has already been cancelled.
The result webhook must be an HTTPS URL and is delivered once (10-second timeout, no retries). Treat it as a notification: if your endpoint was down, poll GET /v1/agents/{agentId}/outbound-calls/{callId} — the call record is always the source of truth.

​
Good to know

Without Answering Machine Detection, a voicemail box or auto-attendant counts as an answered call (in_progress → completed) and the agent speaks to the recording. Turn detection on and the agent recognises a voicemail box, leaves your message and ends the call as voicemail_left, re-prompts when nobody speaks, and — with IVR Menu Navigation — works through a phone menu to reach a person.
The platform never retries no_answer, busy, voicemail_left or failed calls unless the agent or the call has a retry policy. With one, each retry is a new call record with attempt_number, parent_call_id and root_call_id, created as scheduled and dialled at next_attempt_at; each attempt fires your webhook on its own. Without one, your application decides whether and when to call again.
A trigger can be refused for policy reasons rather than validation: 409 policy_violation (a retry policy’s per-number caps), 409 suppressed (the number is on the organization’s suppression list), 409 out_of_window (outside the agent’s calling hours), and 400 consent_required (the agent requires a consent_basis). See Trigger Outbound Call.
When the callee answers, the agent speaks the first match in this order:
  1. The greeting field from the trigger request — spoken verbatim.
  2. The agent’s Outbound Greeting setting (dashboard agent settings, or outboundGreetingMessage via the Agents API) — spoken verbatim.
  3. If call_context was provided — an AI-composed opener that introduces the agent and states the reason for the call (e.g. “Hi, this is Ava from Acme calling to confirm your appointment tomorrow at 2pm.”).
  4. Otherwise, the agent’s inbound greeting message.
The agent’s skip_greeting voice setting suppresses all of these.
The agent’s stored configuration (prompt, voice, tools) always applies. call_context is appended to the prompt for that one call only — ideal for “you’re calling John to confirm his 2pm appointment” without creating a dedicated agent per purpose.

​
Endpoints

Authentication works exactly like the rest of the API — see Authentication.