Variables personnalisées

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 :

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. Le texte inconnu à accolades simples reste inchangé ; les espaces réservés inconnus à doubles accolades deviennent vides.

Définir des variables sur un assistant

Éditeur de variables personnalisées avec clé, libellé, valeur par défaut, exemple et description — Settings de l’assistant → Advanced → Automations → Variables : définissez Key et Label, puis ajoutez une valeur par défaut, un exemple et une description si nécessaire.

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 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	Politique de source de valeur : `manual` (par défaut), `lead`, `webhook` ou `system`. `lead` autorise explicitement cet assistant à accéder à l’attribut personnalisé enregistré de même clé dans le workspace et est validé par rapport au catalogue actuel. `system` est réservé aux valeurs intégrées prises en charge.

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
Outil API : URL de la requête, valeurs des en-têtes et valeurs statiques des paramètres — substituées au moment où l’outil s’exécute
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

Les outils API résolvent les variables à chaque requête, y compris les valeurs recueillies pendant la conversation. Les paramètres statiques numériques et booléens conservent leurs variables jusqu’à ce moment. Utilisez Variables d’appel dans la section Requête de test de l’outil pour fournir des exemples. Les variables non résolues des valeurs statiques et des en-têtes deviennent vides ; celles de l’URL restent inchangées. 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 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. Lorsque Transfer to assistant confie l’appel à un autre assistant, le prompt système, le message initial, les textes du flow et les textes des outils intégrés de cet assistant sont remplis de la même façon, avec les valeurs actuelles de l’appel, y compris celles collectées jusque-là. {{assistant_name}} désigne alors l’assistant qui reprend l’appel, et ses propres valeurs par défaut remplissent toute variable pour laquelle l’appel n’a pas de valeur. Les clés absentes peuvent utiliser les valeurs par défaut de l’assistant destinataire ; les valeurs explicitement effacées restent vides. Les variables restent disponibles même sans transmission des messages. Les actions API qui enregistrent des données externes doivent associer les valeurs renvoyées aux variables de l’appel pour les assistants suivants. 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 :

Explicite — valeurs transmises avec l’appel, par exemple variables de l’API make-call.
Webhook de variables entrant — enrichissement récupéré au début de l’appel (voir ci-dessous).
Valeurs actuelles du contact et du système — attributs personnalisés sélectionnés et valeurs remplies par la plateforme à partir du contexte de cet appel.
Variable mémorisée de l’appelant — dernière valeur consentie conservée dans la portée partagée ou privée configurée.
Valeur par défaut — le default_value de la définition.

Un espace réservé à doubles accolades sans valeur devient une chaîne vide. Le texte inconnu à accolades simples reste inchangé.

Valeurs explicites via l’API

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

Transmettez les tâches propres à un appel dans variables, y compris pour les variables manuelles. La même clé dans lead ne donne pas accès au champ du contact. La requête ne modifie ni l’assistant ni le contact ; la conservation suit le réglage de mémoire de chaque variable. Utilisez un objet plat avec des clés snake_case minuscules (64 caractères maximum). Les chaînes acceptent 2000 caractères ; les nombres et booléens deviennent du texte. Les objets imbriqués, tableaux et valeurs null sont refusés. Les caractères de contrôle, la mise en forme invisible et les préfixes de rôle sont retirés. Après le début de l’appel, utilisez MCP get_call avec expected_variables, ou POST /api/v1/calls/{id}/verify-inputs avec { "expected_variables": { "auftrag": "Réserver une consultation" } }. La réponse en lecture seule contient uniquement les clés demandées : matched, missing, different ou not_available. Une preuve indisponible ne signifie ni réussite ni échec ; vérifiez après le début de l’appel. Des valeurs identiques prouvent leur transmission, pas la réussite du scénario. Un appel MCP mis en attente faute de ligne conserve ses entrées. Les appels sortants préremplissent aussi les valeurs par défaut propres à l’appel et les champs de contact sélectionnés avant l’enrichissement. Ces valeurs peuvent primer sur un webhook ultérieur. Une valeur explicite pour cet appel a la priorité maximale.

Leads de campagne → variables

Dans une campagne, 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 :

phone_number,name,company_name,appointment_date
+493012345678,Jordan,Northwind,2026-07-10
+491701234567,Alex,Contoso,2026-07-11

Ici, company_name et appointment_date alimentent {{company_name}} et {{appointment_date}} uniquement après la création de ces champs comme attributs personnalisés du workspace et leur sélection pour cet assistant. Cette sélection crée une définition source: "lead" ; les champs arbitraires ou supprimés ne sont pas exposés. Le nom du contact est une identité distincte, disponible via la variable système intégrée {{customer_name}}.

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 pour ce que Famulor envoie une fois l’appel terminé.

Requête

Famulor envoie une requête POST avec un corps JSON :

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

X-Famulor-Signature: sha256=<hexdigest>

Réponse

Renvoyez les variables à fusionner :

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

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);
}

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

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. 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.

Bien démarrer

Assistants

Constructeur de parcours

Téléphonie

Canaux

Audience

Campagnes

Opérations

Paramètres de l’espace

Facturation

Variables personnalisées

Syntaxe de référence des variables

Définir des variables sur un assistant

Où les variables sont substituées

Sources de valeur et priorité

Valeurs explicites via l’API

Leads de campagne → variables

Variables système

Webhook de variables entrant

Requête

Réponse

Automatisation native (alternative)

Vérifier la signature

Exemple de requête

API et MCP

​Syntaxe de référence des variables

​Définir des variables sur un assistant

​Où les variables sont substituées

​Sources de valeur et priorité

​Valeurs explicites via l’API

​Leads de campagne → variables

​Variables système

​Webhook de variables entrant

​Requête

​Réponse

​Automatisation native (alternative)

​Vérifier la signature

​Exemple de requête

​API et MCP

Syntaxe de référence des variables

Définir des variables sur un assistant

Où les variables sont substituées

Sources de valeur et priorité

Valeurs explicites via l’API

Leads de campagne → variables

Variables système

Webhook de variables entrant

Requête

Réponse

Automatisation native (alternative)

Vérifier la signature

Exemple de requête

API et MCP