# 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).

`POST https://api.zavu.dev/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:**
- 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.

## Body

- `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.
  - `{key}` (string)

## Responses

### 202

Call accepted and dialing.

- `call` (object, required)
  - `id` (string, required)
  - `direction` (string, required): Whether the call was placed by Zavu (outbound) or received from a caller (inbound). One of: `inbound`, `outbound`.
  - `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` (string, 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. One of: `queued`, `ringing`, `in_progress`, `completed`, `failed`, `busy`, `no_answer`, `canceled`.
  - `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` (object[]): 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` (string, required): Who produced the turn. `tool` records a tool call the agent made during the conversation. One of: `user`, `assistant`, `tool`.
    - `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, 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.
  - `metadata` (object): Arbitrary metadata you attached when creating the call.
    - `{key}` (string)
  - `createdAt` (string<date-time>, required)
  - `updatedAt` (string<date-time>)

### 400

Invalid request, the sender's agent does not have voice enabled, or voice calls are not available in test mode.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 402

Insufficient balance (`insufficient_balance`), or the call would exceed the team's monthly spend cap (`spend_cap_reached`, with `details.dashboardUrl`).

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 403

This 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`).

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 404

Sender or agent not found.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 429

Daily 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.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X POST "https://api.zavu.dev/v1/calls" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+56912345678"
}'
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.calls.create({
  to: "+56912345678",
});

console.log(result);
```