> ## Documentation Index > Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /v1/calls openapi: 3.0.3 info: title: Zavu Unified Messaging Layer API version: 0.2.0 description: > Unified multi-channel messaging API for Zavu. Supported channels: - **SMS**: Simple text messages - **WhatsApp**: Rich messaging with media, buttons, lists, CTA URL buttons, and templates - **Telegram**: Bot messaging with text, media, and interactive elements - **Email**: Transactional emails via Amazon SES Design goals: - Simple `send()` entrypoint for developers - Project-level authentication via Bearer token - Support for all WhatsApp message types (text, image, video, audio, document, sticker, location, contact, buttons, list, cta_url, reaction, template) - If a non-text message type is sent, WhatsApp channel is used automatically - 24-hour WhatsApp conversation window enforcement - Universal `to` field accepts phone numbers (E.164), email addresses, or numeric chat IDs (Telegram/Instagram/Messenger) servers: - url: https://api.zavu.dev security: - bearerAuth: [] paths: /v1/calls: post: tags: - Voice Agents summary: Place a voice call description: >- 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. operationId: createCall requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VoiceCallCreateRequest' examples: basic: summary: Outbound call with the default sender value: to: '+56912345678' language: summary: Outbound call in a different language value: to: '+56912345678' language: es-ES full: summary: Outbound call with overrides value: to: '+56912345678' senderId: sender_12345 greeting: Hi, this is Acme calling about your appointment. language: en-US maxDurationMinutes: 10 metadata: campaign: appointment_reminders responses: '202': description: Call accepted and dialing. content: application/json: schema: $ref: '#/components/schemas/VoiceCallResponse' '400': description: >- Invalid request, the sender's agent does not have voice enabled, or voice calls are not available in test mode. content: application/json: schema: $ref: '#/components/schemas/Error' examples: voice_not_enabled: summary: Agent voice not enabled value: code: invalid_request message: The sender's agent does not have voice enabled '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Insufficient balance. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: insufficient_balance message: >- Insufficient balance to place this call. Please add funds to continue. '403': description: Voice Agents is not enabled for this team. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: forbidden message: Voice Agents is not enabled for this team '404': description: Sender or agent not found. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: VoiceCallCreateRequest: type: object description: >- Request body to place an outbound voice call. The call is answered by the voice agent configured on the sender. required: - to properties: to: type: string description: Recipient phone number in E.164 format. example: '+56912345678' senderId: type: string description: >- 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: type: string description: Overrides the agent's configured greeting for this call only. maxLength: 1000 language: type: string description: >- 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. maxLength: 15 example: es-ES maxDurationMinutes: type: integer description: Overrides the agent's maximum call duration for this call only. minimum: 1 maximum: 120 metadata: type: object additionalProperties: type: string description: >- Arbitrary metadata to associate with the call. Returned on the call object and included in voice webhooks. VoiceCallResponse: type: object required: - call properties: call: $ref: '#/components/schemas/VoiceCall' Error: type: object required: - code - message properties: code: type: string example: invalid_request message: type: string example: Phone number is invalid details: type: object additionalProperties: true VoiceCall: type: object required: - id - direction - from - to - status - createdAt properties: id: type: string example: call_abc123 direction: $ref: '#/components/schemas/VoiceCallDirection' from: type: string description: >- Caller phone number in E.164 format. Your sender's number for outbound calls; the caller's number for inbound calls. example: '+13125551212' to: type: string description: Callee phone number in E.164 format. example: '+56912345678' status: $ref: '#/components/schemas/VoiceCallStatus' endReason: type: string nullable: true description: >- Why the call ended (e.g. `agent_ended`, `max_duration`, `transfer`, `hangup`). Present once the call is no longer active. answeredAt: type: string format: date-time nullable: true description: When the call was answered. endedAt: type: string format: date-time nullable: true description: When the call ended. durationSeconds: type: integer nullable: true description: Billable talk time in seconds, measured from answer to hangup. turnCount: type: integer nullable: true description: Number of conversation turns exchanged during the call. transcript: type: array description: >- Ordered transcript of the call. Included when retrieving a single call; omitted from list responses. items: $ref: '#/components/schemas/VoiceCallTurn' cost: type: number nullable: true description: >- Total cost of the call in USD, combining the managed voice pipeline per-minute charge and telephony. Available once the call has ended. metadata: type: object additionalProperties: type: string description: Arbitrary metadata you attached when creating the call. createdAt: type: string format: date-time updatedAt: type: string format: date-time VoiceCallDirection: type: string description: >- Whether the call was placed by Zavu (outbound) or received from a caller (inbound). enum: - inbound - outbound VoiceCallStatus: type: string description: |- 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. enum: - queued - ringing - in_progress - completed - failed - busy - no_answer - canceled VoiceCallTurn: type: object description: A single turn in a voice call transcript. required: - seq - role - text properties: seq: type: integer description: Ordinal position of the turn within the call, starting at 0. role: type: string description: >- Who produced the turn. `tool` records a tool call the agent made during the conversation. enum: - user - assistant - tool text: type: string description: >- Transcribed speech for `user` and `assistant` turns, or a JSON summary of the tool call for `tool` turns. startedAt: type: string format: date-time nullable: true description: When the turn started. endedAt: type: string format: date-time nullable: true description: When the turn ended. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````