Ir al contenido

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.

  • Una conexión de WhatsApp en modo solo API. La coexistencia no tiene llamadas: cualquier acción de llamada en ese modo devuelve 422 calling_not_supported_in_coex.
  • Llamadas activadas en la configuración del número (abajo). Desactivadas → 409 calling_not_enabled.
  • El campo calls suscrito en el webhook de tu app de Meta.
  • Una clave con send (atender, rechazar, colgar, llamar), read (registro y permisos) y admin (configuración).
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.

  1. El contacto llama. Llega el evento call.incoming con data.call.id (cal_…), sdp_type: "offer" y el sdp de la oferta.
  2. Tu cliente WebRTC crea la respuesta SDP a partir de la oferta.
  3. Opcional: POST /v1/calls/{id}/pre-accept con el sdp para que Meta prepare los medios mientras aparece la pantalla de atender.
  4. POST /v1/calls/{id}/accept con el mismo sdp. Después de un pre-accept, un SDP distinto devuelve 409 call_sdp_mismatch sin llamar a Meta.
  5. Para colgar: POST /v1/calls/{id}/terminate. Cuando Meta confirma, llega call.ended con duration_s.

Un cliente mínimo en JavaScript (navegador), que recibe el call.incoming de tu backend (por ejemplo por el WebSocket) y atiende:

atender.js
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.

Meta solo deja que la empresa llame a quien dio permiso de llamada. Verifica antes:

Ventana de terminal
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:

Ventana de 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..." }'

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.

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.

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.

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