{{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.
Watch the walkthrough
The English interface uses isolated example data. Changes and results in this walkthrough are demonstrations.Variable reference syntax
Reference a variable with double braces — the preferred, JSON-safe 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

Assistant Settings → Advanced → Automations → Variables: define Key and Label, then add an optional default value, example and description.
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
{{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.
Messaging and email replies
Messaging channels, including WhatsApp and Zendesk, and native email use the current conversation’s permitted variables. Generated replies and model-written SMS/email tool messages resolve placeholders before sending. Values inserted into a link are URL-encoded. A missing or empty link value blocks that draft instead of sending an incomplete identifier. Fixed email content stays literal; choose template mode when the configured content contains variables. A CRM identifier must exist as a workspace Custom Attribute and be shared with the assistant. A field saved only on a contact is not sufficient. Do not replace an external CRM identifier with the contact’s internal ID. Test the resulting link with an example contact before starting a campaign.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-callvariables. - 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.
Explicit values via the API
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: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.Caller recognition from connected systems
When a native integration such as Hostaway, WooCommerce, Shopware 6 or onOffice is connected as an Agent Tool, the assistant can recognise the caller before the greeting. A guest calls the holiday apartment, the number matches exactly one booking, and the assistant opens with “Hello Anna, you arrive on Friday. How can I help?” instead of asking for a name and a booking code. Famulor looks the number up in each connected system for at most 2.5 seconds, in parallel with your own call-start webhook or automation. A slow or unreachable system never delays the call: the conversation starts on time without its values. A fixed first message or a greeting audio is spoken as saved, because the values only reach the assistant’s next answer. For the greeting by name, put the variable into the first message (for exampleHello {{hostaway_guest_first_name}}, with a default value for callers without a match) or leave the first message empty so that the assistant words the greeting itself.
What the assistant receives
Each match adds variables whose names start with the system name, for examplehostaway_guest_first_name or hostaway_arrival_date. The assistant treats them as data about the caller, never as instructions, and does not say that it looked the caller up. Door codes, Wi-Fi passwords, payment data, email addresses and phone numbers are never passed this way: sensitive details still need the checks of the integration’s tools.
Values from explicit call variables, your call-start webhook or your automation win over them. They are not saved in caller memory, so every call starts from the current state of the connected system. If several records match one number, or two connections of one system both match, the assistant receives no values and asks the caller for details.
Where it runs
Simulations, avatars, Translate sessions and Milian never look callers up.
Switch it off for one tool
In Agent Tools, open the integration and turn off Recognise callers before the conversation. The switch is on by default for integrations that can recognise callers. Through the API, sendcaller_recognition to POST /api/v1/tools/integrations/{provider}, or in the mcp config of PATCH /api/v1/tools/{id}. The CLI takes famulor connect-integration <provider> --caller-recognition false.
See what happened
The call history lists every lookup under Before the conversation with its status and duration: Caller recognised, Several matches, No match, Number withheld, Too slow, skipped or Failed. The values themselves appear with the call’s input variables.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 aPOST with a JSON body:
Response
Return the variables to merge: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.
Chat channels and email
The same webhook runs once at the start of a chat conversation (WhatsApp, Messenger, Instagram and the other messaging channels) or an email thread, before the assistant’s first reply. Famulor sends these fields. There is no call ID;conversation_id identifies the conversation:
channel is messaging or email. from_number is the customer’s phone number when the channel has one, contact_email the sender’s address for emails (otherwise null); to_number is always null. The signature, response format and 5-second limit are the same as for calls. Values you return are kept for the whole conversation, so Famulor does not ask again. Values already set in the conversation take precedence over the webhook. Emails trigger the webhook only for verified senders. If the lookup fails, the conversation continues without the values.
It runs only when the customer writes first. Conversations the business starts, for example a WhatsApp template sent first, do not trigger it.
An Automation bound under Inbound (conversation start) works here too and runs before the webhook. It receives the same fields, and call_id holds the conversation ID. It has 8 seconds to answer; if it returns nothing, the webhook is used.
Verifying the signature
Example request
API & MCP
GET /api/v1/assistants/{id}/variables— read the assistant’s variable definitions; scopeassistants:read.PATCH /api/v1/assistants/{id}/variables— replace the variable definitions; scopeassistants:write.- MCP tools:
get_assistant_variables,set_assistant_variables.