Custom variables

Custom variables let you write an assistant once and personalize every call. Instead of hard-coding a name, an appointment, or an account number into the system prompt, you reference a placeholder like {{customer_name}} and supply the value per call — from your API request, a campaign lead, an inbound enrichment webhook, or the platform’s built-in system context.

Variable reference syntax

Reference a variable with double braces — the preferred, JSON-safe form:

Hi {{customer_name}}, I see your appointment is on {{appointment_date}}.

The legacy single-brace form {customer_name} is also resolved, but only for keys that are actually known (a defined or system variable). This keeps literal braces — for example JSON in a tool body — intact. Unknown single-brace text is left untouched; unknown double-brace placeholders become empty.

Defining variables on an assistant

Custom variable editor with key, label, default value, example and description fields — Assistant Settings → Advanced → Automations → Variables: define Key and Label, then add an optional default value, example and description.

Each assistant carries a list of variable definitions. A definition has:

Field	Required	Description
`key`	yes	The identifier used as `{{key}}`. Lowercase letter first, then lowercase letters, digits, and underscores; 1–64 characters (`^[a-z][a-z0-9_]{0,63}$`). Unique per assistant. Cannot be a reserved system variable.
`label`	yes	Human-readable name shown in the editor.
`description`	no	Note on what the variable is for.
`default_value`	no	Fallback used when no value is supplied at call time.
`example`	no	Sample value (editor/docs only, never sent).
`source`	no	Value-source policy: `manual` (default), `lead`, `webhook`, or `system`. `lead` explicitly grants this assistant access to the same-key registered workspace Custom Attribute and is validated against the current catalog. `system` is reserved for supported built-in defaults.

Keys are validated on save: invalid format, a collision with a reserved system variable, a duplicate key, or a missing label are all rejected.

Where variables are substituted

Values are substituted at call start, before the model or flow runs, in these fields:

Assistant system prompt
Assistant first message (greeting)
Flow node start.greeting
Flow node agent.instructions
Flow tool node request URL and header values
API tool request URL, header values, and static parameter values — substituted at the moment the tool runs
Flow transfer node destination number and announcement
Flow warm transfer node destination number, caller announcement, and briefing instructions
Built-in tool texts — tool description, transfer announcement, warm-transfer hold message, connected message, briefing first message, summary instructions, end-call farewell, assistant-transfer pre-transfer message, and payment-collection prompt

API tools resolve variables when each request runs, including values collected during the conversation. Static number and boolean parameters keep their templates until that point. Use Call variables in the tool’s Test request section to supply sample values. Unresolved static/header placeholders become empty; unresolved endpoint URL placeholders remain unchanged. So a transfer node can route each call to a per-lead number like {{handover_number}}, supplied via campaign lead fields, the API call’s variables, or the inbound variable-webhook — and a warm-transfer briefing can open with Hallo, hier {{assistant_name}} von {{company}} — Anrufer {{caller_name}}. See the Node reference for what each flow field controls. Spoken tool texts are substituted twice: once at call start with the resolved input variables, and again at the moment the tool runs — so values collected during the conversation (via set_variable or collect steps) are included and take precedence. When Transfer to assistant hands the call to another assistant, that assistant’s system prompt, first message, flow texts and built-in tool texts are filled the same way, with the call’s current values, including values collected so far. {{assistant_name}} then names the receiving assistant, and its own default values fill any variable the call has no value for. Missing keys may use the receiving assistant’s defaults; explicitly cleared values stay empty. Variables remain available even when no conversation messages are passed. API actions that save data externally must map returned values to call variables if later assistants should use them. For example, a tool node can call https://api.example.com/orders/{{order_id}} or send Authorization: Bearer {{api_token}} with per-call values.

Value sources & precedence

A value can arrive from several places. At call start the platform uses this precedence, highest first:

Explicit — values passed with the call, such as API make-call variables.
Inbound variable-webhook — enrichment fetched at call start (see below).
Current contact and system values — selected Custom Attributes and values filled by the platform from this call’s context.
Remembered caller variable — the last consented value kept in the configured Shared or Private scope.
Default — the definition’s default_value.

A double-brace placeholder with no value becomes an empty string. Unknown legacy single-brace text stays unchanged.

Explicit values via the 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" }
  }'

Pass one-call tasks in variables, including values for Manual variables. Putting the same key in lead does not grant access to that contact field. This request does not edit the assistant or contact; retention follows each variable’s Caller memory setting. Values must be a flat object with lowercase snake_case keys (up to 64 characters). Strings accept up to 2000 characters; numbers and booleans become text. Nested objects, arrays and null values are rejected. Control characters, invisible formatting and role-marker prefixes are removed before use. After a call starts, use MCP get_call with expected_variables, or send POST /api/v1/calls/{id}/verify-inputs with { "expected_variables": { "auftrag": "Book a consultation" } }. The read-only response reports only the requested keys: matched, missing, different, or not_available. A missing snapshot is not a failed or passed test; check again after the call starts. Matching inputs verifies delivery, not the scenario outcome. A capacity-queued MCP call retains its inputs. Outbound calls also prefill call-only defaults and selected contact values before call-start enrichment; those prefilled values can take precedence over a later webhook. An explicit per-call value has the highest priority.

Campaign leads → variables

In a campaign, each lead can include free-form custom fields. At dial time, a custom field is mapped onto a variable with the same key, so a CSV column becomes a variable:

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

Here company_name and appointment_date populate {{company_name}} and {{appointment_date}} only after those fields exist as workspace Custom Attributes and are selected for this assistant. That selection creates a definition with source: "lead"; arbitrary or deleted lead fields are not exposed. Contact name is separate identity data and is available through the built-in {{customer_name}} system variable.

System variables

These keys are always available at call start. They are reserved — you cannot define a custom variable with one of these keys.

Key	Label	Description	Example
`caller_number`	Caller number	The phone number the call is coming from (inbound) / being placed to (outbound), E.164.	`+493012345678`
`called_number`	Called number	The number that was dialed / your number that received the call, E.164.	`+498998765432`
`assistant_name`	Assistant name	The name of the assistant handling the call.	`Reception Bot`
`direction`	Call direction	`inbound`, `outbound` or `web`.	`inbound`
`call_id`	Call ID	Unique identifier of this call.	`c_a1b2c3`
`date`	Date	Current date at call start (assistant timezone), `YYYY-MM-DD`.	`2026-07-05`
`time`	Time	Current time at call start (assistant timezone), `HH:MM`.	`14:30`
`datetime`	Date & time	Current date and time at call start (ISO 8601).	`2026-07-05T14:30:00Z`
`weekday`	Weekday	Current weekday at call start.	`Sunday`

Inbound variable-webhook

For inbound calls you often don’t know the caller in advance. Configure a variable webhook on the assistant and Famulor calls it at call start to enrich variables — for example, to look up a customer by their caller number. This fires before the call starts; see Post-call webhooks for what Famulor sends after one ends.

Request

Famulor sends a POST with a JSON body:

{
  "event": "call.variables",
  "assistant_id": "asst_123",
  "call_id": "c_a1b2c3",
  "direction": "inbound",
  "from_number": "+493012345678",
  "to_number": "+498998765432"
}

The raw request body is signed with HMAC-SHA256 using the webhook secret configured for the assistant. The signature is sent in this header:

X-Famulor-Signature: sha256=<hexdigest>

Response

Return the variables to merge:

{
  "variables": {
    "customer_name": "Jordan",
    "open_amount": "128.50"
  }
}

These values override system variables and defaults, but explicit values supplied for the call take precedence. If the lookup fails, the call continues with the values already available.

Native automation (alternative)

Instead of a custom webhook, you can create an Automation with the Inject input variables trigger and bind it to the assistant. Add a Return variables action using the same { variables: {…} } response shape. If no matching automation is active, the configured webhook is used.

Verifying the signature

import crypto from "node:crypto";

// rawBody: the exact bytes received, before 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: the exact bytes received, before 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)

Always compute the HMAC over the raw request body bytes, not over a re-serialized object — re-serialization can change whitespace or key order and break the signature. Use a constant-time comparison.

Example request

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 & MCP

GET /api/v1/assistants/{id}/variables — read the assistant’s variable definitions; scope assistants:read.
PATCH /api/v1/assistants/{id}/variables — replace the variable definitions; scope assistants:write.
MCP tools: get_assistant_variables, set_assistant_variables.

Full REST reference lives at docs.famulor.io. Use {{key}} everywhere you want a per-call value, keep keys snake_case, and give every variable a sensible default_value so calls degrade gracefully when a source is missing.

Getting started

Assistants

Flow builder

Telephony

Channels

Audience

Campaigns

Live operations

Workspace settings

Billing

Custom variables

Variable reference syntax

Defining variables on an assistant

Where variables are substituted

Value sources & precedence

Explicit values via the API

Campaign leads → variables

System variables

Inbound variable-webhook

Request

Response

Native automation (alternative)

Verifying the signature

Example request

API & MCP

​Variable reference syntax

​Defining variables on an assistant

​Where variables are substituted

​Value sources & precedence

​Explicit values via the API

​Campaign leads → variables

​System variables

​Inbound variable-webhook

​Request

​Response

​Native automation (alternative)

​Verifying the signature

​Example request

​API & MCP

Variable reference syntax

Defining variables on an assistant

Where variables are substituted

Value sources & precedence

Explicit values via the API

Campaign leads → variables

System variables

Inbound variable-webhook

Request

Response

Native automation (alternative)

Verifying the signature

Example request

API & MCP