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

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

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

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 :

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

X-Famulor-Signature: sha256=<hexdigest>

Réponse

Renvoyez les variables à fusionner :

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

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

Automatisations

Téléphonie

Canaux

Campagnes

Opérations

Variables personnalisées

Syntaxe de référence

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

​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

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