Pular para o conteúdo

Guias

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

  • 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.
  • Ligações ligadas nas configurações do número (abaixo). Desligadas → 409 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).
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, com o estado atual em details.

  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 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) e atende:

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.

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

Janela do terminal
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:

Janela do terminal
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.

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.

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.

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.

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