Voice Agents

Place a voice call

Place an outbound voice call answered by the voice agent configured on the sender. Zavu dials the recipient and runs the conversation through its managed voice pipeline (speech recognition, the agent’s LLM, and speech synthesis, with real-time interruption handling).

Requirements:

The Voice Agents feature must be enabled for your team (otherwise 403).
The sender’s agent must have voice.enabled set to true.
Not available with test-mode API keys.

Billing: Voice calls are billed per minute of connected time plus telephony, deducted from your prepaid balance. A short-duration estimate is reserved when the call is placed; you are charged for the actual duration when the call ends.

POST

calls

curl --request POST \
  --url https://api.zavu.dev/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "+56912345678"
}
'

{
  "call": {
    "id": "call_abc123",
    "from": "+13125551212",
    "to": "+56912345678",
    "createdAt": "2023-11-07T05:31:56Z",
    "endReason": "<string>",
    "answeredAt": "2023-11-07T05:31:56Z",
    "endedAt": "2023-11-07T05:31:56Z",
    "durationSeconds": 123,
    "turnCount": 123,
    "transcript": [
      {
        "seq": 123,
        "text": "<string>",
        "startedAt": "2023-11-07T05:31:56Z",
        "endedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "cost": 123,
    "metadata": {},
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "code": "invalid_request",
  "message": "The sender's agent does not have voice enabled"
}

{
  "code": "invalid_request",
  "message": "Phone number is invalid",
  "details": {}
}

{
  "code": "insufficient_balance",
  "message": "Insufficient balance to place this call. Please add funds to continue."
}

{
  "code": "forbidden",
  "message": "Voice Agents is not enabled for this team"
}

{
  "code": "invalid_request",
  "message": "Phone number is invalid",
  "details": {}
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body to place an outbound voice call. The call is answered by the voice agent configured on the sender.

string

required

Recipient phone number in E.164 format.

Example:

"+56912345678"

senderId

string

Sender profile that places the call. Uses the project's default sender if omitted. The sender's agent must have voice enabled.

Example:

"sender_12345"

greeting

string

Overrides the agent's configured greeting for this call only.

Maximum string length: 1000

language

string

Language the agent speaks on this call only, as a BCP-47 tag (en, es, es-ES, pt-BR), or auto to detect the caller's language and follow it. Overrides the agent's configured language for speech recognition, the agent's replies, and the synthesized voice. If the agent uses a custom voice you supplied, that voice is kept and only the language changes. When omitted, the agent's configured language is used.

Maximum string length: 15

Example:

"es-ES"

maxDurationMinutes

integer

Overrides the agent's maximum call duration for this call only.

Required range: 1 <= x <= 120

metadata

object

Arbitrary metadata to associate with the call. Returned on the call object and included in voice webhooks.

Show child attributes

Response

Call accepted and dialing.

call

object

required

Show child attributes

List voice calls

Get voice call

⌘I

curl --request POST \
  --url https://api.zavu.dev/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "+56912345678"
}
'

{
  "call": {
    "id": "call_abc123",
    "from": "+13125551212",
    "to": "+56912345678",
    "createdAt": "2023-11-07T05:31:56Z",
    "endReason": "<string>",
    "answeredAt": "2023-11-07T05:31:56Z",
    "endedAt": "2023-11-07T05:31:56Z",
    "durationSeconds": 123,
    "turnCount": 123,
    "transcript": [
      {
        "seq": 123,
        "text": "<string>",
        "startedAt": "2023-11-07T05:31:56Z",
        "endedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "cost": 123,
    "metadata": {},
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "code": "invalid_request",
  "message": "The sender's agent does not have voice enabled"
}

{
  "code": "invalid_request",
  "message": "Phone number is invalid",
  "details": {}
}

{
  "code": "insufficient_balance",
  "message": "Insufficient balance to place this call. Please add funds to continue."
}

{
  "code": "forbidden",
  "message": "Voice Agents is not enabled for this team"
}

{
  "code": "invalid_request",
  "message": "Phone number is invalid",
  "details": {}
}