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.
Antes de começar
Seção intitulada “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
422calling_not_supported_in_coex. - Ligações ligadas nas configurações do número (abaixo). Desligadas →
409calling_not_enabled. - O campo
callsassinado no webhook do app da Meta. - Uma chave com
send(atender, recusar, encerrar, ligar),read(log e permissões) eadmin(configurações).
Estados de uma ligação
Seção intitulada “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, com o estado atual em details.
Receber uma ligação, de ponta a ponta
Seção intitulada “Receber uma ligação, de ponta a ponta”- O contato liga. Chega o evento
call.incomingcomdata.call.id(cal_…),sdp_type: "offer"e osdpda oferta. - Seu cliente WebRTC cria a resposta SDP a partir da oferta.
- Opcional:
POST /v1/calls/{id}/pre-acceptcom osdppara a Meta já montar a mídia enquanto a tela de atender aparece. POST /v1/calls/{id}/acceptcom o mesmosdp. Depois de umpre-accept, um SDP diferente volta409call_sdp_mismatchsem chamar a Meta.- Para desligar:
POST /v1/calls/{id}/terminate. Quando a Meta confirma, chegacall.endedcomduration_s.
Um cliente mínimo em JavaScript (navegador), que recebe o call.incoming do seu backend (por exemplo pelo WebSocket) e atende:
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.
Ligar para o contato
Seção intitulada “Ligar para o contato”A Meta só deixa a empresa ligar para quem deu permissão de chamada. Confira antes:
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:
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.
Eventos
Seção intitulada “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
Seção intitulada “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.
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
Seção intitulada “Limites e erros”| 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 |