Calls

Trigger outbound voice calls from your agents — pass details straight into the agent as variables it can use during the conversation. This is the API’s automation payoff: fire a call from your own systems when a lead comes in.

List phone numbers

Returns the phone numbers in your workspace. Use a number’s id as the fromPhoneNumberId when placing a call.

GET /phone-numbers

curl https://intent-weasel-655.eu-west-1.convex.site/api/v1/phone-numbers \
  -H "Authorization: Bearer YOUR_API_KEY"

array

Show phone number

string

The phone number id (use as fromPhoneNumberId).

string

The number in E.164 format.

string

Your label for the number.

string

twilio, sip_trunk, or exotel.

{
  "data": [
    {
      "id": "phnum_8901...",
      "number": "+12089745876",
      "label": "Front desk line",
      "provider": "twilio"
    }
  ]
}

Place an outbound call

Requires the Scale plan (write access).

Places a call from the given agent, using one of your phone numbers. Any dynamicVariables you pass are available to the agent as {{variables}} during the call — for example a lead’s name or the reason for the call.

POST /agents/{id}/calls

string

required

The agent to call from.

string

required

The number to call, with country code (e.g. +15551234567).

string

required

The phone number to call from (an id from List phone numbers). It must be assigned to this agent.

object

Key–value pairs passed into the agent as {{variables}}. Values may be strings, numbers, or booleans.

string

Override the agent’s opening line for this call only.

curl -X POST https://intent-weasel-655.eu-west-1.convex.site/api/v1/agents/jd70.../calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumber": "+15551234567",
    "fromPhoneNumberId": "phnum_8901...",
    "dynamicVariables": { "name": "Alex", "reason": "demo follow-up" }
  }'

{ "conversationId": "conv_2701..." }

The call is placed and a 202 is returned with the conversationId. You can fetch its transcript afterward from Get a conversation.

Common errors

Status	Code	When
400	`invalid_request`	Missing `toNumber` / `fromPhoneNumberId`, an unparseable number, or a number not assigned to this agent.
402	`insufficient_credits`	The workspace has no credits, so no call was placed.
404	`not_found`	The agent doesn’t exist in your workspace.

Placing a call spends usage credits, just like a call started any other way. Make sure the destination number and agent are correct before calling in a loop.

Getting started

Your brand

Clients

Building agents

Chat & embedding

Calendar

API

Billing your clients

Account & billing

List phone numbers

Place an outbound call

Common errors

​List phone numbers

​Place an outbound call

​Common errors

List phone numbers

Place an outbound call

Common errors