Webhooks

Catalogue des événements

Tous les types d’événements webhook émis par ThunderPhone.

Chaque corps de webhook comporte un champ type dont la valeur est l’un des types d’événements de cette page. Lorsque vous vous abonnez à un point de terminaison, le tableau events doit contenir les types d’événements souhaités (ou être vide pour vous abonner à tous les événements — à l’exception des événements par tour telephony.turn / web.turn, qui sont envoyés uniquement aux points de terminaison qui les nomment explicitement).

Ces événements sont transmis selon deux modes :

• Les livraisons vers un point de terminaison sont toujours des notifications non bloquantes avec des nouvelles tentatives : répondez avec n’importe quel code 2xx ; l’enveloppe contient un event_id pour le dédoublonnage.
• 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 cours.

Les exemples de payloads ci-dessous présentent l’enveloppe de point de terminaison 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 envois vers les points de terminaison sont des notifications sans attente 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 historique — consultez telephony.incoming / web.incoming pour le schéma complet de la requête et de la 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, ainsi qu'un 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 envoyé ; 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 est le 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.

telephony.turn#

Envoyé pendant qu'un appel téléphonique est en cours, une fois pour chaque tour contenant de la parole au moment où il se produit — les réponses prononcées de l'agent et les tours transcrits de l'appelant. Permet de suivre la conversation en direct via de simples webhooks au lieu d'interroger GET /v1/calls/{call_id}/transcript. Non bloquant.

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

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 générateur démarre. Les envois vers les points de terminaison sont sans attente pour chaque session web. Les clés publiables en mode="webhook" reçoivent également la requête de configuration bloquante sur le webhook historique — 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 contient 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 dans le générateur, 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 générateur (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".

web.tool#

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

web.turn#

L'équivalent de telephony.turn pour le canal web, couvrant les appels de widget web et les appels de test du micro dans le générateur. Même structure de charge utile, avec origin_domain au lieu de from_number / to_number. Comme telephony.turn, il nécessite un abonnement explicite — il n'est jamais envoyé via un tableau events vide.

É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 régulièrement 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"
}

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

issue.reported#

Envoyé lorsqu’un signalement de problème est créé — soit soumis par un utilisateur depuis le tableau de bord (source: "user"), soit automatiquement par l’évaluation des appels (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"
}

É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 ayant échoué au lancement et n’ayant jamais produit d’appel. Non bloquant. Utile pour connecter des exécutions CI par lot à vos systèmes de messagerie 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"
}

Événements d’alerte#

alert.triggered#

Envoyé lorsqu’une règle d’alerte dont le canal Envoyer vers les webhooks des développeurs est activé franchit son seuil. Non bloquant. Une règle se déclenche une fois, puis respecte son délai de récupération ; ainsi, un dépassement continu produit un événement par fenêtre de récupération.

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

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

Associé#