---
title: "Variables et contexte par appel"
description: "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.

```json
{
  "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

```text
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é :

```text
<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](/fr/guides/pricing) de l’appel.

Pour un agent à [étapes](/fr/guides/agent-steps), 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` :

```json
{
  "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.

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
```

```json
{
  "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`](/fr/guides/dynamic-call-config) 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](/fr/webhooks/call-incoming).
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](/fr/guides/sip-addresses), 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](/fr/guides/sip-addresses).
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](/fr/guides/embed-web-widget)). 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 :

```json
{
  "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 :

```json
{
  "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](/fr/webhooks/call-incoming) 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 :

```json
{
  "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](/api-reference/validation-sets), les [exécutions de relecture](/api-reference/replay-runs) et les [investigations](/api-reference/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.
