Saltar al contenido principal

En qué consiste

La Calling API de WhatsApp de YCloud gestiona la señalización de llamadas de voz entre un usuario de WhatsApp y un número de teléfono comercial. Tu aplicación intercambia el SDP a través de YCloud, mientras que tu implementación de WebRTC se encarga de la conexión de audio. Las llamadas pueden iniciarse en cualquiera de las dos direcciones:
  • Iniciadas por el usuario: Un usuario de WhatsApp llama a tu empresa. Tu aplicación recibe una oferta y acepta o rechaza la llamada.
  • Iniciadas por la empresa: Tu aplicación crea una oferta y solicita a YCloud que llame a un usuario de WhatsApp.
La Calling API gestiona la señalización de llamadas, no la pila multimedia de WebRTC. Tu aplicación es responsable de configurar la conexión entre pares, la captura y reproducción de audio, la generación de SDP y la liberación de recursos de WebRTC.

Mapa de la API

Las Calling APIs y los eventos de webhook siguen el mismo ciclo de vida, pero no forman una secuencia única que se aplique a todas las llamadas. Completa la configuración compartida y luego sigue el flujo iniciado por el usuario o iniciado por la empresa. Usa el ID de llamada, wacid, para correlacionar cada operación y evento.

Configuración compartida

Llamadas iniciadas por el usuario

Llamadas iniciadas por la empresa

Finalización de llamadas compartida

Procesamiento multimedia opcional

Estas tablas describen el flujo de trabajo de la aplicación. No garantizan que los webhooks se entreguen en el mismo orden que las filas. Correlaciona los eventos mediante wacid y gestiona las entregas repetidas de forma idempotente.

Antes de comenzar

Antes de realizar una solicitud de Calling, prepara lo siguiente:
  1. Una clave de API de la cuenta de YCloud. Envíala en el encabezado X-API-Key. Consulta Autenticación.
  2. Una cuenta de WhatsApp Business y un número de teléfono comercial registrado con YCloud.
  3. Calling habilitado para ese número de teléfono.
  4. Una implementación de audio WebRTC que pueda crear y aplicar ofertas y respuestas SDP.
  5. Un endpoint de webhook de YCloud suscrito a los eventos de Calling utilizados por tu integración. Consulta Configurar webhooks.
  6. Permiso de llamada del usuario cuando sea necesario para una llamada iniciada por la empresa.
Ponte en contacto con tu representante de YCloud para habilitar el acceso a la API Calling. Para la elegibilidad de llamadas salientes, sigue los requisitos actuales de Calling, incluido el nivel de mensajería de 2000 clientes de Business Portfolio y los países admitidos para números comerciales. El umbral anterior de 1000 conversaciones queda sustituido por los requisitos actuales. Los siguientes ejemplos utilizan estas variables de entorno:
Mantén la clave de API en tu servidor. No la incluyas en el código de navegadores o aplicaciones móviles.

Cómo funciona

Empieza configurando el número de teléfono comercial. Luego, intercambia el SDP según la dirección de la llamada. Las respuestas de la API confirman las operaciones individuales de señalización, mientras que los eventos de webhook informan sobre los cambios de estado y el resultado final. Si la captura está habilitada, eventos independientes indican cuándo una grabación o transcripción está lista para descargarse.

Solicitud

Configurar el número de teléfono comercial

Los ajustes de Calling y captura pertenecen a un número de teléfono comercial de WhatsApp específico. Configúralos antes de procesar llamadas.

Consultar la configuración de Calling

Usa GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings para comprobar si Calling está habilitado y si el icono de Calling está visible:
Si omites type, YCloud devuelve la respuesta con la configuración de Calling.

Habilitar Calling

Guarda la configuración de Calling con POST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings antes de empezar a aceptar o realizar llamadas:
La respuesta contiene el objeto calling guardado. Antes de gestionar llamadas en vivo, termina de configurar tus webhooks y sesiones WebRTC.

Configurar la grabación y la transcripción

Los ajustes de captura se aplican a las nuevas llamadas originadas mediante la API. Puedes habilitar la grabación, la transcripción o ambas.
Para consultar la configuración de captura, usa type=capture:
Puedes incluir calling e capture en la misma solicitud POST. Tras validar el acceso al número de teléfono, YCloud intenta guardar cada sección por separado. Si alguna de las operaciones falla, es posible que la otra sección ya haya quedado almacenada. Consulta ambas configuraciones después de un error y vuelve a intentar solo la sección que aún requiera actualizarse.

Gestionar una llamada iniciada por el usuario

Secuencia de Calling iniciada por el usuario En una llamada iniciada por el usuario, WhatsApp envía la oferta SDP. Tu aplicación responde a esa oferta y luego acepta o rechaza la llamada.

1. Recibir el evento connect

Suscríbete a whatsapp.call.connect. Un evento iniciado por el usuario tiene direction configurado como USER_INITIATED e incluye un SDP offer.
Guarda callingConnect.wacid y callingConnect.phoneId juntos. Aplica la oferta SDP recibida a tu conexión de pares WebRTC y genera una respuesta SDP.

2. Preaceptar la llamada

Llama a la preaceptación después de crear una respuesta SDP, pero antes de que el agente acepte la llamada. Esto prepara la ruta multimedia y puede reducir los cortes de audio cuando se responde la llamada. Endpoint: POST /whatsapp/calls/preAccept
Una vez que la preaceptación se complete correctamente, mantén la llamada en estado sonando o lista. La preaceptación no responde la llamada por el usuario.

3. Aceptar la llamada

Cuando el agente responda, envía los mismos phoneId, wacid, tipo de SDP y respuesta SDP al endpoint de aceptación. Endpoint: POST /whatsapp/calls/accept
Los campos de la solicitud y la estructura de la respuesta son los mismos que en la preaceptación. Tras una respuesta correcta, usa el estado de la conexión WebRTC para la preparación de los medios y espera whatsapp.call.terminate para conocer el resultado final de la llamada. La ventana documentada para la aceptación de llamadas entrantes es de aproximadamente 30 a 60 segundos después del webhook connect. Acepta de inmediato; una llamada no contestada finaliza del lado del usuario con una notificación Not Answered y un webhook terminate. Incluso si la conexión WebRTC ya está establecida, inicia el audio únicamente después de que la solicitud de aceptación devuelva HTTP 200. Comenzar antes puede cortar las primeras palabras; comenzar demasiado tarde produce silencio.

Rechazar en lugar de aceptar

Si el agente no puede atender la llamada entrante, recházala en lugar de crear una sesión activa. Endpoint: POST /whatsapp/calls/reject
La respuesta utiliza la respuesta estándar de Calling. Libera la conexión peer local después de la solicitud y sigue aceptando un evento de finalización posterior para este wacid si se recibe alguno.

Iniciar una llamada iniciada por la empresa

En una llamada iniciada por la empresa, tu aplicación crea la oferta SDP y la envía a YCloud.

Obtener permiso para llamar

Antes de iniciar una llamada, obtén el permiso de llamada del usuario. Se puede enviar una solicitud interactiva de permiso dentro de una ventana de servicio de atención al cliente válida:
Envía este cuerpo a POST /v2/whatsapp/messages/sendDirectly o ponlo en cola con POST /v2/whatsapp/messages. También puedes crear una plantilla de permiso de llamada. Por ejemplo, envía este cuerpo a POST /v2/whatsapp/templates y luego espera la aprobación:
Envía la plantilla aprobada con su parámetro de cuerpo:
Cuando callback_permission_status está habilitado en la configuración de llamadas del número de teléfono, una llamada iniciada por el usuario puede otorgar permiso para devolverle la llamada. Un usuario también puede otorgar permiso permanente para llamadas desde el perfil de la empresa. Las respuestas de permiso llegan como eventos whatsapp.inbound_message.received. Revisa el objeto interactive.call_permission_reply, no solo si el mensaje de solicitud de permiso fue entregado:
No inicies la llamada tras un rechazo o un permiso vencido. El error de Meta 138006 significa que el número de la empresa no cuenta con el permiso de llamada requerido. Para obtener información detallada sobre los errores del proveedor, consulta Meta’s Calling errors.

1. Crear una oferta SDP

Crea una conexión peer WebRTC local y añade la pista de audio. Genera la oferta SDP, establécela como la descripción local y espera a que esa operación finalice antes de enviar la oferta a YCloud.

2. Conectar la llamada

Endpoint: POST /whatsapp/calls/connect Proporciona al menos uno de entre to o recipient. Si envías ambos, YCloud usa to e ignora recipient.
Guarda de inmediato el wacid devuelto. success: true significa que la operación de conexión fue aceptada; no significa que el usuario haya respondido.

3. Aplicar la respuesta y rastrear el intento

YCloud envía whatsapp.call.connect para la llamada. En el caso de una llamada iniciada por la empresa, el evento tiene direction: BUSINESS_INITIATED y transporta el SDP remoto answer. Aplica esa respuesta como la descripción remota para la misma conexión peer. Suscríbete a whatsapp.call.status.updated para hacer seguimiento del intento:
Haz que el procesamiento de eventos sea idempotente para que un reenvío no repita acciones de agentes, facturación ni tareas de limpieza.

Finalizar una llamada activa

Llama a terminate cuando tu aplicación necesite finalizar una llamada activa entrante o saliente. Endpoint: POST /whatsapp/calls/terminate
Los campos de la solicitud coinciden con la solicitud de rechazo. Una respuesta correcta confirma que YCloud procesó la operación de finalización. Mantén abierto el registro de la llamada hasta que recibas el evento de finalización definitivo o tu propia política de recuperación lo cierre.

Respuesta

Los cinco endpoints de señalización devuelven la misma estructura de respuesta:
wacid identifica la llamada asociada a la operación. success: true confirma que la operación de señalización se realizó con éxito; no confirma que el otro participante haya respondido ni que la llamada haya finalizado. Usa el estado de WebRTC y los eventos del webhook de Calling para conocer esos resultados.

Procesar el evento final de la llamada

whatsapp.call.terminate es el evento terminal del ciclo de vida de una llamada.
Cuando recibas este evento, finaliza el registro de la llamada y libera los recursos de WebRTC restantes. Una respuesta anterior de la API no confirma que la llamada se haya completado.

Recibir grabaciones y transcripciones

Cuando la captura está habilitada, el procesamiento del contenido multimedia continúa después del ciclo de vida de la llamada. La grabación y la transcripción tienen eventos terminales independientes: El siguiente ejemplo muestra una grabación disponible:
Ambas propiedades del payload utilizan los mismos campos:

Descargar un recurso disponible

Llama al endpoint multimedia únicamente después de que el evento correspondiente informe AVAILABLE. Endpoint: GET /whatsapp/calls/media/{mediaAssetId}
El endpoint devuelve el archivo completo como archivo adjunto y no admite descargas de rangos de bytes. Las grabaciones usan .ogg; las transcripciones usan .json. Solo el tenant propietario en YCloud puede descargar un recurso. Un recurso permanece disponible durante 30 días a partir del momento de su creación. Los recursos faltantes, no disponibles, vencidos o que no pertenezcan a la cuenta devuelven HTTP 404.

Crear un receptor de webhook confiable

Suscribe tu endpoint a los eventos que requiera tu integración:
Para cada solicitud:
  1. Conserva el cuerpo sin procesar de la solicitud y verifica YCloud-Signature antes de confiar en el evento.
  2. Guarda el evento o añade tareas duraderas a una cola.
  3. Devuelve con prontitud una respuesta correcta 2xx.
  4. Deduplica mediante el evento de nivel superior id.
  5. Correlaciona los datos de la llamada mediante wacid; conserva phoneId junto con ellos para operaciones posteriores.
  6. Gestiona eventos relacionados que lleguen muy seguidos y tolera reenvíos.
Consulta Configurar webhooks para conocer la creación de endpoints, la validación de firmas y el comportamiento de entrega. La página Ejemplos de payload de Webhook contiene los ejemplos completos generados.

Gestionar errores y recuperación

Los endpoints de llamadas usan la respuesta estándar de error de la API de YCloud. Consulta Gestionar errores para ver la estructura de respuesta y las pautas de reintento. Usa estas comprobaciones para fallos comunes de Calling: Un tiempo de espera agotado en la solicitud no demuestra que la acción de señalización haya fallado. Antes de reintentar, concilia la solicitud con los eventos de webhook y tu estado local actual de la llamada. Es posible que la acción ya haya llegado a WhatsApp.

Lista de verificación de integración

  • Habilita Calling en el número de teléfono comercial correcto.
  • Configura y prueba todas las suscripciones de webhook de Calling requeridas.
  • Verifica las firmas de webhook y deduplica los eventos.
  • Almacena wacid, phoneId, la dirección y el estado actual juntos.
  • Trata el success de la API como la aceptación de la operación, no como el resultado final de la llamada.
  • Usa preAccept solo como preparación; llama a accept para responder.
  • Finaliza las llamadas a partir de whatsapp.call.terminate.
  • Descarga los medios capturados solo después de un evento AVAILABLE y dentro del plazo de 30 días.
  • Libera los recursos de WebRTC en caso de rechazo, finalización, fallo o tiempo de espera local agotado.
  • Evita registrar claves de API, SDP completo o identificadores de participantes en los registros generales de la aplicación.

Referencia de la API de Calling

Revisa los esquemas exactos de solicitud y respuesta para cada endpoint de Calling.

Ejemplos de payload de Webhook

Inspecciona los ejemplos completos de eventos de Calling generados a partir de la especificación del webhook.