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

# Visão Geral

> Endpoints de chamadas de voz no WhatsApp: chamada fake (toca e desliga) e chamada com áudio

**Auth:** `TokenAccount` ou `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** não

O módulo `/api/call/*` cobre o disparo de **chamadas de voz** a partir da instância. Hoje há duas operações: a **chamada fake**, que faz o telefone tocar por alguns segundos e desliga sozinha (sem áudio), e a **chamada com áudio**, que liga e reproduz um arquivo quando o destinatário atende. Todas as rotas validam a ownership da instância e aceitam `TokenAccount` ou `TokenInstance`.

## Endpoints disponíveis

| Método | Path                        | Tipo                                     |
| ------ | --------------------------- | ---------------------------------------- |
| POST   | `/api/call/fake/:instance`  | [Chamada Fake](/pt/api/calls/fake)       |
| POST   | `/api/call/audio/:instance` | [Chamada com Áudio](/pt/api/calls/audio) |

## Estrutura comum

### Destinatário (`number`)

Ambos os endpoints recebem o destino no campo `number`, que aceita:

* Número simples: `"5511999999999"` (preferido).
* JID privado: `"5511999999999@s.whatsapp.net"`.

As chamadas são sempre 1:1 — não há chamada para grupo via API.

### Resposta padrão (200)

As duas rotas retornam um envelope com o `callId` atribuído pelo WhatsApp:

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

A chamada fake inclui também o campo `duration` (segundos que ficou tocando).

<Note>
  O `callId` identifica a chamada no WhatsApp. A chamada fake é encerrada automaticamente pelo servidor após `duration` segundos; a chamada com áudio só reproduz o arquivo se o destinatário **atender**.
</Note>

## Erros comuns

| HTTP | Mensagem                                                 |
| ---- | -------------------------------------------------------- |
| 400  | `Instance name is required`                              |
| 400  | `Invalid request body: <detalhe>`                        |
| 400  | `Number is required`                                     |
| 400  | `Duration must be between 1 and 60 seconds` (fake)       |
| 400  | `Provide exactly one of mediaUrl or mediaBase64` (áudio) |
| 404  | `instance not found`                                     |
| 500  | `<motivo da falha>`                                      |

Envelope de erro:

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

## Próximos passos

<CardGroup cols={2}>
  <Card title="Chamada Fake" icon="phone" href="/pt/api/calls/fake">
    Faz o telefone tocar por alguns segundos e desliga sozinha.
  </Card>

  <Card title="Chamada com Áudio" icon="phone-volume" href="/pt/api/calls/audio">
    Liga e reproduz um áudio (URL ou base64) quando atendem.
  </Card>
</CardGroup>