Outbound Phone Calls

Dial an E.164 phone number from one of your provisioned Convoi numbers.

6 min read

Endpoint

http

POST /api/v1/public/calls

The same /calls endpoint creates phone calls when type is "outbound_phone". Provide the destination number, the Convoi-managed phone_number_id to dial from, and the agent that should run the call.

Request body: minimal

json

{
  "type": "outbound_phone",
  "agent_id": "agt_b88d642dd68747f28305c428b209xxxx",
  "customer": { "number": "+92310000053", "name": "xyz" },
  "phone_number_id": "phn_c38155f043624745a66d2e28c185xxxx"
}

Request body: full

json

{
  "type": "outbound_phone",
  "agent_id": "agt_b88d642dd68747f28305c428b209xxxx",
  "customer": {
    "number": "+0000000",
    "name": "xyz",
    "metadata": { "lead_id": "L-12345" }
  },
  "phone_number_id": "phn_c38155f043624745a66d2e28c185xxxx",
  "agent_overrides": {
    "first_message": "Hi Wasay, this is a quick callback from Convoi."
  },
  "metadata": { "campaign": "may-outreach" }
}

Field	Type	Required	Notes
type	string	yes	Must be "outbound_phone".
agent_id	string	yes	Agent that runs the call.
phone_number_id	string	yes	ID of one of your Convoi-managed numbers.
customer.number	string	yes	E.164 (e.g. +971501234567).
customer.name	string	no	Display name for transcripts and dashboards.
customer.metadata	object	no	Free-form per-customer attributes.
agent_overrides	object	no	Per-call overrides: first_message, system_prompt, llm, tts, stt, knowledge_base_ids.
metadata	object	no	Free-form per-call attributes.

Response

The response mirrors the web-call response, except livekit and room_id are null. customer is populated; status begins at "initiated" and transitions through "active" → "completed" (or one of the terminal failure states). duration_seconds and cost.amount update as the call progresses.

Related in Calls