Webhooks de Llamadas Entrantes

Webhooks de Llamadas Entrantes

Los webhooks de llamadas envían un POST a tu servidor cuando una llamada inicia, termina o cambia de estado. Esta guía te muestra la forma rápida de registrarlo desde Private Integrations, la regla del HTTP 200 que decide si se guarda, y el método por API.

La forma sencilla: configúralo en el portal

No necesitas llamar a la API para registrar un webhook de llamadas. Se puede configurar directamente desde el portal.

1. Inicia sesión en tu Zonitel Office Portal.
2. En el menú lateral izquierdo, expande Settings y haz clic en Private Integrations.
3. Abre la pestaña Webhooks.
4. En Calls webhook, pega tu Webhook URL.
5. Haz clic en Save.

Zonitel envía un evento cuando una llamada inicia, termina o cambia de estado. La URL debe ser válida y responder con HTTP 200 para guardarse: si no responde correctamente no se almacena, así que levanta tu endpoint primero. Para quitarlo después, borra el campo y guarda de nuevo.

El resto de este artículo cubre el método por API, para configurar webhooks de forma programática.

Advanced: método y autenticación del receptor

1. Abre Advanced debajo de la URL del webhook y activa Use a custom method or authentication.
2. Elige el HTTP method y la Authentication que requiere el servicio receptor. Métodos: POST, PUT, PATCH o GET. Autenticación: None, Bearer token, API key, Basic (user + password) o Custom header.
3. Completa los campos de la opción elegida y guarda el webhook. La URL receptora debe responder con HTTP 200 para que el portal la acepte.

El valor predeterminado es POST sin autenticación. GET no lleva cuerpo: el evento viaja como parámetros de consulta. Para API key, elige dónde enviarla e introduce el nombre del encabezado o parámetro que exige el receptor.

Las credenciales opcionales del receptor pertenecen al servicio que recibe el webhook. Son distintas del token de la API de Zonitel y de X-Client-Id, que tu software utiliza para llamar a nuestra API. Proporciona únicamente credenciales destinadas a ese receptor.

El ejemplo de registro por API que aparece abajo configura la URL. Utiliza el portal para las opciones Advanced mostradas aquí.

Cómo Funciona

1. Registra una URL de webhook en tu cuenta.

2. Cada llamada entrante a tus números de cliente dispara una solicitud POST a la URL configurada.

3. Tu servidor debe responder con HTTP 200 OK dentro de 5 segundos para confirmar la recepción.

Importante: La URL del webhook debe ser HTTPS y accesible públicamente desde Internet.

Registrar una URL de Webhook

Endpoint:

Cuerpo de la solicitud (JSON):

Notas:

• La URL debe ser HTTPS y accesible públicamente.

• Debe responder con HTTP 200 OK en menos de 5 segundos.

Ejemplo de respuesta exitosa (200 OK):

Consultar Webhook Registrado

Endpoint:

Ejemplo de respuesta (200 OK):

Ejemplo de Payload del Webhook

Cuando se recibe una llamada entrante, tu endpoint de webhook recibirá una solicitud POST con un payload JSON como este:

Campos del Payload:

• caller_id_name: Nombre del llamante (si está disponible).

• caller_id_number: Número de teléfono del llamante.

• destination_number: Número de cliente que recibe la llamada.

Respuestas Comunes de Error

• 401 Unauthorized

• 403 Forbidden

• 404 Not Found

• 500 Internal Server Error

Buenas Prácticas

• Usa siempre HTTPS para tus URLs de webhook.

• Responde con HTTP 200 OK dentro de 5 segundos para confirmar la recepción del evento.

• Mantén tu token Bearer seguro y no lo compartas públicamente.

• Asegúrate de que tu endpoint pueda manejar múltiples llamadas concurrentes.

Elimina un webhook registrado

Envía DELETE a la misma dirección para dejar de recibir eventos. Borrar el campo de Llamadas en la pestaña Webhooks de Configuración > Integraciones Privadas hace lo mismo.

DELETE https://api.zonitel.com/api/v3/integrations/calls/webhooks

Para ir más lejos

Registrar el webhook es la mitad de una integración de llamadas. Descargar el historial, obtener grabaciones y transcripciones y lanzar llamadas desde tu propia aplicación se explican en Sincroniza tus llamadas con la API.

¿Necesitas ayuda?

Llamada/Texto/WhatsApp: (833) 966-4835
Email: info@zonitel.com