# 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](https://developers.facebook.com/docs/whatsapp/cloud-api/calling): 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

- 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`](/es/errors#calling_not_supported_in_coex).
- Llamadas activadas en la configuración del número (abajo). Desactivadas → `409` [`calling_not_enabled`](/es/errors#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).

## 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`](/es/errors#call_invalid_state), con el estado actual en `details`.

## Recibir una llamada, de punta a punta

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`](/es/errors#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](/es/webhooks/destinations/)) y atiende:

```js title="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`](/es/errors#call_sdp_invalid).

## Llamar al contacto

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

```bash
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:

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

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`](/es/errors#call_permission_required).

## 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

`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**.

## SIP

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

| Código | Cuándo |
|---|---|
| [`call_permission_required`](/es/errors#call_permission_required) | Meta `138006`: el contacto no dio permiso |
| [`call_rate_limited`](/es/errors#call_rate_limited) | límite de llamadas o de solicitudes de permiso de Meta |
| [`call_error`](/es/errors#call_error) | otro error `138xxx` de Meta, con el detalle en `details[0].message` |
| [`meta_unknown_outcome`](/es/errors#meta_unknown_outcome) | Meta falló en medio de la acción; el webhook corrige el estado después |
