Developer cookbook

Variables par appel

Personnalisez un agent enregistré pour chaque appel sans modifier son prompt, ses outils ni ses paramètres déployés.

Placez des placeholders dans le prompt de votre agent enregistré, puis fournissez un objet variables au démarrage d'un appel. La configuration enregistrée et l'historique des versions restent inchangés. ThunderPhone effectue le rendu du texte avant d'envoyer la configuration d'appel au runtime vocal.

Lorsqu'aucune valeur n'est nécessaire, omettez variables et n'envoyez pas null (rejeté avec 400).

Placeholders et valeurs par défaut#

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

Les noms sont sensibles à la casse et respectent le format [A-Za-z_][A-Za-z0-9_]*. Les espaces autour du nom sont autorisés ; les espaces après | font partie de la valeur par défaut et sont conservés. {{name|Friend}} utilise Friend lorsque name est absent ou null ; une chaîne vide est une valeur explicitement fournie. Les valeurs absentes sans valeur par défaut deviennent des chaînes vides et leurs noms apparaissent dans unresolved_variables. Le texte entre doubles accolades qui n'est pas un placeholder valide est supprimé. Le texte entre doubles accolades dans chaque valeur fournie est supprimé indépendamment ; une valeur ne peut pas supprimer le texte environnant du prompt ni une autre valeur. Les délimiteurs de doubles accolades non appariés sont également supprimés. Les exemples JSON dans les prompts ne doivent pas utiliser {{. Les valeurs sont du texte brut, jamais évalué comme du code ni développé récursivement comme des modèles.

Les variables peuvent également apparaître dans les prompts d'acquiescements verbaux, les messages de messagerie vocale sortants et le texte de l'annonce de consentement lorsque ce champ est envoyé pour un appel téléphonique. L'agent ne possède pas de champ first_message distinct : placez ses instructions d'ouverture dans le prompt. Les placeholders existants de messagerie vocale {agent_name} et {org_name} continuent de fonctionner.

Les valeurs peuvent être des chaînes, des nombres, des booléens ou null ; les booléens sont rendus sous la forme true et false. Les caractères de contrôle Unicode (Cc), à l'exception du saut de ligne (\n), de la tabulation (\t) et du retour chariot (\r), tous les caractères de format (Cf) et les points de code surrogates (Cs) sont supprimés ; \r\n est normalisé en \n. Chaque valeur est limitée à 2 000 caractères lors du rendu. Les chaînes fournies sont également nettoyées et tronquées avant leur stockage. L'objet d'origine doit tenir dans 32 Ko de JSON UTF-8 ; les objets plus volumineux reçoivent 400 sur les requêtes d'appel/session, tandis que les imports de campagnes signalent individuellement les lignes non valides. Les tableaux et les objets imbriqués ne sont pas acceptés comme valeurs. Les clés de métadonnées non conformes (par exemple, un en-tête CSV contenant un espace) sont conservées et renvoyées, mais ne peuvent pas être référencées par un placeholder.

Origine des valeurs#

API d'appels sortants#

Envoyez variables avec agent_id sur POST /v1/call :

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

Cela fonctionne également avec l'agent sortant par défaut du numéro de téléphone ou avec un config.prompt en ligne. Une clé d'idempotence ne peut pas être réutilisée avec des variables différentes.

CSV de campagne#

Les colonnes CSV qui ne sont pas des numéros de téléphone sont déjà stockées comme variables de contact. Chaque appel les utilise désormais automatiquement. Utilisez des en-têtes tels que name, account_id et appointment_slot pour correspondre à vos espaces réservés. Le mappage de nom existant peut combiner les colonnes de prénom et de nom dans la variable name.

Webhook de configuration dynamique#

Pour le webhook de configuration bloquant, renvoyez un agent enregistré dans votre organisation ainsi que des valeurs par appel :

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

Les clés de la réponse remplacent les variables au niveau de la requête, tandis que les autres clés de la requête restent inchangées. Une valeur de réponse null sélectionne la valeur par défaut de l'espace réservé. L'objet fusionné ne doit pas non plus dépasser 32 Ko. Les réponses d'agent enregistré n'acceptent que agent_id et variables ; renvoyez une configuration en ligne lorsque vous devez remplacer le prompt ou les paramètres. Une réponse contenant prompt utilise toujours une configuration en ligne : tout agent_id dans cette réponse est ignoré, y compris les métadonnées nulles ou non entières. Le prompt en ligne doit toujours passer la validation normale. Les réponses de webhook en ligne peuvent également inclure variables. Les réponses de webhook d'agent enregistré utilisent la répartition A/B déployée de l'agent pour les appels téléphoniques et les appels depuis le widget ; les variables sont rendues après la sélection de la variante. Pour les appels téléphoniques entrants, utilisez un numéro sans agent entrant attribué et configurez son webhook de numéro de téléphone ou d'organisation ; les clés de widget utilisent mode="webhook". Les notifications entrantes du système de points de terminaison ne fournissent pas de réponses de configuration bloquantes.

API de session Widget et Realtime#

POST /v1/widget/session accepte un objet variables de niveau supérieur. Sa clé publiable sélectionne l'agent enregistré. Les clés en mode webhook transmettent ces valeurs au webhook de configuration et fusionnent la réponse comme décrit ci-dessus. Les variables de widget/realtime fournies par le navigateur sont contrôlées par le client, transmises à l'identique dans web.incoming après la validation et le nettoyage des chaînes décrits ci-dessus, et répercutées dans les webhooks de fin et l'historique des appels. Ne les considérez pas comme des données fiables d'identité ou d'autorisation.

POST /v1/realtime/sessions accepte variables avec agent_id (ou un config en ligne). Ce sont des champs d'API de création de session. Le pont WebSocket Realtime ne transmet pas d'option variables ; fournissez-les directement à l' API de création de session. Les clients Widget doivent inclure variables dans la charge utile de session envoyée ; la transmission par SDK ne fait pas partie de cette modification d'API. Les appels de test au micro du Builder et les appels simulés résolvent les valeurs par défaut et les espaces réservés manquants, mais ne disposent d'aucune entrée de variables par appel.

Valeurs renvoyées après l'appel#

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete et web.complete incluent les variables finales fusionnées et unresolved_variables. Les charges utiles de fin héritées qui incluent data.history les incluent également :

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

Stockez l'identifiant de votre CRM ou de votre tâche dans l'objet variables afin d'associer l'appel terminé à son enregistrement source. Ces champs sont conservés avec l'enregistrement d'appel ; n'envoyez que des informations appropriées à conserver dans l'historique des appels et les webhooks.

Compatibilité avec les prompts existants#

Le rendu s’applique également aux prompts existants d’agents enregistrés et de variantes A/B, aux configurations sortantes et en temps réel intégrées, ainsi qu’aux prompts renvoyés par les webhooks de configuration. Les espaces réservés {{name}} inconnus deviennent du texte vide, même lorsqu’aucune variables n’est fournie. Vérifiez les prompts existants avant le déploiement, y compris les prompts intégrés ou de webhook fournis en externe que ThunderPhone ne peut pas répertorier. Les appels au micro du Builder et les appels de simulation appliquent le même comportement par défaut/texte vide.