> ## Documentation Index > Fetch the complete documentation index at: https://docs.famulor.io/llms.txt > Use this file to discover all available pages before exploring further. # Variables personnalisées > Définissez des variables par assistant et injectez des valeurs en direct — API, leads, webhook ou contexte système — dans les prompts, accueils et 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 des variables 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](#variables-système) 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 : **system prompt** * Assistant : **first 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 * **Nœud Transfer** du flow : **number** de destination et **announcement** * **Nœud Warm transfer** du flow : **number** de destination, **caller announcement** et **briefing instructions** * **Built-in tool texts** — **description** de l'outil, **announcement** du transfert, **hold message**, **connected message**, **briefing first message** et **summary instructions** du transfert accompagné, **farewell** à la fin de l'appel, **pre-transfer message** du transfert vers un autre assistant et **prompt** de la collecte de la carte de paiement Ainsi, un nœud Transfer peut orienter chaque appel vers un numéro propre au lead comme `{{handover_number}}`, fourni via les champs personnalisés du lead de campagne, via `variables` dans l'appel API, ou via le webhook de variables entrant — et un briefing de transfert accompagné peut commencer par `Hallo, hier {{assistant_name}} von {{company}} — Anrufer {{caller_name}}`. Voir la [Référence des nœuds](/fr/flow-builder/nodes) pour savoir ce que contrôle chaque champ de flow. Les textes parlés des outils sont substitués deux fois : une première fois au début de l'appel avec les variables d'entrée résolues, puis à nouveau au moment où l'outil s'exécute — les valeurs collectées **pendant** la conversation (via `set_variable` ou des étapes Collect) sont ainsi incluses et restent prioritaires. Ainsi, un nœud d'outil peut appeler `https://api.example.com/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, la plateforme utilise 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](#webhook-de-variables-entrant)). 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.io/api/v1/calls \ -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](/fr/campaigns/overview), chaque lead peut porter des **champs personnalisés** libres. Au moment de la composition, un champ 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 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. Famulor l'appelle au début de l'appel pour enrichir les variables, par exemple à partir du numéro de l'appelant. Il se déclenche avant le début de l'appel ; voir [Webhooks post-appel](/fr/assistants/webhooks) pour ce que Famulor envoie une fois l'appel terminé. ### Requête Famulor 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 avec le secret de webhook configuré. La signature est envoyée dans cet 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 remplacent les variables système et les valeurs par défaut, tandis que les valeurs explicitement transmises pour l'appel restent prioritaires. Si la recherche échoue, l'appel continue avec les valeurs déjà disponibles. ### Automatisation native (alternative) À la place d'un webhook personnalisé, vous pouvez créer une [**Automation**](/fr/automations/overview) avec le déclencheur **Inject input variables** et la rattacher à l'assistant. Ajoutez une action **Return variables** avec la même structure `{ variables: {…} }`. Sans automatisation active correspondante, le webhook configuré est utilisé. ### 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 /api/v1/assistants/{id}/variables` — lit les définitions de variables de l'assistant ; scope `assistants:read`. * `PATCH /api/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.