> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Variables personnalisées
> Définissez des variables propres à chaque assistant et injectez des valeurs en direct — depuis l'API, les leads d'une campagne, un webhook entrant ou le contexte système — dans les prompts, les messages d'accueil et les outils
Les variables personnalisées vous permettent d'écrire un assistant une seule fois et de personnaliser chaque appel. Plutôt que de coder en dur un nom, un rendez-vous ou un numéro de compte dans le prompt système, vous référencez un espace réservé comme `{{customer_name}}` et fournissez la valeur à chaque appel — depuis votre requête API, un lead de campagne, un webhook d'enrichissement entrant, ou le contexte système intégré à la plateforme.
## Syntaxe de référence
Référencez une variable avec des doubles accolades — la forme à privilégier, compatible JSON :
```text theme={null}
Hi {{customer_name}}, I see your appointment is on {{appointment_date}}.
```
L'ancienne syntaxe à accolade simple `{customer_name}` est également résolue, mais **uniquement pour les clés effectivement connues** (une variable définie ou système). Cela permet de préserver intactes les accolades littérales — par exemple du JSON dans le corps d'un outil. Tout espace réservé dont la clé est inconnue reste inchangé.
## Définir des variables sur un assistant
Chaque assistant possède une liste de définitions de variables. Une définition comprend :
| Champ | Obligatoire | Description |
| --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | oui | L'identifiant utilisé comme `{{key}}`. Doit commencer par une lettre minuscule, suivie de lettres minuscules, de chiffres et de underscores ; 1 à 64 caractères (`^[a-z][a-z0-9_]{0,63}$`). Unique par assistant. Ne peut pas être une [variable système](#system-variables) réservée. |
| `label` | oui | Nom lisible affiché dans l'éditeur. |
| `description` | non | Note sur l'usage de la variable. |
| `default_value` | non | Valeur de repli utilisée lorsqu'aucune valeur n'est fournie au moment de l'appel. |
| `example` | non | Exemple de valeur (éditeur/documentation uniquement, jamais envoyé). |
| `source` | non | Indice informatif : `manual` (par défaut), `lead`, `webhook` ou `system`. Il oriente les indications de l'interface et le mapping du webhook ; il ne restreint pas l'origine réelle d'une valeur. |
Les clés sont validées à l'enregistrement : un format invalide, une collision avec une variable système réservée, une clé en double ou un label manquant sont tous rejetés.
## Où les variables sont substituées
Les valeurs sont substituées au début de l'appel, avant l'exécution du modèle ou du flow, dans les champs suivants :
* Assistant : **prompt système**
* Assistant : **premier message** (message d'accueil)
* Nœud de flow **`start.greeting`**
* Nœud de flow **`agent.instructions`**
* **Nœud d'outil** du flow : **URL** de la requête et **valeurs** des en-têtes
Ainsi, un nœud d'outil peut appeler `https://app.famulor.de/api/user/orders/{{order_id}}` ou envoyer `Authorization: Bearer {{api_token}}` avec des valeurs propres à chaque appel.
## Sources de valeur et priorité
Une valeur peut provenir de plusieurs sources. Au début de l'appel, le worker résout chaque clé selon cet ordre de priorité, du plus élevé au plus faible :
1. **Explicite** — valeurs transmises avec l'appel : `variables` de l'API `make-call`, ou les champs personnalisés d'un lead de campagne mappés sur les clés correspondantes.
2. **Webhook de variables entrant** — enrichissement récupéré au début de l'appel (voir [ci-dessous](#inbound-variable-webhook)).
3. **Variables système** — renseignées par la plateforme à partir du contexte de l'appel.
4. **Valeur par défaut** — le `default_value` de la définition.
Un espace réservé sans valeur à aucun de ces niveaux reste tel quel.
### Valeurs explicites via l'API
```bash theme={null}
curl -X POST https://app.famulor.de/api/user/make-call \
-H "Authorization: Bearer fam_..." \
-H "Content-Type: application/json" \
-d '{
"assistant_id": "asst_123",
"to_number": "+493012345678",
"variables": { "customer_name": "Jordan", "appointment_date": "2026-07-10" }
}'
```
### Leads de campagne → variables
Dans une [campagne](/campaigns/overview), chaque lead porte des **champs personnalisés** libres (`leads.custom_fields`). Au moment de la composition, le champ personnalisé d'un lead est mappé sur une variable portant la **même clé**. Une colonne CSV devient ainsi une variable :
```csv theme={null}
phone_number,name,customer_name,appointment_date
+493012345678,Jordan,Jordan,2026-07-10
+491701234567,Alex,Alex,2026-07-11
```
Ici, les colonnes `customer_name` et `appointment_date` alimentent `{{customer_name}}` et `{{appointment_date}}` pour chaque appel. Attribuez `source: "lead"` à une variable issue d'un lead pour documenter son origine.
## Variables système
Ces clés sont toujours disponibles et renseignées par le worker au début de l'appel. Elles sont réservées : vous ne pouvez pas définir une variable personnalisée portant l'une de ces clés.
| Clé | Libellé | Description | Exemple |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `caller_number` | Numéro de l'appelant | Le numéro de téléphone d'où provient l'appel (entrant) / vers lequel il est passé (sortant), au format E.164. | `+493012345678` |
| `called_number` | Numéro appelé | Le numéro composé / votre numéro qui a reçu l'appel, au format E.164. | `+498998765432` |
| `assistant_name` | Nom de l'assistant | Le nom de l'assistant qui traite l'appel. | `Reception Bot` |
| `direction` | Sens de l'appel | `inbound`, `outbound` ou `web`. | `inbound` |
| `call_id` | ID d'appel | Identifiant unique de cet appel. | `c_a1b2c3` |
| `date` | Date | Date actuelle au début de l'appel (fuseau horaire de l'assistant), au format `YYYY-MM-DD`. | `2026-07-05` |
| `time` | Heure | Heure actuelle au début de l'appel (fuseau horaire de l'assistant), au format `HH:MM`. | `14:30` |
| `datetime` | Date et heure | Date et heure actuelles au début de l'appel (ISO 8601). | `2026-07-05T14:30:00Z` |
| `weekday` | Jour de la semaine | Jour de la semaine actuel au début de l'appel. | `Sunday` |
## Webhook de variables entrant
Pour les appels **entrants**, vous ne connaissez souvent pas l'appelant à l'avance. Configurez un **webhook de variables** sur l'assistant (`variable_webhook_url` + `variable_webhook_secret`) : le worker l'appelle au début de l'appel pour enrichir les variables — par exemple en recherchant un client à partir de son numéro d'appelant.
### Requête
Le worker envoie une requête `POST` avec un corps JSON :
```json theme={null}
{
"event": "call.variables",
"assistant_id": "asst_123",
"call_id": "c_a1b2c3",
"direction": "inbound",
"from_number": "+493012345678",
"to_number": "+498998765432"
}
```
Le corps brut de la requête est signé en HMAC-SHA256 à l'aide du `variable_webhook_secret` de l'assistant, envoyé dans l'en-tête :
```text theme={null}
X-Famulor-Signature: sha256=
```
### Réponse
Renvoyez les variables à fusionner :
```json theme={null}
{
"variables": {
"customer_name": "Jordan",
"open_amount": "128.50"
}
}
```
Ces valeurs se fusionnent **au-dessus** des variables système et des valeurs par défaut, mais **en dessous** de toute valeur explicite transmise à l'appel. La requête expire au bout d'environ 5 s ; un échec n'est pas bloquant — le worker le journalise et poursuit avec les valeurs déjà disponibles.
### Automatisation native (alternative)
Plutôt qu'un `variable_webhook_url` personnalisé, vous pouvez créer une **Automatisation** avec le déclencheur **Injecter des variables d'entrée** (`call.variables`) rattaché à l'assistant. Au début de l'appel, le worker exécute cette automatisation de façon synchrone et attend une action **Renvoyer les variables** (même structure `{ variables: {…} }`). En l'absence d'automatisation active correspondante, l'URL du webhook classique est utilisée en repli.
### Vérifier la signature
```js Node.js theme={null}
import crypto from "node:crypto";
// rawBody : les octets exacts reçus, avant JSON.parse
function verify(rawBody, signatureHeader, secret) {
const expected =
"sha256=" +
crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(signatureHeader);
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```
```python Python theme={null}
import hmac, hashlib
# raw_body : les octets exacts reçus, avant json.loads
def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(
secret.encode(), raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature_header)
```
Calculez toujours le HMAC sur les octets **bruts** du corps de la requête, jamais sur un objet resérialisé — la resérialisation peut modifier les espaces ou l'ordre des clés et casser la signature. Utilisez une comparaison à temps constant.
### Exemple de requête
```bash theme={null}
curl -X POST https://your-app.example.com/famulor/variables \
-H "Content-Type: application/json" \
-H "X-Famulor-Signature: sha256=6d3a...e1f0" \
-d '{
"event": "call.variables",
"assistant_id": "asst_123",
"call_id": "c_a1b2c3",
"direction": "inbound",
"from_number": "+493012345678",
"to_number": "+498998765432"
}'
```
## API et MCP
* `GET /v1/assistants/{id}/variables` — lit les définitions de variables de l'assistant ; scope `assistants:read`.
* `PATCH /v1/assistants/{id}/variables` — remplace les définitions de variables ; scope `assistants:write`.
* Outils MCP : `get_assistant_variables`, `set_assistant_variables`.
La référence REST complète se trouve sur [docs.famulor.io](https://docs.famulor.io). Utilisez `{{key}}` partout où vous avez besoin d'une valeur propre à l'appel, gardez vos clés en `snake_case`, et donnez à chaque variable un `default_value` pertinent pour que les appels se dégradent proprement en cas de source manquante.