---
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`).
- 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.
- `404` — Sender or agent not found.

---

[API](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api.md) · [All operations](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zavudev/zavu-unified-messaging-layer-api/versions/07b87b6ae707/schema)