# Ligações no WhatsApp

> Receber e fazer ligações de voz pela Calling API: o Messajo cuida da sinalização, o áudio vai direto entre o seu cliente WebRTC e a Meta.

O Messajo trata **só a sinalização** das ligações da [Calling API](https://developers.facebook.com/docs/whatsapp/cloud-api/calling): a oferta SDP chega por webhook, você responde pela API e o áudio (WebRTC ou SIP) passa direto entre o seu sistema e a Meta. O Messajo nunca carrega mídia.

## Antes de começar

- Uma conexão de WhatsApp em modo **só API**. A coexistência não tem ligações: qualquer chamada de ligação nesse modo volta `422` [`calling_not_supported_in_coex`](/errors#calling_not_supported_in_coex).
- Ligações ligadas nas configurações do número (abaixo). Desligadas → `409` [`calling_not_enabled`](/errors#calling_not_enabled).
- O campo `calls` assinado no webhook do app da Meta.
- Uma chave com `send` (atender, recusar, encerrar, ligar), `read` (log e permissões) e `admin` (configurações).

## Estados de uma ligação

| Direção | Caminho |
|---|---|
| Recebida (`user_initiated`) | `offered` → `pre_accepted` (opcional) → `accepted` → `terminating` → `ended`; ou `offered`/`pre_accepted` → `rejected` |
| Feita (`business_initiated`) | `dialing` → `ringing` → `accepted` → `terminating` → `ended`; ou `dialing`/`ringing` → `rejected` |

`end_reason` diz como terminou: `completed`, `missed` (nunca atendida), `failed`, `rejected`, `canceled` ou `unknown` (sem notícia da Meta por mais de 10 minutos). Ação que não vale no estado atual devolve `409` [`call_invalid_state`](/errors#call_invalid_state), com o estado atual em `details`.

## Receber uma ligação, de ponta a ponta

1. O contato liga. Chega o evento `call.incoming` com `data.call.id` (`cal_…`), `sdp_type: "offer"` e o `sdp` da oferta.
2. Seu cliente WebRTC cria a resposta SDP a partir da oferta.
3. Opcional: `POST /v1/calls/{id}/pre-accept` com o `sdp` para a Meta já montar a mídia enquanto a tela de atender aparece.
4. `POST /v1/calls/{id}/accept` com o **mesmo** `sdp`. Depois de um `pre-accept`, um SDP diferente volta `409` [`call_sdp_mismatch`](/errors#call_sdp_mismatch) sem chamar a Meta.
5. Para desligar: `POST /v1/calls/{id}/terminate`. Quando a Meta confirma, chega `call.ended` com `duration_s`.

Um cliente mínimo em JavaScript (navegador), que recebe o `call.incoming` do seu backend (por exemplo pelo [WebSocket](/webhooks/destinations/)) e atende:

```js title="atender.js"
const API = "https://api.messajo.com/v1";

// Chame do seu backend: a chave de API nunca vai para o navegador.
async function callApi(path, body) {
  const res = await fetch(`/meu-backend/messajo${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`Messajo ${res.status}`);
  return res.json();
}

export async function onIncomingCall(event) {
  const { id, sdp } = event.data.call; // call.incoming
  const pc = new RTCPeerConnection();
  const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
  for (const track of mic.getTracks()) pc.addTrack(track, mic);
  pc.ontrack = ({ streams }) => {
    const audio = new Audio();
    audio.srcObject = streams[0];
    audio.play();
  };

  await pc.setRemoteDescription({ type: "offer", sdp });
  await pc.setLocalDescription(await pc.createAnswer());
  // espera os candidatos ICE entrarem no SDP local
  await new Promise((resolve) => {
    if (pc.iceGatheringState === "complete") return resolve();
    pc.onicegatheringstatechange = () =>
      pc.iceGatheringState === "complete" && resolve();
  });

  const answer = pc.localDescription.sdp;
  await callApi(`/calls/${id}/pre-accept`, { sdp: answer });
  await callApi(`/calls/${id}/accept`, { sdp: answer });
  return { pc, hangUp: () => callApi(`/calls/${id}/terminate`, {}) };
}
```

O backend só repassa o corpo para `${API}/calls/{id}/…` com `Authorization: Bearer $MESSAJO_API_KEY`. O SDP é texto até 64 KiB, começa com `v=0` e pode vir com quebras LF ou CRLF; fora disso, `400` [`call_sdp_invalid`](/errors#call_sdp_invalid).

## Ligar para o contato

A Meta só deixa a empresa ligar para quem deu **permissão de chamada**. Confira antes:

```bash
curl "https://api.messajo.com/v1/connections/conn_.../call-permissions?to=5511999990001" \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

A resposta traz `status` (`no_permission`, `temporary`, `permanent` ou `rejected`), `expires_at` e as `actions` que a Meta permite agora, com os limites. Sem permissão, peça com uma mensagem `interactive` do tipo `call_permission_request` (só `body.text`, dentro da janela de 24 h) ou com um template que tenha o componente de pedido de permissão. A resposta do contato chega como `call.permission_updated`. A Meta limita os pedidos a 1 por 24 h e 2 por 7 dias para o mesmo contato.

Com permissão, ligue com a oferta SDP do seu cliente WebRTC:

```bash
curl https://api.messajo.com/v1/calls \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connection_id": "conn_...", "to": "5511999990001", "sdp": "v=0\r\n..." }'
```

Volta `201` com a ligação em `dialing`. A resposta SDP do contato chega em `call.sdp_answer`; os passos seguintes, em `call.status`. Sem permissão → `403` [`call_permission_required`](/errors#call_permission_required).

## Eventos

| Tipo | Quando |
|---|---|
| `call.incoming` | o contato ligou (com `sdp` da oferta) |
| `call.sdp_answer` | o contato atendeu uma ligação sua (com `sdp` da resposta) |
| `call.status` | `RINGING`, `ACCEPTED`, `REJECTED` |
| `call.ended` | fim, com `end_reason`, `start_time`, `end_time` e `duration_s` |
| `call.permission_updated` | a permissão de chamada do contato mudou (`status`, `is_permanent`, `expires_at`) |

O SDP tem endereços IP do contato. Ele vai nos eventos, mas a leitura pela API (`GET /v1/calls`, `GET /v1/calls/{id}`) mostra só `has_sdp`, e o Messajo apaga o SDP 1 hora depois do fim da ligação. O painel mostra o log em **Ligações**.

## Configurações do número

`GET /v1/connections/{id}/calling-settings` lê e `PUT` (chave `admin`) altera, em partes: ligar ou desligar (`status`), mostrar o ícone de ligar (`call_icon_visibility`), oferecer retorno de ligação (`callback_permission_status`), o horário de atendimento (`call_hours`, com fuso, dias da semana e feriados) e o SIP. No painel: conexão → **Ligações**.

## SIP

Para levar o áudio a um PBX em vez de um cliente WebRTC, configure `sip.servers` (hostname público e porta). O Messajo só grava a configuração e a repassa à Meta. A senha SIP que a Meta gera vem **uma vez**, só num `GET …/calling-settings?include_sip_credentials=true` feito por chave `admin`: o Messajo não grava nem registra em log.

## Limites e erros

| Código | Quando |
|---|---|
| [`call_permission_required`](/errors#call_permission_required) | Meta `138006`: o contato não deu permissão |
| [`call_rate_limited`](/errors#call_rate_limited) | limite de ligações ou de pedidos de permissão da Meta |
| [`call_error`](/errors#call_error) | outro erro `138xxx` da Meta, com o detalhe em `details[0].message` |
| [`meta_unknown_outcome`](/errors#meta_unknown_outcome) | a Meta falhou no meio da ação; o webhook acerta o estado depois |
