Benutzerdefinierte Variablen

Mit benutzerdefinierten Variablen schreibst du einen Assistenten einmal und personalisierst trotzdem jeden Anruf. Statt einen Namen, einen Termin oder eine Kontonummer fest in den System-Prompt zu schreiben, referenzierst du einen Platzhalter wie {{customer_name}} und lieferst den Wert pro Anruf – aus deiner API-Anfrage, einem Kampagnen-Lead, einem eingehenden Anreicherungs-Webhook oder dem eingebauten Systemkontext der Plattform.

Referenzsyntax

Referenziere eine Variable mit doppelten geschweiften Klammern – das ist die bevorzugte, JSON-sichere Form:

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

Die alte Form mit einfachen Klammern {customer_name} wird ebenfalls aufgelöst, allerdings nur für Schlüssel, die tatsächlich bekannt sind (eine definierte Variable oder eine Systemvariable). So bleiben literale Klammern – zum Beispiel JSON im Body eines Tools – unangetastet. Unbekannter Text mit einfachen Klammern bleibt erhalten; unbekannte Platzhalter mit doppelten Klammern werden leer.

Variablen für einen Assistenten definieren

Editor für benutzerdefinierte Variablen mit Schlüssel, Bezeichnung, Standardwert, Beispiel und Beschreibung — Assistenten-Settings → Advanced → Automations → Variables: Lege Key und Label fest und ergänze bei Bedarf Standardwert, Beispiel und Beschreibung.

Jeder Assistent hat eine Liste von Variablendefinitionen. Eine Definition besteht aus:

Feld	Erforderlich	Beschreibung
`key`	ja	Der Bezeichner, der als `{{key}}` verwendet wird. Beginnt mit einem Kleinbuchstaben, danach Kleinbuchstaben, Ziffern und Unterstriche; 1–64 Zeichen (`^[a-z][a-z0-9_]{0,63}$`). Pro Assistent eindeutig. Darf keine reservierte Systemvariable sein.
`label`	ja	Für Menschen lesbarer Name, der im Editor angezeigt wird.
`description`	nein	Notiz, wofür die Variable gedacht ist.
`default_value`	nein	Fallback-Wert, der genutzt wird, wenn zum Zeitpunkt des Anrufs kein Wert übergeben wird.
`example`	nein	Beispielwert (nur für Editor/Doku, wird nie gesendet).
`source`	nein	Richtlinie für die Wertquelle: `manual` (Standard), `lead`, `webhook` oder `system`. `lead` gibt diesem Assistenten ausdrücklich Zugriff auf das gleichnamige registrierte Custom Attribute des Workspace und wird gegen den aktuellen Katalog geprüft. `system` ist unterstützten integrierten Standardwerten vorbehalten.

Schlüssel werden beim Speichern validiert: Ein ungültiges Format, eine Kollision mit einer reservierten Systemvariable, ein doppelter Schlüssel oder ein fehlendes Label werden allesamt abgelehnt.

Wo Variablen ersetzt werden

Werte werden beim Start des Anrufs ersetzt, bevor Modell oder Flow laufen – und zwar in diesen Feldern:

system prompt des Assistenten
first message des Assistenten (Begrüßung)
Flow-Node start.greeting
Flow-Node agent.instructions
URL und Header-values der Anfrage im Flow-Tool-Node
URL, Header-values und statische Parameterwerte eines API-Tools – ersetzt im Moment der Tool-Ausführung
Ziel-number und announcement im Flow-Transfer-Node
Ziel-number, caller announcement und briefing instructions im Flow-Warm-Transfer-Node
Built-in tool texts – description des Tools, announcement bei der Weiterleitung, hold message, connected message, briefing first message und summary instructions beim Warm Transfer, farewell beim Beenden des Anrufs, pre-transfer message bei der Übergabe an einen anderen Assistenten und prompt beim Erfassen der Zahlungskarte

API-Tools lösen Variablen bei jeder Anfrage auf, einschließlich im Gespräch erfasster Werte. Statische Zahlen- und Wahrheitswert-Parameter behalten bis dahin ihre Platzhalter. Gib im Bereich Testanfrage des Tools unter Anrufvariablen Beispielwerte ein. Nicht aufgelöste Platzhalter in statischen Werten und Headern werden leer; in der Endpunkt-URL bleiben sie unverändert. So kann ein Transfer-Node jeden Anruf an eine Lead-spezifische Nummer wie {{handover_number}} weiterleiten, geliefert über die benutzerdefinierten Felder des Kampagnen-Leads, variables im API-Aufruf oder den eingehenden Variablen-Webhook – und ein Warm-Transfer-Briefing kann mit Hallo, hier {{assistant_name}} von {{company}} — Anrufer {{caller_name}} beginnen. Was jedes Flow-Feld steuert, steht in der Flow-Knotenreferenz. Gesprochene Tool-Texte werden zweimal ersetzt: einmal beim Start des Anrufs mit den aufgelösten Eingabevariablen, und erneut in dem Moment, in dem das Tool ausgeführt wird – dadurch sind auch Werte enthalten, die während des Gesprächs erfasst wurden (über set_variable oder Collect-Schritte), und diese haben Vorrang. Übergibt Transfer to assistant den Anruf an einen anderen Assistenten, werden dessen System-Prompt, erste Nachricht, Flow-Texte und Built-in-Tool-Texte genauso ersetzt – mit den aktuellen Werten des Anrufs, einschließlich der bis dahin erfassten Werte. {{assistant_name}} ist dann der Name des übernehmenden Assistenten, und seine eigenen Standardwerte füllen jede Variable, für die der Anruf keinen Wert hat. Fehlende Schlüssel können die Standardwerte des Ziel-Assistenten verwenden; ausdrücklich geleerte Werte bleiben leer. Variablen bleiben auch ohne übergebene Gesprächsnachrichten verfügbar. Speichert eine API-Aktion Daten extern, müssen zurückgegebene Werte Call-Variablen zugeordnet werden, damit spätere Assistenten sie verwenden können. So kann ein Tool-Node https://api.example.com/orders/{{order_id}} aufrufen oder Authorization: Bearer {{api_token}} mit Werten pro Anruf senden.

Wertquellen und Priorität

Ein Wert kann aus mehreren Quellen kommen. Beim Start des Anrufs verwendet die Plattform diese Priorität, höchste zuerst:

Explizit – Werte, die direkt mit dem Anruf übergeben werden, zum Beispiel über variables im API-Aufruf make-call.
Eingehender Variablen-Webhook – Anreicherung, die beim Start des Anrufs abgerufen wird (siehe unten).
Aktuelle Kontakt- und Systemwerte – ausgewählte Custom Attributes und Werte, die die Plattform aus dem Kontext dieses Anrufs befüllt.
Gespeicherte Anrufer-Variable – der letzte eingewilligte Wert aus dem konfigurierten gemeinsamen oder privaten Bereich.
Standardwert – der default_value aus der Definition.

Ein Platzhalter mit doppelten Klammern ohne Wert wird durch einen leeren String ersetzt. Unbekannter Text mit einfachen Klammern bleibt unverändert.

Explizite Werte über die 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" }
  }'

Einmalige Aufgaben gehören in variables, auch für manuelle Variablen. Derselbe Schlüssel in lead erteilt keinen Zugriff auf das Kontaktfeld. Die Anfrage ändert weder Assistent noch Kontakt; die Speicherung richtet sich nach der Anrufergedächtnis-Einstellung jeder Variable. Erlaubt ist ein flaches Objekt mit kleingeschriebenen snake_case-Schlüsseln (bis zu 64 Zeichen). Strings dürfen bis zu 2000 Zeichen haben; Zahlen und boolesche Werte werden zu Text. Verschachtelte Objekte, Arrays und null-Werte werden abgelehnt. Steuerzeichen, unsichtbare Formatierung und Rollenpräfixe werden vor der Verwendung entfernt. Nach dem Call-Start prüfst du die Eingaben mit MCP get_call und expected_variables oder mit POST /api/v1/calls/{id}/verify-inputs und { "expected_variables": { "auftrag": "Beratungstermin buchen" } }. Die schreibgeschützte Antwort enthält nur die angefragten Schlüssel: matched, missing, different oder not_available. Ein fehlender Nachweis ist weder ein bestandener noch ein fehlgeschlagener Test; prüfe nach dem Call-Start erneut. Passende Eingaben belegen ihre Übergabe, nicht das Szenarioergebnis. Ein wegen ausgelasteter Leitungen vorgemerkter MCP-Call behält seine Eingaben. Outbound-Calls befüllen außerdem callbezogene Standardwerte und ausgewählte Kontaktwerte vor der Anreicherung. Diese Werte können Vorrang vor einem späteren Webhook haben. Ein expliziter Wert für diesen Call hat die höchste Priorität.

Kampagnen-Leads → Variablen

In einer Kampagne kann jeder Lead frei definierbare benutzerdefinierte Felder haben. Beim Wählen wird ein Feld auf eine Variable mit dem gleichen Schlüssel gemappt. So wird aus einer CSV-Spalte eine Variable:

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

Hier befüllen company_name und appointment_date {{company_name}} und {{appointment_date}} erst, nachdem diese Felder als Custom Attributes des Workspace existieren und für diesen Assistenten ausgewählt wurden. Diese Auswahl erzeugt eine Definition mit source: "lead"; beliebige oder gelöschte Lead-Felder werden nicht freigegeben. Der Kontaktname ist eine getrennte Identität und steht über die integrierte Systemvariable {{customer_name}} bereit.

Systemvariablen

Diese Schlüssel sind beim Start des Anrufs immer verfügbar. Sie sind reserviert – du kannst keine benutzerdefinierte Variable mit einem dieser Schlüssel anlegen.

Schlüssel	Label	Beschreibung	Beispiel
`caller_number`	Anrufernummer	Die Telefonnummer, von der der Anruf kommt (eingehend) bzw. an die er geht (ausgehend), E.164.	`+493012345678`
`called_number`	Angerufene Nummer	Die gewählte Nummer bzw. deine Nummer, die den Anruf empfangen hat, E.164.	`+498998765432`
`assistant_name`	Name des Assistenten	Der Name des Assistenten, der den Anruf bearbeitet.	`Reception Bot`
`direction`	Anrufrichtung	`inbound`, `outbound` oder `web`.	`inbound`
`call_id`	Anruf-ID	Eindeutige ID dieses Anrufs.	`c_a1b2c3`
`date`	Datum	Aktuelles Datum beim Start des Anrufs (Zeitzone des Assistenten), `YYYY-MM-DD`.	`2026-07-05`
`time`	Uhrzeit	Aktuelle Uhrzeit beim Start des Anrufs (Zeitzone des Assistenten), `HH:MM`.	`14:30`
`datetime`	Datum & Uhrzeit	Aktuelles Datum und Uhrzeit beim Start des Anrufs (ISO 8601).	`2026-07-05T14:30:00Z`
`weekday`	Wochentag	Aktueller Wochentag beim Start des Anrufs.	`Sunday`

Eingehender Variablen-Webhook

Bei eingehenden Anrufen kennst du den Anrufer oft nicht im Voraus. Konfiguriere einen Variablen-Webhook am Assistenten. Famulor ruft ihn beim Start auf, um Variablen anzureichern, zum Beispiel anhand der Anrufernummer. Das passiert vor dem Anruf; was Famulor nach dessen Ende sendet, steht unter Webhooks nach dem Anruf.

Anfrage

Famulor sendet einen POST mit JSON-Body:

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

Der rohe Request-Body wird mit HMAC-SHA256 und dem konfigurierten Webhook-Secret signiert. Die Signatur wird im Header mitgesendet:

X-Famulor-Signature: sha256=<hexdigest>

Antwort

Gib die zu mergenden Variablen zurück:

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

Diese Werte überschreiben Systemvariablen und Standardwerte; explizit für den Anruf übergebene Werte haben Vorrang. Schlägt der Abruf fehl, läuft der Anruf mit den bereits vorhandenen Werten weiter.

Native Automation (Alternative)

Statt eines eigenen Webhooks kannst du eine Automation mit dem Trigger Inject input variables anlegen und an den Assistenten binden. Füge eine Aktion Return variables mit demselben { variables: {…} }-Format hinzu. Ohne passende aktive Automation wird der konfigurierte Webhook verwendet.

Signatur verifizieren

import crypto from "node:crypto";

// rawBody: die exakten empfangenen Bytes, vor 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: die exakten empfangenen Bytes, vor 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)

Berechne den HMAC immer über die rohen Bytes des Request-Bodys, nicht über ein neu serialisiertes Objekt – eine erneute Serialisierung kann Whitespace oder die Key-Reihenfolge verändern und damit die Signatur brechen. Verwende einen zeitkonstanten Vergleich.

Beispielanfrage

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 – liest die Variablendefinitionen des Assistenten; Scope assistants:read.
PATCH /api/v1/assistants/{id}/variables – ersetzt die Variablendefinitionen; Scope assistants:write.
MCP-Tools: get_assistant_variables, set_assistant_variables.

Die vollständige REST-Referenz findest du unter docs.famulor.io. Nutze {{key}} überall dort, wo du einen Wert pro Anruf brauchst, halte Schlüssel in snake_case und gib jeder Variable einen sinnvollen default_value, damit Anrufe sauber degradieren, wenn eine Quelle fehlt.

Erste Schritte

Assistenten

Flow-Builder

Telefonie

Kanäle

Audience

Kampagnen

Live-Betrieb

Workspace-Einstellungen

Abrechnung

Benutzerdefinierte Variablen

Referenzsyntax

Variablen für einen Assistenten definieren

Wo Variablen ersetzt werden

Wertquellen und Priorität

Explizite Werte über die API

Kampagnen-Leads → Variablen

Systemvariablen

Eingehender Variablen-Webhook

Anfrage

Antwort

Native Automation (Alternative)

Signatur verifizieren

Beispielanfrage

API & MCP

​Referenzsyntax

​Variablen für einen Assistenten definieren

​Wo Variablen ersetzt werden

​Wertquellen und Priorität

​Explizite Werte über die API

​Kampagnen-Leads → Variablen

​Systemvariablen

​Eingehender Variablen-Webhook

​Anfrage

​Antwort

​Native Automation (Alternative)

​Signatur verifizieren

​Beispielanfrage

​API & MCP

Referenzsyntax

Variablen für einen Assistenten definieren

Wo Variablen ersetzt werden

Wertquellen und Priorität

Explizite Werte über die API

Kampagnen-Leads → Variablen

Systemvariablen

Eingehender Variablen-Webhook

Anfrage

Antwort

Native Automation (Alternative)

Signatur verifizieren

Beispielanfrage

API & MCP