Webhooks

Catálogo de eventos

Todos los tipos de eventos de webhook que emite ThunderPhone.

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 punto de conexión, el arreglo events debe contener los tipos de evento que quieras (o estar vacío para suscribirte a todo, excepto los eventos por turno telephony.turn / web.turn, que se envían únicamente a los puntos de conexión que los nombran explícitamente).

Estos eventos se envían en dos estilos:

• Las entregas a puntos de conexión siempre son notificaciones no bloqueantes con reintentos: responde con cualquier 2xx; el sobre incluye un event_id para deduplicar.
• Los intercambios bloqueantes se ejecutan únicamente 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 define la llamada en curso.

Los ejemplos de cargas útiles a continuación muestran el sobre del punto de conexión 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 y olvido enviadas para cada llamada entrante, ya sea que 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 es 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 conocimientos, 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>} cuando tiene éxito, o {"status": <status>, "error": "<message>"} cuando falla.

telephony.turn#

Se envía mientras una llamada de telefonía está en curso, una vez por cada turno con voz a medida que ocurre: las respuestas habladas del agente y los turnos transcritos de quien llama. Te permite seguir la conversación en vivo mediante webhooks simples en lugar de consultar repetidamente GET /v1/calls/{call_id}/transcript. No es bloqueante.

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}

web.incoming#

El equivalente en el canal web de telephony.incoming, enviado cuando inicia una sesión de widget web o una llamada de prueba de micrófono del constructor. Las entregas al endpoint son de envío y olvido 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 las sesiones del widget en modo webhook, to_number está vacío (el número del agente de la sesión se asigna después de la configuración); para las llamadas de prueba de micrófono del constructor, origin_domain y publishable_key_prefix están vacíos.

web.complete#

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

web.tool#

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

web.turn#

El equivalente en el canal web de telephony.turn, que cubre las llamadas del widget web y las llamadas de prueba de micrófono del constructor. Tiene la misma estructura de carga útil, con origin_domain en lugar de from_number / to_number. Al igual que telephony.turn, requiere una suscripción explícita: nunca se entrega mediante un arreglo events vacío.

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 periódicamente 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 error 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"
}

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"
}

issue.reported#

Se envía cuando se crea un informe de problema: ya sea presentado por un usuario 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"
}

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 conectar ejecuciones de CI por lotes con tus sistemas de chat y 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"
}

Eventos de alerta#

alert.triggered#

Se envía cuando una regla de alerta con el canal Entregar a webhooks de desarrollador habilitado supera su umbral. No bloquea. Una regla se activa una vez y luego respeta su período de espera, por lo que una infracción sostenida produce un evento por cada ventana 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"
}

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

Relacionado#