> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> WhatsApp voice-call endpoints: fake call (ring and hang up) and audio call

**Auth:** `TokenAccount` or `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotent:** no

The `/api/call/*` module covers placing **voice calls** from the instance. There are currently two operations: the **fake call**, which makes the phone ring for a few seconds and hangs up on its own (no audio), and the **audio call**, which rings and plays a file once the recipient answers. Every route validates instance ownership and accepts `TokenAccount` or `TokenInstance`.

## Available endpoints

| Method | Path                        | Type                              |
| ------ | --------------------------- | --------------------------------- |
| POST   | `/api/call/fake/:instance`  | [Fake Call](/en/api/calls/fake)   |
| POST   | `/api/call/audio/:instance` | [Audio Call](/en/api/calls/audio) |

## Common structure

### Recipient (`number`)

Both endpoints take the destination in the `number` field, which accepts:

* Plain number: `"5511999999999"` (preferred).
* Private JID: `"5511999999999@s.whatsapp.net"`.

Calls are always 1:1 — there is no group call via the API.

### Standard response (200)

Both routes return an envelope with the `callId` assigned by WhatsApp:

```json theme={null}
{
  "success": true,
  "message": "Audio call placed",
  "callId":  "3EB08FCF27E532F1D3D3",
  "number":  "5511999999999"
}
```

The fake call also includes a `duration` field (seconds it rang).

<Note>
  The `callId` identifies the call on WhatsApp. The fake call is ended automatically by the server after `duration` seconds; the audio call only plays the file if the recipient **answers**.
</Note>

## Common errors

| HTTP | Message                                                  |
| ---- | -------------------------------------------------------- |
| 400  | `Instance name is required`                              |
| 400  | `Invalid request body: <detail>`                         |
| 400  | `Number is required`                                     |
| 400  | `Duration must be between 1 and 60 seconds` (fake)       |
| 400  | `Provide exactly one of mediaUrl or mediaBase64` (audio) |
| 404  | `instance not found`                                     |
| 500  | `<failure reason>`                                       |

Error envelope:

```json theme={null}
{
  "success": false,
  "error": { "message": "Number is required" }
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Fake Call" icon="phone" href="/en/api/calls/fake">
    Makes the phone ring for a few seconds and hangs up on its own.
  </Card>

  <Card title="Audio Call" icon="phone-volume" href="/en/api/calls/audio">
    Rings and plays an audio (URL or base64) when answered.
  </Card>
</CardGroup>