Catalogue des événements

Chaque corps de webhook contient un champ type dont la valeur est l’un des types d’événements de cette page. Lorsque vous vous abonnez à un endpoint, le tableau events doit contenir les types d’événements souhaités (ou être vide pour vous abonner à tous les événements). Ces événements sont transmis selon deux modes :

Les livraisons d’endpoint sont toujours des notifications non bloquantes avec des tentatives : répondez avec n’importe quel code 2xx ; l’enveloppe contient un event_id à utiliser pour la déduplication.
Les échanges bloquants s’exécutent uniquement sur le webhook historique à URL unique : la requête de configuration telephony.incoming / web.incoming (numéros en mode webhook et clés de widget, délai d’expiration de 10 s) et la répartition des outils en mode webhook. Votre réponse façonne l’appel en direct.

Les exemples de payloads ci-dessous montrent l’enveloppe d’endpoint dans son ordre de transmission (clés triées par ordre alphabétique : data, event_id, type) ; les livraisons historiques contiennent les mêmes data sans event_id.

Événements d’appel

`telephony.incoming`

Envoyé lorsqu’un appel entrant atteint l’un de vos numéros de téléphone. Les livraisons aux endpoints sont des notifications sans attente de réponse envoyées pour chaque appel entrant, que le numéro soit configuré avec un agent ou avec un webhook. Les numéros sans agent attribué reçoivent également la requête de configuration bloquante sur le webhook hérité — consultez telephony.incoming / web.incoming pour le schéma complet de requête / réponse.

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

`telephony.complete`

Envoyé lorsqu’un appel téléphonique entrant ou sortant se termine. Non bloquant. Inclut la transcription complète, l’URL de l’enregistrement et le récapitulatif de facturation. Consultez telephony.complete / web.complete pour le schéma de la charge utile.

`telephony.tool`

Envoyé après qu’un appel téléphonique a invoqué un outil de fonction. Notification d’audit non bloquante — l’outil a déjà été exécuté lorsque cet événement est livré ; il couvre vos propres outils de fonction (et non les outils intégrés, de base de connaissances, de connexion d’application ou 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 correspond au résultat exécuté : {"status": <http status>, "response": <your endpoint's JSON>} en cas de réussite, ou {"status": <status>, "error": "<message>"} en cas d’échec.

`web.incoming`

L’équivalent de telephony.incoming pour le canal web, envoyé lorsqu’une session de widget web ou un appel de test du micro dans le builder démarre. Les livraisons aux endpoints sont sans attente de réponse pour chaque session web. Les clés publiables en mode="webhook" reçoivent également la requête de configuration bloquante sur le webhook hérité — cette requête bloquante a une structure différente (origin_domain, publishable_key_prefix ; aucun numéro de téléphone). Consultez 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 correspond toujours à la valeur littérale "web". Pour les sessions de widget en mode webhook, to_number est vide (le numéro d’agent de la session est attribué après la configuration) ; pour les appels de test du micro dans le builder, origin_domain et publishable_key_prefix sont vides.

`web.complete`

L’équivalent de telephony.complete pour le canal web, couvrant les appels de widget web (direction: "web") et les appels de test du micro dans le builder (direction: "test"). Non bloquant. Même structure de charge utile que telephony.complete, avec origin_domain en plus, et from_number défini sur "web".

Sur le webhook hérité à URL unique, les appels de test du micro dans le builder sont historiquement signalés comme telephony.complete — seuls les appels avec direction: "web" y utilisent le type web.complete. Le système d’endpoints mappe les appels web et de test vers web.*. Les charges utiles historiques peuvent contenir les anciennes valeurs widget ou mic pour direction.

`web.tool`

L’équivalent de telephony.tool pour le canal web. Les data contiennent origin_domain au lieu de from_number / to_number.

Événements de qualité

`call.graded`

Envoyé lorsqu’une exécution d’évaluation par IA se termine pour un appel. Non bloquant.

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

Champ	Type	Description
`grade.id`	entier	ID de l’évaluation
`grade.score`	entier \| null	0–100
`grade.call_outcome`	chaîne	`success`, `failure`, `unknown` ou `no_conversation`
`grade.summary`	chaîne	Résumé en un paragraphe
`grade.detected_issues`	tableau	Chaînes décrivant les problèmes détectés par l’évaluateur
`grade.status`	chaîne	Toujours `completed` — seules les exécutions terminées sont émises
`grade.grader_model`	chaîne	Évaluateur ayant produit le résultat (par ex. `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	horodatage

Un appel peut être évalué plusieurs fois — une évaluation heuristique rapide est souvent suivie d’une évaluation complète par modèle une fois l’enregistrement disponible, et des réévaluations manuelles sont possibles. Chaque exécution terminée émet son propre événement call.graded ; considérez le dernier graded_at comme faisant autorité.

`issue.reported`

Envoyé lorsqu’un rapport de problème est créé — soit signalé par un utilisateur depuis le tableau de bord (source: "user"), soit automatiquement par l’évaluation d’appel (source: "system"). Non bloquant.

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

Champ	Type	Description
`issue_report.severity`	chaîne	`critical`, `warning` ou `info`
`issue_report.status`	chaîne	`open` ou `resolved`
`issue_report.source`	chaîne	`user` (signalé depuis le tableau de bord) ou `system` (créé par l’évaluation)

La réévaluation d’un appel reconstruit ses rapports de problèmes générés par le système, ce qui émet à nouveau issue.reported pour les rapports recréés. Dédupliquez sur call_id + title si vous ne souhaitez qu’une notification par problème sous-jacent.

Événements d’appels de test

`test-call.completed`

Envoyé lorsqu’une exécution d’appel de test atteint un statut terminal — completed ou failed, y compris les exécutions qui ont échoué au lancement et n’ont jamais produit d’appel. Non bloquant. Utile pour connecter les exécutions CI par lot à vos systèmes de chat/notifications.

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

Champ	Type	Description
`test_call_run.target_type`	chaîne	`agent` ou `phone_number`
`test_call_run.target_id`	entier	ID de l’agent ou du numéro de téléphone ciblé par l’exécution, correspondant à `target_type`
`test_call_run.status`	chaîne	`completed` ou `failed`
`test_call_run.call_id`	entier \| null	`null` lorsque l’exécution a échoué avant qu’un appel soit passé
`test_call_run.error_message`	chaîne	Vide en cas de réussite

Événements d’alerte

`alert.triggered`

Envoyé lorsqu’une règle d’alerte dont le canal Transmettre aux webhooks de développeur est activé franchit son seuil. Non bloquant. Une règle se déclenche une fois, puis respecte son délai de refroidissement ; une violation persistante produit donc un événement par fenêtre de délai de refroidissement.

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

Champ	Type	Description
`event_id` (dans `data`)	UUID	L’identifiant de déclenchement de l’alerte — distinct de l’`event_id` de livraison de l’enveloppe
`rule_id`, `rule_name`	UUID, chaîne	La règle qui s’est déclenchée
`metric`	chaîne	`success_rate`, `failure_rate`, `avg_score`, `call_volume` ou `suite_regression`
`comparator`	chaîne	`lt`, `lte`, `gt` ou `gte`
`metric_value`	nombre	La valeur de la métrique sur la fenêtre lorsque la règle s’est déclenchée
`threshold`	nombre	Le seuil configuré
`window_hours`	entier	Fenêtre d’évaluation glissante
`fired_at`	horodatage

Consultez le guide des alertes pour créer des règles, configurer les métriques, les délais de refroidissement et les canaux e-mail / Slack.

Associé

telephony.incoming / web.incoming

La charge utile bloquante des appels entrants à laquelle vous devez répondre.

telephony.complete / web.complete

Transcription et métriques après l’appel.

Points de terminaison webhook

Abonnez une URL à un sous-ensemble de ces événements.

Outils de fonction

Comment les événements telephony.tool / web.tool sont générés.

Webhooks

Function Tools

Catalogue des événements

Événements d’appel

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Événements de qualité

`call.graded`

`issue.reported`

Événements d’appels de test

`test-call.completed`

Événements d’alerte

`alert.triggered`

Associé

telephony.incoming / web.incoming

telephony.complete / web.complete

Points de terminaison webhook

Outils de fonction

​Événements d’appel

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Événements de qualité

​call.graded

​issue.reported

​Événements d’appels de test

​test-call.completed

​Événements d’alerte

​alert.triggered

​Associé

telephony.incoming / web.incoming

telephony.complete / web.complete

Points de terminaison webhook

Outils de fonction

Événements d’appel

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Événements de qualité

`call.graded`

`issue.reported`

Événements d’appels de test

`test-call.completed`

Événements d’alerte

`alert.triggered`

Associé