---
title: "Place a voice call"
method: POST
path: "/v1/calls"
tags: ["Voice Agents"]
---

# Place a voice call

`POST /v1/calls`

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`).
- An account that has verified nothing may only call the phone numbers the project has verified (`403` with code `destination_not_verified`, and `details.verifiedNumbers` lists them), and at most 5 calls a day (`429` with code `daily_limit_exceeded`). A number is verified from the dashboard's Sandbox screen by sending the pre-filled WhatsApp message from that phone; the same verification covers SMS and calls. Verify your identity, add a payment method, settle a deposit or subscribe to call any destination. That raises the ceiling to 50 calls a day on Free; paid plans have no daily call ceiling. Full reference: https://docs.zavu.dev/concepts/sending-limits
- 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.

## Request body

- VoiceCallCreateRequest — Request body to place an outbound voice call. The call is answered by the voice agent configured on the sender.
  - `to` string, required — Recipient phone number in E.164 format.
  - `senderId` string — Sender profile that places the call. Uses the project's default sender if omitted. The sender's agent must have voice enabled.
  - `greeting` string — Overrides the agent's configured greeting for this call only.
  - `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.
  - `maxDurationMinutes` integer — Overrides the agent's maximum call duration for this call only.
  - `metadata` object — Arbitrary metadata to associate with the call. Returned on the call object and included in voice webhooks.

## Response `202`

Call accepted and dialing.

- VoiceCallResponse
  - `call` VoiceCall, required
    - `id` string, required
    - `direction` 'inbound' | 'outbound', required — Whether the call was placed by Zavu (outbound) or received from a caller (inbound).
    - `from` string, required — Caller phone number in E.164 format. Your sender's number for outbound calls; the caller's number for inbound calls.
    - `to` string, required — Callee phone number in E.164 format.
    - `status` 'queued' | 'ringing' | 'in_progress' | 'completed' | 'failed' | 'busy' | 'no_answer' | 'canceled', required — Lifecycle status of a voice call. - `queued`: outbound call created, not yet dialing. - `ringing`: dialing (outbound) or received and ringing (inbound). - `in_progress`: answered, the agent is connected. - `completed`: ended after a conversation. - `failed`: could not be completed. - `busy`: the line was busy. - `no_answer`: rang but was not answered. - `canceled`: canceled before it was answered.
    - `endReason` string, nullable — Why the call ended (e.g. `agent_ended`, `max_duration`, `transfer`, `hangup`). Present once the call is no longer active.
    - `answeredAt` string, date-time, nullable — When the call was answered.
    - `endedAt` string, date-time, nullable — When the call ended.
    - `durationSeconds` integer, nullable — Billable talk time in seconds, measured from answer to hangup.
    - `turnCount` integer, nullable — Number of conversation turns exchanged during the call.
    - `transcript` VoiceCallTurn[] — Ordered transcript of the call. Included when retrieving a single call; omitted from list responses.
      - `seq` integer, required — Ordinal position of the turn within the call, starting at 0.
      - `role` 'user' | 'assistant' | 'tool', required — Who produced the turn. `tool` records a tool call the agent made during the conversation.
      - `text` string, required — Transcribed speech for `user` and `assistant` turns, or a JSON summary of the tool call for `tool` turns.
      - `startedAt` string, date-time, nullable — When the turn started.
      - `endedAt` string, date-time, nullable — When the turn ended.
    - `cost` number, nullable — Total cost of the call in USD, combining the managed voice pipeline per-minute charge and telephony. Available once the call has ended.
    - `metadata` object — Arbitrary metadata you attached when creating the call.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time

## Other responses

- `400` — Invalid request, the sender's agent does not have voice enabled, or voice calls are not available in test mode.
- `401` — Unauthorized.
- `402` — Insufficient balance.
- `403` — Voice Agents is not enabled for this team, or the account may not call this number yet. `destination_not_verified` means the account is unverified and voice reaches only numbers the project has verified: `details.verifiedNumbers` lists them.
- `404` — Sender or agent not found.
- `429` — Daily call limit reached. An account that has verified nothing may place 5 calls a day, and 50 on a Free plan once past that floor. Paid plans have no daily call ceiling.

## Changes

- **2026-08-29** `581fdea6fa36` — 1 info
  - added the non-success response with the status `429`
- **2026-07-25** `5cce7d79055c` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/changes/v1/calls/post.md)

---

[API](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api.md) · [All operations](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/revisions/b343da23d9f4?raw)