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

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.
Webhook de variables entrant — enrichissement récupéré au début de l’appel (voir ci-dessous).
Variables système — renseignées par la plateforme à partir du contexte de l’appel.
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

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

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