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

# Introdução às Ligações

As integrações do tipo **HyperMeow (com ligações)** fazem e recebem ligações de voz do WhatsApp. Pela API você pode deixar um sistema externo (um bot, uma URA) atender essas ligações, falar com o contato e, quando quiser, devolver a ligação para a fila de atendimento.

## Como funciona

1. **Cadastre um webhook `CALL_ROUTING`** na integração, pela rota [Cadastrar Webhook](https://docs.multchats.com/api-reference/integration/create-webhook.md) com `"type": "CALL_ROUTING"`, ou pelo painel em Integrações → Webhooks. Só pode existir um por integração.
2. Com esse webhook cadastrado, **as ligações recebidas não aparecem para os atendentes**. Cada ligação dispara o [webhook de ligações](https://docs.multchats.com/api-reference/webhook/call-webhook.md) com os dados de quem está ligando.
3. Sua aplicação [atende](https://docs.multchats.com/api-reference/call/accept-call.md) (ou [recusa](https://docs.multchats.com/api-reference/call/reject-call.md)) a ligação e conecta no [WebSocket de áudio](#áudio-da-ligação) para ouvir e falar com o contato.
4. Para passar a ligação para um atendente, use [Transferir ligação para a fila](https://docs.multchats.com/api-reference/call/transfer-call-to-queue.md). A ligação passa a tocar para os atendentes e o primeiro que atender fica com ela.
5. Enquanto espera na fila, o contato ouve em loop o **áudio de espera** cadastrado no webhook (`holdAudioUrl`). Sem áudio cadastrado, o contato fica em silêncio.

Também é possível [ligar para um número](https://docs.multchats.com/api-reference/call/start-call.md) pela API: a ligação fica com a sua aplicação do mesmo jeito, e pode ser transferida para a fila.

> [!NOTE]
>
> Uma ligação na fila não tem tempo limite: ela espera até um atendente assumir, o contato desligar ou a API [encerrar a ligação](https://docs.multchats.com/api-reference/call/hangup-call.md).

## Estados da ligação

| `state` | Descrição |
| - | - |
| `ringing` | Tocando, ainda não atendida |
| `connecting` | Atendida, conectando o áudio |
| `active` | Em andamento |
| `ended` | Encerrada |

O campo `answeredBy` diz com quem a ligação está: `api` quando é da sua aplicação, o ID do atendente quando um atendente assumiu, ou `null` quando ninguém atendeu. `queued` é `true` depois que a API transferiu a ligação para a fila.

## Áudio da ligação

O áudio é trocado por um WebSocket, aberto depois que a ligação foi atendida pela API (ou depois que o contato atendeu, numa ligação iniciada pela API):

```
wss://api.multchats.com/v2/call/audio?integrationId=<integrationId>&callId=<callId>
```

A autenticação é a mesma das outras rotas: cabeçalho `Authorization: Bearer <token>`, ou o parâmetro `?token=<token>` para clientes que não conseguem enviar cabeçalhos no WebSocket.

As mensagens são binárias nos dois sentidos, em **PCM 16 bits little-endian, mono, 16 kHz**, em quadros de 960 amostras (60 ms, 1920 bytes):

* o que você **recebe** é a voz do contato;
* o que você **envia** é tocado para o contato.

O WebSocket é fechado (código `1000`) quando a ligação termina ou é transferida para a fila. Abrir um segundo WebSocket para a mesma ligação substitui o primeiro.

| Status na conexão | Motivo |
| - | - |
| `401` | Token ausente ou inválido |
| `400` | `integrationId` ou `callId` ausente, ou ligação não encontrada |
| `409` | A ligação não está com a API: ainda não foi atendida (`CALL_NOT_ANSWERED`), já está na fila (`CALL_IN_QUEUE`) ou com um atendente (`CALL_ALREADY_ANSWERED`) |

### Exemplo (Node.js)

```js theme={null}
import WebSocket from "ws";

const socket = new WebSocket(
  "wss://api.multchats.com/v2/call/audio?integrationId=<integrationId>&callId=<callId>",
  { headers: { Authorization: "Bearer <token>" } },
);

socket.on("message", (frame) => {
  // frame: Buffer com 60 ms da voz do contato (PCM s16le, 16 kHz, mono)
  const resposta = processarAudio(frame);
  if (resposta) socket.send(resposta); // tocado para o contato
});

socket.on("close", () => {
  // a ligação terminou ou foi transferida para a fila
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.