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:- Una clave de API de la cuenta de YCloud. Envíala en el encabezado
X-API-Key. Consulta Autenticación. - Una cuenta de WhatsApp Business y un número de teléfono comercial registrado con YCloud.
- Calling habilitado para ese número de teléfono.
- Una implementación de audio WebRTC que pueda crear y aplicar ofertas y respuestas SDP.
- Un endpoint de webhook de YCloud suscrito a los eventos de Calling utilizados por tu integración. Consulta Configurar webhooks.
- Permiso de llamada del usuario cuando sea necesario para una llamada iniciada por la empresa.
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
UsaGET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings para comprobar si Calling está habilitado y si el icono de Calling está visible:
type, YCloud devuelve la respuesta con la configuración de Calling.
Habilitar Calling
Guarda la configuración de Calling conPOST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings antes de empezar a aceptar o realizar llamadas:
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:
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
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 awhatsapp.call.connect. Un evento iniciado por el usuario tiene direction configurado como USER_INITIATED e incluye un SDP offer.
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
3. Aceptar la llamada
Cuando el agente responda, envía los mismosphoneId, wacid, tipo de SDP y respuesta SDP al endpoint de aceptación.
Endpoint: POST /whatsapp/calls/accept
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
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: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:
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.
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íawhatsapp.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
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:
Descargar un recurso disponible
Llama al endpoint multimedia únicamente después de que el evento correspondiente informeAVAILABLE.
Endpoint: GET /whatsapp/calls/media/{mediaAssetId}
.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:- Conserva el cuerpo sin procesar de la solicitud y verifica
YCloud-Signatureantes de confiar en el evento. - Guarda el evento o añade tareas duraderas a una cola.
- Devuelve con prontitud una respuesta correcta
2xx. - Deduplica mediante el evento de nivel superior
id. - Correlaciona los datos de la llamada mediante
wacid; conservaphoneIdjunto con ellos para operaciones posteriores. - Gestiona eventos relacionados que lleguen muy seguidos y tolera reenvíos.
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
successde la API como la aceptación de la operación, no como el resultado final de la llamada. - Usa
preAcceptsolo como preparación; llama aacceptpara responder. - Finaliza las llamadas a partir de
whatsapp.call.terminate. - Descarga los medios capturados solo después de un evento
AVAILABLEy 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.

