Catalogue des événements

Chaque corps de webhook comporte un champ type dont la valeur correspond à 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). Ces événements sont transmis selon deux modes :

Les livraisons vers un endpoint sont toujours des notifications non bloquantes avec des tentatives : répondez avec n’importe quel code 2xx ; l’enveloppe contient un event_id 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 d’outils en mode webhook. Votre réponse façonne l’appel en direct.

Les exemples de payloads ci-dessous présentent l’enveloppe de l’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 en envoi unique 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, l’URL de l’enregistrement lorsqu’elle est disponible 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 sur le canal web de telephony.incoming, envoyé lorsqu’une session de widget web ou un appel de test du micro du builder démarre. Les livraisons aux endpoints sont en envoi unique 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 est toujours la valeur littérale "web". Pour les sessions de widget en mode webhook, to_number est vide (le numéro de l’agent de la session est attribué après la configuration) ; pour les appels de test du micro du builder, origin_domain et publishable_key_prefix sont vides.

`web.complete`

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

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

`web.tool`

L’équivalent sur le canal web de telephony.tool. data contient origin_domain à la place de from_number / to_number.

Événements vocaux

La création de voix personnalisées est asynchrone. Ces événements non bloquants vous permettent de réagir à un résultat final au lieu d’interroger le point de terminaison des détails du clone.

`voice.ready`

Envoyé lorsqu’une voix personnalisée termine son traitement et peut être attribuée à un agent.

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

Envoyé lorsque le traitement d’une voix personnalisée rencontre un échec définitif.

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

Champ	Type	Description
`voice.id`	string	Identifiant public de la voix personnalisée
`voice.name`	string	Valeur de la voix de l’agent au format `custom:<public_id>`
`voice.display_name`	string	Nom de la voix destiné à l’organisation
`voice.language`	string	Code de langue unique du clone
`voice.gender`	string	`male`, `female` ou une chaîne vide
`voice.status`	string	`ready` pour `voice.ready` ; `failed` pour `voice.failed`
`voice.failure_reason`	string	Vide en cas de succès ; détail de l’échec de traitement en cas d’échec
`voice.created_at`, `voice.updated_at`	timestamp	Horodatages ISO 8601
`reason`	string	Détail de l’échec ; présent uniquement sur `voice.failed`

Événements de qualité

`call.graded`

Envoyé chaque fois qu’une évaluation par IA est terminée 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` — seuls les traitements terminés émettent cet événement
`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 un modèle une fois l’enregistrement disponible, et des réévaluations manuelles sont possibles. Chaque traitement terminé émet son propre événement call.graded ; considérez le champ graded_at le plus récent comme faisant autorité.

`issue.reported`

Envoyé lorsqu’un rapport de problème est créé — soit soumis par un utilisateur depuis le dashboard (source: "user"), soit automatiquement par l’évaluation de l’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` (soumis depuis le dashboard) ou `system` (créé par l’évaluation)

La réévaluation d’un appel reconstruit ses rapports de problème générés par le système, ce qui réémet issue.reported pour les rapports recréés. Dédupliquez selon call_id + title si vous ne souhaitez recevoir 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 état terminal — completed ou failed, y compris les exécutions qui ont échoué au lancement et n’ont jamais généré d’appel. Non bloquant. Utile pour connecter des exécutions CI par lots à vos systèmes de chat et de 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 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, des métriques, des délais de refroidissement et les canaux e-mail / Slack.

Associés

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 des webhooks

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 vocaux

`voice.ready`

`voice.failed`

Événements de qualité

`call.graded`

`issue.reported`

Événements d’appels de test

`test-call.completed`

Événements d’alerte

`alert.triggered`

Associés

telephony.incoming / web.incoming

telephony.complete / web.complete

Points de terminaison des webhooks

Outils de fonction

​Événements d’appel

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Événements vocaux

​voice.ready

​voice.failed

​Événements de qualité

​call.graded

​issue.reported

​Événements d’appels de test

​test-call.completed

​Événements d’alerte

​alert.triggered

​Associés

telephony.incoming / web.incoming

telephony.complete / web.complete

Points de terminaison des webhooks

Outils de fonction

Événements d’appel

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Événements vocaux

`voice.ready`

`voice.failed`

Événements de qualité

`call.graded`

`issue.reported`

Événements d’appels de test

`test-call.completed`

Événements d’alerte

`alert.triggered`

Associés