Skip to main content
Par défaut, chaque numéro de téléphone et chaque clé publiable ont un agent statique attribué. Lorsque vous avez besoin d’une personnalisation par appelant ou par visiteur — routage VIP, contexte d’utilisateur connecté, tests A/B de prompt — passez en mode webhook et laissez votre serveur décider.

Fonctionnement

  1. Abonnez-vous à l’événement telephony.incoming (téléphone) ou web.incoming (widget). Les deux sont des webhooks bloquants : ThunderPhone attend jusqu’à 10 secondes votre réponse avant de poursuivre l’appel.
  2. ThunderPhone vous envoie {call_id, from_number, to_number} (les sessions du widget contiennent des champs spécifiques au widget au lieu de numéros — consultez le schéma de requête).
  3. Votre serveur répond avec une configuration d’agent (prompt, voix, produit, outils). ThunderPhone utilise cette configuration pour l’appel.
  4. Si vous renvoyez {}, expirez le délai ou rencontrez une erreur, l’agent attribué statiquement est utilisé comme solution de secours. Valeur par défaut sûre.
Fonctionne de manière identique pour les appels téléphoniques (telephony.incoming) et les sessions de widget (web.incoming), qu’ils soient transmis à un endpoint webhook ou au webhook monourl hérité.

1. Configurer la destination du webhook

Pour les numéros de téléphone, abonnez votre endpoint à telephony.incoming :
La réponse inclut un secret à usage unique — enregistrez-le ; vous l’utiliserez pour vérifier la signature.

2. Implémenter le gestionnaire

Trois règles empiriques :
  • Vérifiez la signature pour chaque requête (voir Vérifier les signatures de webhook). Ne sautez pas cette étape en développement : faites-le correctement une fois, puis réutilisez.
  • Répondez rapidement. Dix secondes est la limite stricte, et chaque seconde est du silence pour l’appelant. Effectuez des recherches en base de données si nécessaire, mais n’appelez pas de LLM en aval de manière synchrone : si vous souhaitez générer des prompts dynamiques, précalculez-les et mettez-les en cache.
  • Prévoyez un repli propre. Tout état inattendu doit renvoyer {} afin que l’agent attribué statiquement prenne en charge l’appel.

3. Schéma de réponse

Le corps de la réponse correspond exactement au schéma de réponse des appels entrants. Les champs couramment utilisés :
Le speak-order par appel et max_hold_seconds ne sont pas disponibles dans la réponse du webhook. Configurez-les sur l’ Agent référencé.

Modèles

Contexte de l’utilisateur connecté

Dans les widgets en mode webhook, la page du visiteur sait déjà qui il est. Appelez votre webhook avec un paramètre de chaîne de requête que le SDK du widget transmet (?customer_id=123) et recherchez le client côté serveur.

Déploiement de prompt A/B

Avant de développer cela vous-même, notez que ThunderPhone dispose d’une fonctionnalité native Expériences (/dashboard/experiments et l’onglet A/B du générateur d’agents) qui définit des variantes, répartit le trafic et compare les résultats par variante — aucun webhook requis. Si vous avez tout de même besoin d’un contrôle côté webhook : hachez call_id → compartiment ; servez le prompt A pour 0..49 et le prompt B pour 50..99. Enregistrez le compartiment choisi dans votre propre base de données, puis corrélez-le ultérieurement avec l’évaluation de l’appel terminé.

Routage selon l’heure

Heures d’ouverture → agent « assistance en direct » ; hors horaires → agent « prise de message ». Simple bascule sur new Date().getUTCHours() dans votre gestionnaire.

Étapes suivantes

Référence du webhook d’appel entrant

Schémas exacts des requêtes et réponses, y compris chaque clé de configuration.

Vérifier les signatures de webhook

Configurez correctement le HMAC une fois ; réutilisez-le partout.

Créer une intégration d’outil

Combinez le routage dynamique avec des outils par agent.

Sémantique de livraison

Tentatives, ordre, délais d’attente.