Place a call

POST

/v1/calls

curl --request POST \
  --url https://your-machine.your-tailnet.ts.net/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "deviceId": "phone-7f3a91c2", "to": "+919876543210", "stream": { "url": "wss://agent.example.com/ws", "format": "twilio", "parameters": { "campaign": "renewals" } }, "webhookUrl": "https://example.com/gateway/events" }'

• Your gateway

Queues a call on a phone. The response comes back as soon as the phone has the command; the call’s progress arrives as webhooks (call.dialing, call.active, call.disconnected, …) and in GET /v1/calls/{callId}.

Pass stream to connect the call to your agent’s WebSocket when it’s answered.

Authorizations

• bearer
• apiKey

Request Body^required

Media typeapplication/json

object

deviceId

required

Which phone places the call.

string

to

required

string

<= 64 characters

webhookUrl

Gets this call’s events instead of the default webhook.

string format: uri

metadata

Your own data, stored with the call and returned on reads and webhooks.

object

key

additional properties

any

stream

Your agent’s WebSocket. The gateway connects to it when the call is answered.

object

url

required

ws:// or wss://.

string

format

raw: 16 kHz s16le binary frames. twilio: Twilio Media Streams JSON with 8 kHz mu-law, compatible with Twilio integrations such as Pipecat’s.

string

default: raw

Allowed values: raw twilio

parameters

Sent to your agent in the start message (Twilio customParameters).

object

key

additional properties

string

Examples

Call with an AI agent attached

{
  "deviceId": "phone-7f3a91c2",
  "to": "+919876543210",
  "stream": {
    "url": "wss://agent.example.com/ws",
    "format": "twilio",
    "parameters": {
      "campaign": "renewals"
    }
  },
  "webhookUrl": "https://example.com/gateway/events"
}

Plain call

{
  "deviceId": "phone-7f3a91c2",
  "to": "+919876543210"
}

Responses

202

Call queued and sent to the phone.

Media typeapplication/json

object

call

required

object

id

required

string

deviceId

required

string

remoteNumber

required

string

direction

required

string

Allowed values: outgoing incoming

state

required

string

Allowed values: queued dialing ringing active held ended rejected failed

nativeCallId

string

webhookUrl

string format: uri

metadata

object

key

additional properties

any

stream

Your agent’s WebSocket. The gateway connects to it when the call is answered.

object

url

required

ws:// or wss://.

string

format

raw: 16 kHz s16le binary frames. twilio: Twilio Media Streams JSON with 8 kHz mu-law, compatible with Twilio integrations such as Pipecat’s.

string

default: raw

Allowed values: raw twilio

parameters

Sent to your agent in the start message (Twilio customParameters).

object

key

additional properties

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

answeredAt

string format: date-time

endedAt

string format: date-time

command

required

object

type

string

Allowed value: command

commandId

string format: uuid

callId

string

action

string

Allowed values: dial answer reject hangup hold unhold dtmf

payload

object

key

additional properties

any

media

required

Where to join this call’s audio yourself (WebSocket).

object

path

string

format

object

encoding

string

Allowed value: pcm_s16le

sampleRate

integer

Allowed value: 16000

channels

integer

Allowed value: 1

frameMs

integer

Allowed value: 20

streaming

The phone is sending audio right now.

boolean

Example

{
  "call": {
    "remoteNumber": "+919876543210",
    "direction": "outgoing",
    "state": "queued",
    "stream": {
      "url": "wss://agent.example.com/ws",
      "format": "raw"
    }
  },
  "command": {
    "type": "command",
    "action": "dial"
  },
  "media": {
    "path": "/v1/calls/9b2e/media",
    "format": {
      "encoding": "pcm_s16le",
      "sampleRate": 16000,
      "channels": 1,
      "frameMs": 20
    }
  }
}

400

The request didn’t validate.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

issues

Validation details

Array

Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "invalid request",
    "issues": []
  }
}

401

Missing or invalid API key.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

issues

Validation details

Array

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "invalid API key or session"
  }
}

404

Not found.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

issues

Validation details

Array

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "call not found"
  }
}

409

The phone isn’t connected to the gateway.

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

issues

Validation details

Array

Example

{
  "error": {
    "code": "DEVICE_OFFLINE",
    "message": "device is offline"
  }
}