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"

data

array

Show phone number

string

The phone number id (use as fromPhoneNumberId).

number

string

The number in E.164 format.

label

string

Your label for the number.

provider

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.

toNumber

string

required

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

fromPhoneNumberId

string

required

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

dynamicVariables

object

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

firstMessage

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