ThunderPhone v3 est disponible.En libre-service, à partir de 2 ¢/min.Découvrir l’annonce

Developer cookbook

Variables et contexte par appel

Donnez à chaque appel ses propres informations, sous forme de variables nommées pour le prompt ou d’un brief libre, sans modifier l’agent.

Chaque appel peut contenir deux types d'entrées par appel. Utilisez l'une ou les deux ensemble :

  • variables : valeurs nommées qui renseignent les {{placeholders}} dans le prompt. Utilisez-les pour les champs auxquels le prompt fait référence par leur nom, comme le nom de l'appelant, un numéro de compte ou un créneau de rendez-vous.
  • context : texte libre ajouté après le prompt. Utilisez-le pour un brief qui ne convient pas à un modèle, comme une description de la tâche pour cet appel ou des notes recueillies précédemment.

Les deux fonctionnent avec un agent enregistré et avec une configuration inline, pour toutes les méthodes de démarrage d'un appel décrites ci-dessous. Aucun ne modifie l'agent enregistré, son historique des versions ou ses autres paramètres.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}

Variables

Placez des espaces réservés dans le prompt de votre agent enregistré, puis fournissez un objet variables lors du démarrage d’un appel. ThunderPhone génère le texte avant d’envoyer la configuration de l’appel au runtime vocal.

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

Espaces réservés 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.

Valeurs et limites

Les valeurs peuvent être des chaînes, des nombres, des booléens ou null ; les booléens sont affichés sous forme de 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), les caractères de format (Cf) à l’exception du non-jointeur et du jointeur de largeur nulle (U+200C, U+200D, qui permettent d’écrire des mots dans les langues indiennes et utilisant l’écriture arabe), ainsi que les points de code de substitution (Cs) sont supprimés ; \r\n est normalisé en \n. Chaque valeur est limitée à 2 000 caractères une fois affichée. 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 une erreur 400 dans les requêtes d’appel/session, tandis que les importations 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 correspondantes (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 espace réservé.

Contexte

context est une chaîne pouvant contenir jusqu’à 20 000 caractères. ThunderPhone l’ajoute après le prompt, une fois les variables du prompt renseignées, sous la forme d’un bloc délimité :

<your prompt, with its variables filled in>
 
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>

L’agent le lit avec ses instructions ; rédigez-le donc comme si vous briefiez un collègue avant l’appel. Le contexte n’est pas un modèle : {{name}} qu’il contient reste tel quel. Si le texte a besoin d’une valeur, insérez cette valeur vous-même avant l’envoi.

  • null, une chaîne vide ou uniquement des espaces signifie qu’il n’y a pas de contexte.
  • Une valeur qui n’est pas une chaîne, ou qui dépasse 20 000 caractères, est rejetée avec le code 400 dans les requêtes d’appel et de session ; depuis un webhook de configuration, elle fait échouer l’échange comme des variables non valides (voir ci-dessous).
  • Les espaces au début et à la fin sont supprimés, et les mêmes caractères de contrôle et de format que dans les valeurs de variables sont retirés.
  • Le contexte fait partie du prompt de l’appel ; il compte donc dans la taille du prompt de l’appel.

Pour un agent à étapes, le contexte suit le prompt de chaque agent de l’appel, et non les instructions de chaque étape.

Origine des valeurs

API d'appels sortants

Envoyez variables et context dans POST /v1/call :

{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}

Les deux fonctionnent également avec l'agent sortant par défaut du numéro de téléphone ou avec un config.prompt intégré. Avec une configuration intégrée, context peut aussi être placé dans config, le même champ que renvoie un webhook de configuration ; si vous envoyez les deux, ils doivent contenir le même texte. Une clé d'idempotence ne peut pas être réutilisée avec des variables différentes ou un contexte différent.

CSV de campagne

Les colonnes CSV autres que le numéro de téléphone sont déjà stockées en tant que 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 placeholders. Le mappage de nom existant peut combiner les colonnes de prénom et de nom dans la variable name. Les contacts de campagne n’ont pas de contexte par contact.

Webhook de configuration dynamique

Sur le chemin du webhook de configuration bloquant, renvoyez un agent enregistré dans votre organisation ainsi que toutes les valeurs par appel. Pour un agent Full duplex, l'appel conserve la voix de l'agent même lorsqu'il commence dans une autre langue prise en charge : les associations de voix par langue et le changement de voix natif ne s'appliquent pas à cet appel.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}

Les variables 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 égale à null sélectionne la valeur par défaut de l’espace réservé. L’objet fusionné doit également tenir dans 32 Ko. Les réponses d’agent enregistré n’acceptent que agent_id, variables, context, language et un timezone par appel ; renvoyez une configuration intégrée lorsque vous devez remplacer le prompt ou d’autres paramètres. Les réponses webhook d’agent enregistré utilisent la répartition A/B déployée de l’agent pour les appels téléphoniques comme pour les appels via widget ; les variables sont rendues après la sélection de la variante. Lorsque la réponse définit language pour un agent non Full duplex, l’appel utilise également la voix propre à cette langue si l’agent en a une configurée pour celle-ci. Une réponse contenant prompt utilise toujours une configuration intégrée : tout agent_id présent dans cette réponse est ignoré, y compris les métadonnées nulles ou non entières. Le prompt intégré doit toujours réussir la validation standard. Les réponses webhook intégrées peuvent également inclure variables et context. Un context qui n’est pas une chaîne ou qui est trop long fait échouer l’échange : un appel téléphonique est refusé, et une requête de session de widget échoue avec 400. Les réponses webhook d’agent enregistré utilisent la répartition A/B déployée de l’agent pour les appels téléphoniques comme pour les appels via 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 assigné et configurez le webhook de son numéro de téléphone ou de l’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.

Webhook de configuration d’appel de l’agent

Pour conserver un numéro attribué à son agent et renseigner uniquement les valeurs de l'appel, donnez à l'agent un webhook de configuration d'appel. Avant chaque appel entrant auquel l'agent répond sur un numéro, le webhook reçoit l'appel ainsi que l'identifiant, le nom et la version de l'agent, puis répond avec les mêmes variables, context, language et timezone par appel que ci-dessus, sans nécessiter d'agent_id. Un agent dont les paramètres utilisent un espace réservé sans valeur par défaut a besoin de ce webhook pour répondre à un numéro de téléphone : l'appel ne démarre pas si le webhook échoue. Les espaces réservés avec une valeur par défaut, comme {{name|there}}, permettent à l'agent de répondre sans celui-ci.

En-têtes SIP

Les appels qui parviennent à un agent via SIP (une adresse SIP, ou un numéro sur une connexion SIP manuelle) peuvent transporter du contexte dans les en-têtes X-* et User-to-User. Chacun devient une variable sip_, telle que {{sip_x_amzn_connectcontactid}} ou {{sip_uui}}, avec la priorité la plus faible : une valeur du même nom provenant de l'API ou d'un webhook prévaut. Consultez Transmettre le contexte d'appel dans les en-têtes SIP. Les valeurs des en-têtes sont définies par l'expéditeur ; traitez-les donc comme non fiables, à l'instar de toute valeur fournie par le navigateur.

API de session du widget

POST /v1/widget/session accepte variables et language au 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 du widget fournies par le navigateur sont contrôlées par le client, transmises verbatim dans web.incoming après la validation et le nettoyage des chaînes décrits ci-dessus, puis répercutées dans les webhooks de fin et l’historique des appels. Ne les traitez pas comme des données fiables d’identité ou d’autorisation.

Le champ context du navigateur propre au widget est différent : il transporte le texte de la page consultée par le visiteur, que l’agent traite comme du contenu du site web (voir Intégrer le widget web). Le contexte par appel d’un appel depuis un widget provient du webhook de configuration d’une clé en mode webhook, comme indiqué ci-dessus. Lorsqu’un appel possède les deux, le contexte par appel vient en premier, suivi du contenu de la page.

API de session Realtime

POST /v1/realtime/sessions accepte variables, context et language au niveau supérieur, ainsi que agent_id ou une config intégrée :

{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}

context est accepté uniquement au niveau supérieur ; une config en ligne le rejette comme champ inconnu.

WebSocket en temps réel

Avec un agent enregistré, le prompt déployé de l’agent enregistré reste son prompt. session.instructions devient le contexte de l’appel, session.prompt.variables (ou session.config.variables) deviennent ses variables, et session.language devient sa langue par appel. Sélectionnez l’agent avec session.prompt.id dans le premier session.update, qui démarre la session dès que cette mise à jour arrive :

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}

?agent_id=12 dans l’URL de connexion démarre l’agent dès que le socket se connecte, avant tout session.update, il ne contient donc aucune entrée par appel. Ajoutez &wait_for_session_update=1 pour attendre le premier session.update et utiliser ses instructions et ses variables.

Dans une session inline (sans agent enregistré), session.instructions correspond au prompt lui-même, comme auparavant. Les appels de test dans le navigateur et les simulations résolvent les valeurs par défaut et les placeholders manquants. Pour effectuer un test avec des valeurs, enregistrez un exemple de configuration d’appel sur l’agent et sélectionnez-le au démarrage du test ; l’appel s’exécute comme si votre webhook de configuration d’appel avait répondu avec celui-ci.

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

Le prompt_snapshot de l’appel (GET /v1/calls/{call_id}) affiche le prompt de l’agent avec ses variables renseignées et le bloc de contexte ajouté.

Stockez votre identifiant CRM ou de tâche dans l’objet de variables afin de relier l’appel terminé à son enregistrement source. Les variables et le contexte sont conservés avec l’enregistrement de l’appel ; n’envoyez que des informations pouvant être conservées dans l’historique des appels et les webhooks.

Les relectures d’un appel, dans les ensembles de validation, les exécutions de relecture et les investigations, utilisent les variables et le contexte de cet appel avec le prompt en cours de test ; une relecture teste donc ce qui aurait été communiqué à l’agent lors de cet appel.

Compatibilité avec les prompts existants

Le rendu s’applique également aux prompts existants des agents enregistrés et des variantes A/B, aux configurations sortantes et temps réel inline, 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 inline/webhook fournis en externe que ThunderPhone ne peut pas recenser.
Les appels de test dans le navigateur et les simulations appliquent le même comportement par défaut/vide, sauf si vous sélectionnez un exemple de configuration d’appel enregistrée.