Webhooks de llamadas entrantes y salientes

Webhooks de llamadas entrantes y salientes

Recibe notificaciones de llamadas entrantes y salientes. Aprende a configurar Calls webhook, procesar call.inbound, call.outbound y call.completed y registrar las llamadas después de finalizar con el payload de finalización.

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 notificaciones cuando una llamada entrante llega al sistema, cuando una extensión realiza una llamada saliente y después de que una llamada termina. Las notificaciones de finalización cubren llamadas entrantes y salientes. 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.

Una URL para los eventos de llamadas: las notificaciones entrantes, salientes y de finalización usan la misma URL de Calls webhook. Office no tiene un campo ni un interruptor independiente para outbound.

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 Calls webhook para tu cuenta de cliente desde el portal o la API.
2. Zonitel envía notificaciones de llamadas a esa URL. El webhook cubre llamadas entrantes y salientes; consulta los eventos disponibles abajo.
3. Tu endpoint debe responder con HTTP 200 OK en un máximo de 5 segundos para confirmar cada notificación. POST es el método predeterminado; utiliza Advanced en el portal si tu receptor necesita otro método compatible o autenticación.

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

Eventos de llamadas disponibles

• call.inbound — Se envía cuando una llamada entrante llega al sistema. Permite mostrar quién llama o iniciar un registro mientras la llamada está en curso.
• call.outbound — Se envía cuando una extensión realiza una llamada que el sistema telefónico clasifica como saliente, al iniciar la llamada y antes de que sea contestada. Incluye números externos y los casos entre dominios o con desvío descritos abajo. Permite abrir o preparar un registro mientras la llamada está en curso. No confirma que haya sido contestada; los detalles de finalización llegan después en call.completed.
• call.completed — Se envía después de que la llamada termina. Cubre llamadas entrantes y salientes; el campo direction identifica la dirección. Las notificaciones de llamadas finalizadas también pueden identificar llamadas local.

Registrar llamadas solo después de finalizar

Para crear o actualizar el registro de la llamada en tu CRM al finalizar, configura tu integración receptora para procesar las notificaciones cuyo event_type sea call.completed. Confirma las demás notificaciones con HTTP 200, pero no las utilices para crear un registro de llamada finalizada. Este filtro se aplica en tu integración receptora.

Utiliza el id de la llamada finalizada para relacionar o actualizar el registro, junto con las fechas, duración e indicadores de esa notificación. Para el historial, las grabaciones y las transcripciones, consulta Sincroniza tus llamadas con la API.

call.inbound y call.outbound indican que una llamada comenzó, aunque nunca sea contestada. No los utilices para crear el registro de una llamada finalizada.

Tiempos: call.outbound se genera al marcar. call.completed se genera al importar el registro de detalle de llamada (CDR), lo que puede ocurrir un tiempo después de colgar. No esperes que ambos eventos lleguen inmediatamente uno detrás del otro.

Cuándo se envía call.outbound

• Un usuario marca un número externo desde su teléfono de escritorio, softphone o aplicación móvil.
• El evento de inicio se genera una vez por llamada, incluso si el enrutamiento reintenta con un operador de respaldo. Esto no garantiza una única entrega; prepara el receptor para manejar reintentos de forma segura.
• Incluye llamadas no contestadas y canceladas, porque el evento se genera al iniciar la llamada.
• Las llamadas de emergencia (911) también generan el evento. Nunca hagas una llamada de emergencia para probar un webhook.

Cuándo no se envía call.outbound

• Llamadas internas directas entre extensiones de la misma cuenta/dominio. Se clasifican como local y no generan call.outbound. Si la extensión llamada desvía a un celular, consulta la excepción de abajo.
• Llamadas entrantes reenviadas a un número externo mediante desvío, follow me o grupos de timbrado que llaman a un celular. Sus tramos salientes pueden seguir generando call.completed con direction igual a outbound.
• Faxes enviados desde el portal.

Extensiones entre dominios y desvíos a celulares

• Extensiones en dominios distintos: una llamada entre extensiones de cuentas/dominios separados puede generar call.outbound cuando su ruta se clasifica como saliente, aunque ambos dominios pertenezcan a la misma organización. En este caso, destination_number puede ser una extensión corta como 401 o 102, en lugar de un número telefónico público.
• Una extensión desvía a un celular: llamar a una extensión que desvía a un celular también puede generar call.outbound por el enrutamiento saliente. No asumas que toda llamada marcada inicialmente a una extensión queda excluida.

Estas distinciones describen únicamente call.outbound. No determinan si se envía call.completed para esa misma llamada. No deduzcas el comportamiento del evento de finalización a partir del filtro de inicio saliente.

La disponibilidad del evento de inicio saliente depende de la implementación telefónica de tu cuenta. Si recibes eventos de finalización pero no de inicio saliente, contacta a Soporte Zonitel para confirmar la disponibilidad.

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):

Ejemplos del payload del webhook

Estas son notificaciones que recibe tu endpoint, no el cuerpo utilizado para registrar el webhook. Los ejemplos muestran la entrega predeterminada por POST.

Inicio de llamada entrante: call.inbound

{
  "event_type": "call.inbound",
  "caller_id_name": "John Smith",
  "caller_id_number": "13055550123",
  "destination_number": "13055550999",
  "direction": "inbound"
}

Inicio de llamada saliente: call.outbound

{
  "event_type": "call.outbound",
  "caller_id_name": "Example Company",
  "caller_id_number": "13055550999",
  "destination_number": "3055550123",
  "direction": "outbound"
}

La notificación saliente actual no incluye id ni extension. No dependas de un identificador compartido para relacionarla con call.completed. Utiliza el id de finalización para el registro definitivo de la llamada.

Finalización de llamada: call.completed

Este ejemplo corresponde a una llamada saliente. Una llamada entrante finalizada utiliza el mismo evento con direction igual a inbound.

{
  "event_type": "call.completed",
  "id": "a3c24a95-8e47-4ce7-a7a5-f46197b185bd",
  "caller_id_name": "Example Company",
  "caller_id_number": "13055550999",
  "destination_number": "3055550123",
  "destination_name": "John Smith",
  "duration": "42",
  "is_missed_call": false,
  "has_voicemail": false,
  "start_stamp": {
    "date": "2026-10-13 18:30:00.000000",
    "timezone_type": 1,
    "timezone": "+00:00"
  },
  "answer_stamp": {
    "date": "2026-10-13 18:30:04.000000",
    "timezone_type": 1,
    "timezone": "+00:00"
  },
  "end_stamp": {
    "date": "2026-10-13 18:30:46.000000",
    "timezone_type": 1,
    "timezone": "+00:00"
  },
  "direction": "outbound"
}

Campos del payload

• event_type: Identifica la notificación: call.inbound, call.outbound o call.completed.
• id: Identificador de la llamada en call.completed; no se incluye en la notificación actual de call.outbound.
• caller_id_name y caller_id_number: Identificación del llamante. En call.outbound, corresponde al caller ID enviado al operador (el identificador de la empresa), no al número de extensión.
• destination_number y destination_name: Número y nombre del destino, cuando se proporcionan. En call.outbound, destination_number es el número marcado; el formato puede variar (por ejemplo, 10 dígitos, 11 dígitos o un número internacional con 011). También puede ser una extensión corta en llamadas entre dominios clasificadas como salientes. Consérvalo como texto; no asumas una longitud fija ni que siempre sea un número público.
• direction: Dirección de la llamada; las llamadas finalizadas pueden ser inbound, outbound o local.
• duration: Duración reportada de la llamada en segundos.
• is_missed_call y has_voicemail: Indican una llamada perdida y un mensaje de voz.
• start_stamp, answer_stamp y end_stamp: Fechas de la llamada, con información de zona horaria cuando se proporciona.

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