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

# Chamadas

> Ligar no WhatsApp, falar um aviso e desligar — pelo painel ou API, com a mesma simplicidade dos outros canais.

<Tip>
  Chamada WhatsApp na Notifique é o **aviso que toca o telefone**: você liga, fala o que precisa (código, lembrete, confirmação) e desliga — sem montar URA nem call center.
</Tip>

## Em poucas palavras

* **Hoje:** conexão **não oficial** (número pareado por QR). Liga → fala/toca áudio → desliga.
* **Em breve:** a mesma API na conexão **oficial** (Meta), mantendo o mesmo formato simples.
* Use a **mesma instância** que você já usa para mensagens.
* Chave com escopo **`whatsapp:call`** (e `whatsapp:call:read` para só consultar).

<Warning>
  Nesta primeira versão o fluxo é **envio + desligar**: não há URA, transferência nem conversa ao vivo. É para **dizer algo específico** e encerrar.
</Warning>

***

## Quando usar

| Situação                                   | Usar chamadas?                             |
| ------------------------------------------ | ------------------------------------------ |
| Código de verificação **falado** no ouvido | **Sim**                                    |
| Lembrete curto (consulta, boleto, entrega) | **Sim**                                    |
| Atendimento com conversa ao vivo           | **Não** — use mensagens ou voz tradicional |
| Instância **oficial** (Meta)               | Em breve; hoje use **não oficial**         |

Comparação de modos: [Modos de conexão](/whatsapp-api/como-funciona/modos-de-conexao).

***

## O que você pode fazer

<CardGroup cols={2}>
  <Card title="Fazer a chamada" icon="phone">
    `POST /v1/whatsapp/calls` com `speak`, `play` ou `template`.
  </Card>

  <Card title="Listar chamadas" icon="list">
    `GET /v1/whatsapp/calls` com paginação e filtro por instância.
  </Card>

  <Card title="Consultar uma chamada" icon="magnifying-glass">
    `GET /v1/whatsapp/calls/{id}` com status, duração e eventos.
  </Card>

  <Card title="Template com voz" icon="file-audio">
    `type: "template"` usa o texto/voz do template do canal.
  </Card>

  <Card title="Webhooks da chamada" icon="satellite-dish">
    `whatsapp.call.initiated`, `answered`, `completed`, `failed`… sem polling.
  </Card>
</CardGroup>

Rotas e campos: **referência da API** do WhatsApp (seção Chamadas). Eventos: [Webhooks WhatsApp](/whatsapp-api/como-funciona/eventos-do-webhooks#chamadas-whatsappcall).

***

## Antes de começar

| Item                                     | Obrigatório |
| ---------------------------------------- | ----------- |
| Instância **não oficial** e **ACTIVE**   | Sim (hoje)  |
| Escopo **`whatsapp:call`** na chave      | Sim         |
| Texto (`speak`) ou URL de áudio (`play`) | Sim         |

Ainda não pareou? [Quick Start WhatsApp](/whatsapp-api/como-funciona/quick-start) (aba **não oficial**). Escopos: [Escopos da API Key](/whatsapp-api/como-funciona/escopos-api-key).

Substitua `sk_live_xxxxx` pela sua chave e `{instanceId}` pelo id da instância. Base URL: `https://api.notifique.dev`.

<Info>
  A API Key pertence a **um** workspace. Na v1 **não envie** `x-workspace-id`.
</Info>

***

## 1. Fazer uma chamada (falar texto)

Liga, sintetiza a fala e desliga automaticamente.

```http theme={null}
POST /v1/whatsapp/calls
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json
```

```json theme={null}
{
  "from": "clxx...",
  "to": ["5511999999999"],
  "type": "speak",
  "payload": {
    "text": "Olá! Seu código de verificação é 1 2 3 4.",
    "voice": "female"
  }
}
```

**Resposta `202`**

```json theme={null}
{
  "success": true,
  "data": {
    "messageIds": ["clxx_call..."],
    "messageId": "clxx_call...",
    "status": "QUEUED",
    "count": 1,
  }
}
```

***

## 2. Tocar um áudio (`play`)

```json theme={null}
{
  "from": "clxx...",
  "to": ["5511999999999"],
  "type": "play",
  "payload": {
    "mediaUrl": "https://example.com/aviso.mp3"
  }
}
```

A URL precisa ser **pública** e apontar para um arquivo de áudio.

***

## 3. Template com voz

Se você já cadastrou um template do canal de chamada (`whatsapp_call`), use `type: "template"`:

```json theme={null}
{
  "from": "clxx...",
  "to": ["5511999999999"],
  "type": "template",
  "payload": {
    "templateId": "clxx_template...",
    "variables": {
      "1": "1234",
      "name": "Ana"
    }
  }
}
```

A API resolve o texto (e a voz, se houver) e segue como `speak`.

***

## 4. Listar chamadas

```http theme={null}
GET /v1/whatsapp/calls?page=1&limit=20&instanceId=clxx...
Authorization: Bearer sk_live_xxxxx
```

Parâmetros opcionais: `page`, `limit`, `instanceId`.

***

## 5. Consultar uma chamada

```http theme={null}
GET /v1/whatsapp/calls/{id}?includeEvents=true
Authorization: Bearer sk_live_xxxxx
```

Com `includeEvents=true` você vê a linha do tempo (`QUEUED`, `INITIATED`, `COMPLETED`, `NO_ANSWER`, `FAILED`, …).

***

## Status e encerramento

Depois do enfileiramento, a chamada passa por status como `QUEUED` → `INITIATED` → `COMPLETED` (ou `NO_ANSWER` / `FAILED` / `REJECTED`).

O campo `hangupReason` explica o fim (`completed`, `hangup`, `no_answer`, `provider_error`, …).

***

## Próximos passos

* Exemplos tipados na OpenAPI (aba WhatsApp → **Chamadas**)
* [Modos de conexão](/whatsapp-api/como-funciona/modos-de-conexao)
* [Escopos da API Key](/whatsapp-api/como-funciona/escopos-api-key)
* Para voz tradicional (PSTN), veja a [API de Voz](/voice-api/como-funciona/quick-start)