Variables personalizadas

Las variables personalizadas te permiten escribir un asistente una sola vez y personalizar cada llamada. En lugar de codificar un nombre, una cita o un número de cuenta directamente en el prompt del sistema, haces referencia a un marcador como {{customer_name}} y le das el valor en cada llamada: desde tu solicitud a la API, un lead de campaña, un webhook de enriquecimiento entrante o el contexto del sistema integrado en la plataforma.

Sintaxis de referencia de variables

Haz referencia a una variable con llaves dobles, la forma preferida y segura para JSON:

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

La forma antigua de llave simple {customer_name} también se resuelve, pero solo para claves que realmente existen (una variable definida o del sistema). Así se mantienen intactas las llaves literales, por ejemplo el JSON dentro del cuerpo de una herramienta. Cualquier marcador cuya clave sea desconocida se deja tal cual.

Definir variables en un asistente

Cada asistente tiene una lista de definiciones de variables. Una definición incluye:

Campo	Obligatorio	Descripción
`key`	Sí	El identificador que se usa como `{{key}}`. Debe empezar con una letra minúscula, seguida de letras minúsculas, dígitos y guiones bajos; de 1 a 64 caracteres (`^[a-z][a-z0-9_]{0,63}$`). Único por asistente. No puede ser una variable de sistema reservada.
`label`	Sí	Nombre legible para humanos que se muestra en el editor.
`description`	No	Nota sobre para qué sirve la variable.
`default_value`	No	Valor de respaldo que se usa cuando no se proporciona ningún valor al momento de la llamada.
`example`	No	Valor de ejemplo (solo para el editor/documentación, nunca se envía).
`source`	No	Pista informativa: `manual` (predeterminado), `lead`, `webhook` o `system`. Determina las sugerencias de la interfaz y el mapeo del webhook; no restringe de dónde puede venir un valor.

Las claves se validan al guardar: se rechazan un formato inválido, una colisión con una variable de sistema reservada, una clave duplicada o una etiqueta faltante.

Dónde se sustituyen las variables

Los valores se sustituyen al inicio de la llamada, antes de que se ejecute el modelo o el Flow, en estos campos:

System prompt del asistente
First message del asistente (saludo)
Nodo start.greeting del Flow
Nodo agent.instructions del Flow
URL de la solicitud y valores de encabezado del nodo de herramienta del Flow
number de destino y announcement del nodo de transferencia del Flow
number de destino, caller announcement y briefing instructions del nodo de transferencia cálida del Flow
Built-in tool texts — description de la herramienta, announcement de la transferencia, hold message, connected message, briefing first message y summary instructions de la transferencia cálida, farewell al terminar la llamada, pre-transfer message de la transferencia a otro asistente y prompt de la captura de la tarjeta de pago

Así, un nodo de transferencia puede dirigir cada llamada a un número propio del lead, como {{handover_number}}, aportado mediante los campos personalizados del lead de campaña, el variables de la API, o el webhook de variables entrante — y un briefing de transferencia cálida puede empezar con Hallo, hier {{assistant_name}} von {{company}} — Anrufer {{caller_name}}. Consulta la referencia de nodos de Flow para ver qué controla cada campo del Flow. Los textos hablados de las herramientas se sustituyen dos veces: una al inicio de la llamada con las variables de entrada resueltas, y otra en el momento en que la herramienta se ejecuta — así se incluyen también los valores recopilados durante la conversación (mediante set_variable o pasos de tipo Collect), que tienen prioridad. Así, un nodo de herramienta puede llamar a https://api.example.com/orders/{{order_id}} o enviar Authorization: Bearer {{api_token}} con valores propios de cada llamada.

Origen de los valores y prioridad

Un valor puede llegar desde varios lugares. Al inicio de la llamada, la plataforma usa este orden de prioridad, de mayor a menor:

Explícito: valores pasados con la llamada, ya sea el variables de la API make-call o los campos personalizados de un lead de campaña mapeados a claves coincidentes.
Webhook de variables entrante: enriquecimiento obtenido al inicio de la llamada (ver más abajo).
Variables de sistema: completadas por la plataforma a partir del contexto de la llamada.
Predeterminado: el default_value de la definición.

Un marcador sin valor en ningún nivel se deja tal cual.

Valores explícitos mediante la 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 campaña → variables

En una campaña, cada lead puede incluir campos personalizados de formato libre. Al marcar, un campo se mapea a una variable con la misma clave. Así, una columna del CSV se convierte en una variable:

phone_number,name,customer_name,appointment_date
+493012345678,Jordan,Jordan,2026-07-10
+491701234567,Alex,Alex,2026-07-11

Aquí las columnas customer_name y appointment_date completan {{customer_name}} y {{appointment_date}} en cada llamada. Asigna source: "lead" a una variable proveniente de un lead para documentar su origen.

Variables de sistema

Estas claves siempre están disponibles al inicio de la llamada. Están reservadas: no puedes definir una variable personalizada con ninguna de estas claves.

Clave	Etiqueta	Descripción	Ejemplo
`caller_number`	Número de quien llama	El número de teléfono desde el que llega la llamada (entrante) o al que se realiza (saliente), en formato E.164.	`+493012345678`
`called_number`	Número llamado	El número que se marcó o el número tuyo que recibió la llamada, en formato E.164.	`+498998765432`
`assistant_name`	Nombre del asistente	El nombre del asistente que gestiona la llamada.	`Reception Bot`
`direction`	Dirección de la llamada	`inbound`, `outbound` o `web`.	`inbound`
`call_id`	ID de llamada	Identificador único de esta llamada.	`c_a1b2c3`
`date`	Fecha	Fecha actual al inicio de la llamada (zona horaria del asistente), `YYYY-MM-DD`.	`2026-07-05`
`time`	Hora	Hora actual al inicio de la llamada (zona horaria del asistente), `HH:MM`.	`14:30`
`datetime`	Fecha y hora	Fecha y hora actuales al inicio de la llamada (ISO 8601).	`2026-07-05T14:30:00Z`
`weekday`	Día de la semana	Día de la semana actual al inicio de la llamada.	`Sunday`

Webhook de variables entrante

En las llamadas entrantes muchas veces no conoces de antemano a quien llama. Configura un webhook de variables en el asistente. Famulor lo llama al inicio para enriquecer las variables, por ejemplo, a partir del número de quien llama. Esto se dispara antes de que empiece la llamada; consulta Webhooks posteriores a la llamada para ver qué envía Famulor cuando esta termina.

Solicitud

Famulor envía un POST con un cuerpo JSON:

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

El cuerpo de la solicitud, sin procesar, se firma con HMAC-SHA256 usando el secreto de webhook configurado. La firma se envía en este encabezado:

X-Famulor-Signature: sha256=<hexdigest>

Respuesta

Devuelve las variables que quieres fusionar:

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

Estos valores sustituyen a las variables del sistema y a los valores predeterminados, pero los valores enviados explícitamente para la llamada tienen prioridad. Si la consulta falla, la llamada continúa con los valores disponibles.

Automatización nativa (alternativa)

En lugar de un webhook propio, puedes crear una Automation con el disparador Inject input variables y vincularla al asistente. Añade una acción Return variables con la misma estructura { variables: {…} }. Si no existe una automatización activa que coincida, se usa el webhook configurado.

Verificar la firma

import crypto from "node:crypto";

// rawBody: los bytes exactos recibidos, antes de 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: los bytes exactos recibidos, antes de 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)

Calcula siempre el HMAC sobre los bytes sin procesar del cuerpo de la solicitud, no sobre un objeto reserializado: la reserialización puede cambiar los espacios en blanco o el orden de las claves y romper la firma. Usa una comparación de tiempo constante.

Solicitud de ejemplo

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

GET /api/v1/assistants/{id}/variables: lee las definiciones de variables del asistente; alcance assistants:read.
PATCH /api/v1/assistants/{id}/variables: reemplaza las definiciones de variables; alcance assistants:write.
Herramientas MCP: get_assistant_variables, set_assistant_variables.

La referencia completa de la REST API está en docs.famulor.io. Usa {{key}} en cualquier lugar donde necesites un valor propio de cada llamada, mantén las claves en snake_case y dale a cada variable un default_value razonable para que las llamadas se degraden con elegancia cuando falte una fuente.

Primeros pasos

Asistentes

Constructor de flujos

Telefonía

Canales

Audience

Campañas

Operaciones

Ajustes del workspace

Variables personalizadas

Sintaxis de referencia de variables

Definir variables en un asistente

Dónde se sustituyen las variables

Origen de los valores y prioridad

Valores explícitos mediante la API

Leads de campaña → variables

Variables de sistema

Webhook de variables entrante

Solicitud

Respuesta

Automatización nativa (alternativa)

Verificar la firma

Solicitud de ejemplo

API y MCP

​Sintaxis de referencia de variables

​Definir variables en un asistente

​Dónde se sustituyen las variables

​Origen de los valores y prioridad

​Valores explícitos mediante la API

​Leads de campaña → variables

​Variables de sistema

​Webhook de variables entrante

​Solicitud

​Respuesta

​Automatización nativa (alternativa)

​Verificar la firma

​Solicitud de ejemplo

​API y MCP

Sintaxis de referencia de variables

Definir variables en un asistente

Dónde se sustituyen las variables

Origen de los valores y prioridad

Valores explícitos mediante la API

Leads de campaña → variables

Variables de sistema

Webhook de variables entrante

Solicitud

Respuesta

Automatización nativa (alternativa)

Verificar la firma

Solicitud de ejemplo

API y MCP