Skip to main content
Lorsqu’un appel téléphonique entrant atteint un numéro sans agent attribué, ou qu’une session de widget web démarre sur une clé publiable en mode="webhook", ThunderPhone envoie une requête bloquante telephony.incoming / web.incoming à votre URL de webhook héritée et attend jusqu’à 10 secondes une réponse de configuration. Utilisez cet échange pour choisir dynamiquement un prompt, une voix et des outils pour chaque appel — consultez le guide de configuration dynamique des appels pour le processus complet.
Les endpoints de webhook abonnés reçoivent également telephony.incoming / web.incoming — pour chaque appel entrant et session web, qu’un agent soit configuré ou non — mais ces livraisons sont des notifications fire-and-forget avec un event_id, et ne sont jamais bloquantes. Seul le webhook hérité à URL unique assure l’échange de configuration décrit sur cette page. Les formats des notifications d’endpoint sont disponibles dans le catalogue des événements.
L’échange bloquant n’a pas de solution de repli : si votre gestionnaire renvoie un statut non 2xx, expire ou renvoie une configuration qui échoue à la validation, l’appel est rejeté (l’appel téléphonique ne se connecte pas ; la requête de session du widget échoue avec 502/422). Répondez rapidement — l’appelant entend la tonalité de retour d’appel pendant que vous décidez.

Charge utile de la requête

Pour les appels téléphoniques (telephony.incoming) :
Pour les sessions de widget web (web.incoming), data identifie la page d’intégration au lieu des numéros de téléphone :
Les widgets en mode webhook envoient cette requête à la webhook_url propre à la clé publiable lorsqu’elle est définie, avec repli sur l’URL de webhook au niveau de l’organisation. Dans tous les cas, elle est signée avec le secret du webhook de l’organisation.

Schéma de réponse

Renvoyez un objet JSON décrivant la configuration de l’agent pour cet appel. prompt et voice sont requis ; tous les autres champs sont facultatifs.
Les clés de niveau supérieur inconnues sont silencieusement ignorées — un nom de champ comportant une faute ne rejette pas la configuration, il ne s’applique simplement pas. L’ordre de parole et max_hold_seconds ne sont pas acceptés ici ; ils sont configurables uniquement sur l’agent lui-même.
Comme prompt et voice sont requis, renvoyer {} ou toute réponse qui échoue à la validation rejette l’appel avec 422 — il n’existe aucun repli vers un agent statique sur ce chemin (un numéro ou une clé en mode webhook n’a aucun agent attribué).

Exemple de gestionnaire


Réponse avec des outils de fonction

Ajoutez des outils afin que l’IA puisse appeler vos API au cours de la conversation :
Les requêtes vers les points de terminaison des outils sont signées avec le même secret de webhook de l’organisation que celui qui a signé cet échange. Consultez Outils de fonction pour connaître la structure exacte et le format des requêtes signées.

Aide-mémoire des niveaux de produit


Associé

telephony.complete / web.complete

L’événement de fin d’appel non bloquant.

Outils de fonction

Schéma JSON complet pour tools[] et le contrat d’endpoint signé.

Endpoints webhook

Abonnez plusieurs URL à telephony.incoming / web.incoming.

Configuration dynamique des appels

Modèles pour les prompts, outils et tests A/B par appelant.