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:

An account may call any destination from its first minute, within the daily ceiling: 5 calls a day for an account that has verified nothing, 50 a day on Free once it has verified its identity, added a payment method, settled a deposit or subscribed. Paid plans have no daily call ceiling. Over it, 429 with code daily_limit_exceeded. Full reference: https://docs.zavu.dev/concepts/sending-limits
The call is read by Zavu’s automated risk review before it is dialed, the way a message is (see POST /v1/messages). A call is never held for a person: one the review stops is failed rather than placed late. Repeated refusals suspend the account’s calling, answered with 403 and code sending_suspended.
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",
    "direction": "inbound",
    "from": "+13125551212",
    "to": "+56912345678",
    "status": "queued",
    "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,
        "role": "user",
        "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": "sending_suspended",
  "message": "Sending from this account is suspended after Zavu's automated risk review refused several messages. Contact support to have it reviewed.",
  "details": {
    "dashboardUrl": "/support"
  }
}

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

{
  "code": "daily_limit_exceeded",
  "message": "Daily VOICE limit reached (5/day). Verify your identity or add a payment method to raise it.",
  "details": {
    "limit": 5,
    "remaining": 0,
    "dashboardUrl": "/kyc"
  }
}

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

⌘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",
    "direction": "inbound",
    "from": "+13125551212",
    "to": "+56912345678",
    "status": "queued",
    "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,
        "role": "user",
        "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": "sending_suspended",
  "message": "Sending from this account is suspended after Zavu's automated risk review refused several messages. Contact support to have it reviewed.",
  "details": {
    "dashboardUrl": "/support"
  }
}

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

{
  "code": "daily_limit_exceeded",
  "message": "Daily VOICE limit reached (5/day). Verify your identity or add a payment method to raise it.",
  "details": {
    "limit": 5,
    "remaining": 0,
    "dashboardUrl": "/kyc"
  }
}