Skip to content
DashboardGet API key

Place a voice call

View .md
POST

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://www.zavu.dev/docs/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.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

  • tostringrequired

    Recipient phone number in E.164 format.

  • senderIdstring

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

  • greetingstring

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

    Limitsmax length 1000
  • languagestring

    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.

    Limitsmax length 15
  • maxDurationMinutesinteger

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

    Limitsmin 1 · max 120
  • metadataobject

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

    1 properties
    • {key}string

Responses

202Call accepted and dialing.
  • callobjectrequired
    15 properties
    • idstringrequired
    • directionstringrequired

      Whether the call was placed by Zavu (outbound) or received from a caller (inbound).

      One ofinboundoutbound
    • fromstringrequired

      Caller phone number in E.164 format. Your sender's number for outbound calls; the caller's number for inbound calls.

    • tostringrequired

      Callee phone number in E.164 format.

    • statusstringrequired

      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.

      One ofqueuedringingin_progresscompletedfailedbusyno_answercanceled
    • endReasonstringnullable

      Why the call ended (e.g. agent_ended, max_duration, transfer, hangup). Present once the call is no longer active.

    • answeredAtstring<date-time>nullable

      When the call was answered.

    • endedAtstring<date-time>nullable

      When the call ended.

    • durationSecondsintegernullable

      Billable talk time in seconds, measured from answer to hangup.

    • turnCountintegernullable

      Number of conversation turns exchanged during the call.

    • transcriptobject[]

      Ordered transcript of the call. Included when retrieving a single call; omitted from list responses.

      5 properties
      • seqintegerrequired

        Ordinal position of the turn within the call, starting at 0.

      • rolestringrequired

        Who produced the turn. tool records a tool call the agent made during the conversation.

        One ofuserassistanttool
      • textstringrequired

        Transcribed speech for user and assistant turns, or a JSON summary of the tool call for tool turns.

      • startedAtstring<date-time>nullable

        When the turn started.

      • endedAtstring<date-time>nullable

        When the turn ended.

    • costnumbernullable

      Total cost of the call in USD, combining the managed voice pipeline per-minute charge, telephony, and, on an agent that runs a premium model, that model's tokens. Available once the call has ended. Tokens are charged between 30 minutes and 24 hours after the call ends, so the figure can grow until then.

    • metadataobject

      Arbitrary metadata you attached when creating the call.

      1 properties
      • {key}string
    • createdAtstring<date-time>required
    • updatedAtstring<date-time>
400Invalid request, the sender's agent does not have voice enabled, or voice calls are not available in test mode.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
402Insufficient balance (`insufficient_balance`), or the call would exceed the team's monthly spend cap (`spend_cap_reached`, with `details.dashboardUrl`).
  • codestringrequired
  • messagestringrequired
  • detailsobject
403This account's calling is suspended after Zavu's automated review refused several of its sends (`sending_suspended`), or the destination is not one this account may call yet (`destination_not_verified`).
  • codestringrequired
  • messagestringrequired
  • detailsobject
404Sender or agent not found.
  • codestringrequired
  • messagestringrequired
  • detailsobject
429Daily call limit reached. An account that has verified nothing may place 5 calls a day, and 50 on a Free plan once it has verified its identity, added a payment method, settled a deposit or subscribed. Paid plans have no daily call ceiling.
  • codestringrequired
  • messagestringrequired
  • detailsobject