Catálogo de eventos

Cada cuerpo de webhook tiene un campo type cuyo valor es uno de los tipos de evento de esta página. Cuando te suscribes a un endpoint, el arreglo events debe contener los tipos de evento que quieres (o estar vacío para suscribirte a todo). Estos eventos se entregan en dos modalidades:

Las entregas a endpoints siempre son notificaciones no bloqueantes con reintentos: responde con cualquier 2xx; el sobre incluye un event_id para deduplicar.
Los intercambios bloqueantes se ejecutan solo en el webhook heredado de URL única: la solicitud de configuración telephony.incoming / web.incoming (números en modo webhook y claves de widget, tiempo de espera de 10 s) y el despacho de herramientas en modo webhook. Tu respuesta da forma a la llamada en vivo.

Las cargas útiles de ejemplo a continuación muestran el sobre del endpoint en su orden de transmisión (claves ordenadas alfabéticamente: data, event_id, type); las entregas heredadas incluyen los mismos data sin event_id.

Eventos de llamadas

`telephony.incoming`

Se envía cuando una llamada entrante llega a uno de tus números de teléfono. Las entregas al endpoint son notificaciones de envío sin espera para cada llamada entrante, sin importar si el número está configurado con un agente o con un webhook. Los números sin un agente asignado también reciben la solicitud de configuración bloqueante en el webhook heredado; consulta telephony.incoming / web.incoming para ver el esquema completo de solicitud/respuesta.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

`telephony.complete`

Se envía cuando finaliza una llamada de telefonía entrante o saliente. No bloqueante. Incluye la transcripción, la URL de la grabación cuando está disponible y el resumen de facturación. Consulta telephony.complete / web.complete para ver el esquema de la carga útil.

`telephony.tool`

Se envía después de que una llamada de telefonía invoca una herramienta de función. Notificación de auditoría no bloqueante: la herramienta ya se ejecutó cuando se entrega este evento; cubre tus propias herramientas de función (no las herramientas integradas, de base de conocimiento, conexión de aplicaciones o MCP).

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response es el resultado ejecutado: {"status": <http status>, "response": <your endpoint's JSON>} si tiene éxito, o {"status": <status>, "error": "<message>"} si falla.

`web.incoming`

El equivalente de telephony.incoming para el canal web, enviado cuando se inicia una sesión de widget web o una llamada de prueba de micrófono del builder. Las entregas al endpoint son de envío sin espera para cada sesión web. Las claves publicables en mode="webhook" también reciben la solicitud de configuración bloqueante en el webhook heredado; esa solicitud bloqueante tiene una estructura diferente (origin_domain, publishable_key_prefix; sin números de teléfono). Consulta telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number siempre es el literal "web". Para sesiones del widget en modo webhook, to_number está vacío (el número de agente de la sesión se asigna después de la configuración); para llamadas de prueba de micrófono del builder, origin_domain y publishable_key_prefix están vacíos.

`web.complete`

El equivalente de telephony.complete para el canal web, que cubre llamadas del widget web (direction: "web") y llamadas de prueba de micrófono del builder (direction: "test"). No bloqueante. Tiene la misma estructura de carga útil que telephony.complete, además de origin_domain, con from_number establecido como "web".

En el webhook heredado de una sola URL, las llamadas de prueba de micrófono del builder históricamente se reportan como telephony.complete; solo las llamadas con direction: "web" usan allí el tipo web.complete. El sistema de endpoints asigna tanto las llamadas web como las de prueba a web.*. Las cargas útiles históricas pueden contener los valores heredados de direction widget o mic.

`web.tool`

El equivalente de telephony.tool para el canal web. data contiene origin_domain en lugar de from_number / to_number.

Eventos de voz

La creación de voces personalizadas es asincrónica. Estos eventos no bloqueantes te permiten reaccionar a un resultado final en lugar de consultar repetidamente el endpoint de detalles del clon.

`voice.ready`

Se envía cuando una voz personalizada termina de procesarse y puede asignarse a un agente.

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

`voice.failed`

Se envía cuando el procesamiento de una voz personalizada alcanza un fallo permanente.

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}

Campo	Tipo	Descripción
`voice.id`	string	ID público de la voz personalizada
`voice.name`	string	Valor de voz del agente con el formato `custom:<public_id>`
`voice.display_name`	string	Nombre de la voz visible para la organización
`voice.language`	string	Código de idioma único del clon
`voice.gender`	string	`male`, `female` o una cadena vacía
`voice.status`	string	`ready` para `voice.ready`; `failed` para `voice.failed`
`voice.failure_reason`	string	Vacío en caso de éxito; detalle del fallo de procesamiento en caso de error
`voice.created_at`, `voice.updated_at`	timestamp	Marcas de tiempo ISO 8601
`reason`	string	Detalle del fallo; presente solo en `voice.failed`

Eventos de calidad

`call.graded`

Se envía cada vez que se completa una ejecución de calificación con IA para una llamada. No bloqueante.

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

Campo	Tipo	Descripción
`grade.id`	integer	ID de la calificación
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` o `no_conversation`
`grade.summary`	string	Resumen de un párrafo
`grade.detected_issues`	array	Cadenas de problemas detectados por el calificador
`grade.status`	string	Siempre `completed` — solo se emiten ejecuciones finalizadas
`grade.grader_model`	string	Qué calificador produjo el resultado (por ejemplo, `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Una llamada puede calificarse más de una vez — una calificación heurística rápida suele ir seguida de una calificación completa con modelo una vez que la grabación está disponible, y es posible recalificar manualmente. Cada ejecución completada emite su propio evento call.graded; considera el valor más reciente de graded_at como autoritativo.

`issue.reported`

Se envía cuando se crea un reporte de problema — ya sea enviado por una persona usuaria desde el panel (source: "user") o automáticamente mediante la calificación de llamadas (source: "system"). No bloqueante.

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}

Campo	Tipo	Descripción
`issue_report.severity`	string	`critical`, `warning` o `info`
`issue_report.status`	string	`open` o `resolved`
`issue_report.source`	string	`user` (enviado desde el panel) o `system` (creado mediante calificación)

Recalificar una llamada vuelve a generar sus reportes de problemas creados por el sistema, lo que vuelve a emitir issue.reported para los reportes recreados. Elimina duplicados por call_id + title si solo quieres una notificación por cada problema subyacente.

Eventos de llamadas de prueba

`test-call.completed`

Se envía cuando una ejecución de llamada de prueba alcanza un estado terminal — completed o failed, incluidas las ejecuciones que fallaron al iniciarse y nunca produjeron una llamada. No bloqueante. Útil para integrar ejecuciones de CI por lotes con tus sistemas de chat/notificaciones.

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}

Campo	Tipo	Descripción
`test_call_run.target_type`	string	`agent` o `phone_number`
`test_call_run.target_id`	integer	El ID del agente o del número de teléfono al que se dirigió la ejecución, según `target_type`
`test_call_run.status`	string	`completed` o `failed`
`test_call_run.call_id`	integer \| null	`null` cuando la ejecución falló antes de realizar una llamada
`test_call_run.error_message`	string	Vacío si se completó correctamente

Eventos de alertas

`alert.triggered`

Se envía cuando una regla de alerta con el canal Entregar a webhooks de desarrolladores habilitado supera su umbral. No bloqueante. Una regla se activa una vez y luego respeta su período de espera, por lo que una infracción sostenida genera un evento por cada ventana de período de espera.

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}

Campo	Tipo	Descripción
`event_id` (en `data`)	UUID	El id de activación de la alerta, distinto del `event_id` de entrega del sobre
`rule_id`, `rule_name`	UUID, cadena	La regla que se activó
`metric`	cadena	`success_rate`, `failure_rate`, `avg_score`, `call_volume` o `suite_regression`
`comparator`	cadena	`lt`, `lte`, `gt` o `gte`
`metric_value`	número	El valor de la métrica durante la ventana en que se activó la regla
`threshold`	número	El umbral configurado
`window_hours`	entero	Ventana de evaluación retrospectiva
`fired_at`	marca de tiempo

Consulta la guía de alertas para crear reglas, métricas, períodos de espera y los canales de correo electrónico / Slack.

Relacionado

telephony.incoming / web.incoming

La carga útil bloqueante de llamadas entrantes a la que debes responder.

telephony.complete / web.complete

Transcripción y métricas posteriores a la llamada.

Endpoints de webhook

Suscribe una URL a un subconjunto de estos eventos.

Herramientas de funciones

Cómo se generan los eventos telephony.tool / web.tool.

Webhooks

Function Tools

Eventos de llamadas

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Eventos de voz

`voice.ready`

`voice.failed`

Eventos de calidad

`call.graded`

`issue.reported`

Eventos de llamadas de prueba

`test-call.completed`

Eventos de alertas

`alert.triggered`

Relacionado

telephony.incoming / web.incoming

telephony.complete / web.complete

Endpoints de webhook

Herramientas de funciones

​Eventos de llamadas

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Eventos de voz

​voice.ready

​voice.failed

​Eventos de calidad

​call.graded

​issue.reported

​Eventos de llamadas de prueba

​test-call.completed

​Eventos de alertas

​alert.triggered

​Relacionado

telephony.incoming / web.incoming

telephony.complete / web.complete

Endpoints de webhook

Herramientas de funciones

Eventos de llamadas

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Eventos de voz

`voice.ready`

`voice.failed`

Eventos de calidad

`call.graded`

`issue.reported`

Eventos de llamadas de prueba

`test-call.completed`

Eventos de alertas

`alert.triggered`

Relacionado