> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Outbound Call

> Queues an outbound call: the agent dials the number and the result is delivered to your webhook

## Path Parameters

<ParamField path="agentId" type="string" required>
  The agent that will make the call (UUID format). Must be a Telzino AI agent you have access to.
</ParamField>

## Request Body

<ParamField body="to_number" type="string" required>
  Destination phone number in E.164 format, e.g. `+18135551234`. Numbers in any other format are rejected with `400`.
</ParamField>

<ParamField body="call_context" type="string">
  Context for this specific call, appended to the agent's system prompt (max 4000 characters). Use it to tell the agent who it's calling and why.

  Example: `"You are calling John Smith to confirm his appointment tomorrow at 2pm. If he can't make it, offer Thursday at 10am."`
</ParamField>

<ParamField body="greeting" type="string">
  Exact opening line the agent speaks when the callee answers (max 1000 characters). Overrides the agent's Outbound Greeting setting and the auto-generated opener.

  Example: `"Hi, this is Ava calling from Acme Corp about your appointment."`

  **Greeting precedence when the callee answers:** this `greeting` field → the agent's Outbound Greeting setting → an AI-generated opener composed from `call_context` → the agent's inbound greeting message.
</ParamField>

<ParamField body="metadata" type="object">
  Opaque JSON object (max 16KB serialized) stored with the call and echoed back verbatim in the result webhook and call record — use it to correlate the call with records in your system (CRM IDs, campaign IDs, etc.).
</ParamField>

<ParamField body="callback_url" type="string">
  HTTPS URL that receives the [result webhook](/api-reference/outbound-calls/overview#the-result-webhook) when the call reaches a terminal state. Must use `https://`; URLs resolving to private networks are rejected.
</ParamField>

## Response

Returns `202 Accepted` immediately — the call is queued and dials within a few seconds.

<ResponseField name="id" type="string">
  The outbound call ID. Use it to poll status via [Get Outbound Call](/api-reference/outbound-calls/get).
</ResponseField>

<ResponseField name="status" type="string">
  Always `queued` on creation. See the [call lifecycle](/api-reference/outbound-calls/overview#call-lifecycle) for the full status progression.
</ResponseField>

<ResponseField name="room_name" type="string">
  Internal call room identifier (also appears on the linked call log).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the call was queued.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000/outbound-calls" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "to_number": "+18135551234",
      "call_context": "You are calling John to confirm his appointment tomorrow at 2pm.",
      "metadata": { "crm_id": "123" },
      "callback_url": "https://your-system.com/telzino/call-result"
    }'
  ```

  ```javascript JavaScript theme={null}
  const agentId = '123e4567-e89b-12d3-a456-426614174000';

  const response = await fetch(
    `https://api.telzino.com/v1/agents/${agentId}/outbound-calls`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        to_number: '+18135551234',
        call_context: 'You are calling John to confirm his appointment tomorrow at 2pm.',
        metadata: { crm_id: '123' },
        callback_url: 'https://your-system.com/telzino/call-result',
      }),
    }
  );

  const call = await response.json();
  console.log(`Call ${call.id} queued`);
  ```

  ```python Python theme={null}
  import requests

  agent_id = '123e4567-e89b-12d3-a456-426614174000'

  response = requests.post(
      f'https://api.telzino.com/v1/agents/{agent_id}/outbound-calls',
      headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
      json={
          'to_number': '+18135551234',
          'call_context': 'You are calling John to confirm his appointment tomorrow at 2pm.',
          'metadata': {'crm_id': '123'},
          'callback_url': 'https://your-system.com/telzino/call-result',
      },
  )

  call = response.json()
  print(f"Call {call['id']} queued")
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "id": "0fc6daf8-7251-4553-9488-867ba0b82d8e",
    "status": "queued",
    "room_name": "agent-123e4567-e89b-12d3-a456-426614174000-out-0fc6daf8-7251-4553-9488-867ba0b82d8e",
    "created_at": "2026-06-11T12:49:28.898751+00:00"
  }
  ```

  ```json 400 theme={null}
  {
    "error": "invalid_request",
    "error_description": "to_number must be E.164 (e.g. +15105550123)"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "not_found",
    "error_description": "Agent not found or access denied"
  }
  ```
</ResponseExample>