Guías
Llamadas en WhatsApp
Recibir y hacer llamadas de voz con la Calling API: Messajo se encarga de la señalización y el audio va directo entre tu cliente WebRTC y Meta.
Messajo maneja solo la señalización de las llamadas de la Calling API: la oferta SDP llega por webhook, respondes por la API y el audio (WebRTC o SIP) pasa directo entre tu sistema y Meta. Messajo nunca transporta medios.
Antes de empezar
Sección titulada «Antes de empezar»- Una conexión de WhatsApp en modo solo API. La coexistencia no tiene llamadas: cualquier acción de llamada en ese modo devuelve
422calling_not_supported_in_coex. - Llamadas activadas en la configuración del número (abajo). Desactivadas →
409calling_not_enabled. - El campo
callssuscrito en el webhook de tu app de Meta. - Una clave con
send(atender, rechazar, colgar, llamar),read(registro y permisos) yadmin(configuración).
Estados de una llamada
Sección titulada «Estados de una llamada»| Dirección | Camino |
|---|---|
Entrante (user_initiated) |
offered → pre_accepted (opcional) → accepted → terminating → ended; o offered/pre_accepted → rejected |
Saliente (business_initiated) |
dialing → ringing → accepted → terminating → ended; o dialing/ringing → rejected |
end_reason dice cómo terminó: completed, missed (nunca atendida), failed, rejected, canceled o unknown (sin noticias de Meta por más de 10 minutos). Una acción que no vale en el estado actual devuelve 409 call_invalid_state, con el estado actual en details.
Recibir una llamada, de punta a punta
Sección titulada «Recibir una llamada, de punta a punta»- El contacto llama. Llega el evento
call.incomingcondata.call.id(cal_…),sdp_type: "offer"y elsdpde la oferta. - Tu cliente WebRTC crea la respuesta SDP a partir de la oferta.
- Opcional:
POST /v1/calls/{id}/pre-acceptcon elsdppara que Meta prepare los medios mientras aparece la pantalla de atender. POST /v1/calls/{id}/acceptcon el mismosdp. Después de unpre-accept, un SDP distinto devuelve409call_sdp_mismatchsin llamar a Meta.- Para colgar:
POST /v1/calls/{id}/terminate. Cuando Meta confirma, llegacall.endedconduration_s.
Un cliente mínimo en JavaScript (navegador), que recibe el call.incoming de tu backend (por ejemplo por el WebSocket) y atiende:
const API = "https://api.messajo.com/v1";
// Llama a través de tu backend: la clave de API nunca va al navegador.async function callApi(path, body) { const res = await fetch(`/mi-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 a que los candidatos ICE entren en el 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`, {}) };}El backend solo reenvía el cuerpo a ${API}/calls/{id}/… con Authorization: Bearer $MESSAJO_API_KEY. El SDP es texto de hasta 64 KiB, empieza con v=0 y puede usar saltos LF o CRLF; si no, 400 call_sdp_invalid.
Llamar al contacto
Sección titulada «Llamar al contacto»Meta solo deja que la empresa llame a quien dio permiso de llamada. Verifica antes:
curl "https://api.messajo.com/v1/connections/conn_.../call-permissions?to=5511999990001" \ -H "Authorization: Bearer $MESSAJO_API_KEY"La respuesta trae status (no_permission, temporary, permanent o rejected), expires_at y las actions que Meta permite ahora, con sus límites. Sin permiso, pídelo con un mensaje interactive del tipo call_permission_request (solo body.text, dentro de la ventana de 24 h) o con una plantilla que tenga el componente de solicitud de permiso. La respuesta del contacto llega como call.permission_updated. Meta limita las solicitudes a 1 cada 24 h y 2 cada 7 días para el mismo contacto.
Con permiso, llama con la oferta SDP de tu 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..." }'Devuelve 201 con la llamada en dialing. La respuesta SDP del contacto llega en call.sdp_answer; los pasos siguientes, en call.status. Sin permiso → 403 call_permission_required.
Eventos
Sección titulada «Eventos»| Tipo | Cuándo |
|---|---|
call.incoming |
el contacto llamó (con el sdp de la oferta) |
call.sdp_answer |
el contacto atendió tu llamada (con el sdp de la respuesta) |
call.status |
RINGING, ACCEPTED, REJECTED |
call.ended |
fin, con end_reason, start_time, end_time y duration_s |
call.permission_updated |
cambió el permiso de llamada del contacto (status, is_permanent, expires_at) |
El SDP contiene direcciones IP del contacto. Va en los eventos, pero la lectura por la API (GET /v1/calls, GET /v1/calls/{id}) solo muestra has_sdp, y Messajo borra el SDP 1 hora después del fin de la llamada. El panel muestra el registro en Llamadas.
Configuración del número
Sección titulada «Configuración del número»GET /v1/connections/{id}/calling-settings lee y PUT (clave admin) cambia, por partes: activar o desactivar (status), mostrar el ícono de llamar (call_icon_visibility), ofrecer devolución de llamada (callback_permission_status), el horario de atención (call_hours, con zona horaria, días de la semana y feriados) y SIP. En el panel: conexión → Llamadas.
Para llevar el audio a una centralita en lugar de un cliente WebRTC, configura sip.servers (hostname público y puerto). Messajo solo guarda la configuración y la pasa a Meta. La contraseña SIP que genera Meta viene una vez, solo en un GET …/calling-settings?include_sip_credentials=true hecho con clave admin: Messajo no la guarda ni la registra en logs.
Límites y errores
Sección titulada «Límites y errores»| Código | Cuándo |
|---|---|
call_permission_required |
Meta 138006: el contacto no dio permiso |
call_rate_limited |
límite de llamadas o de solicitudes de permiso de Meta |
call_error |
otro error 138xxx de Meta, con el detalle en details[0].message |
meta_unknown_outcome |
Meta falló en medio de la acción; el webhook corrige el estado después |