Skip to main content
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:
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. El texto desconocido con llaves simples no cambia; los marcadores desconocidos con llaves dobles quedan vacíos.

​
Definir variables en un asistente

Editor de variables personalizadas con clave, etiqueta, valor predeterminado, ejemplo y descripción

Settings del asistente → Advanced → Automations → Variables: define Key y Label y añade, si lo necesitas, un valor predeterminado, un ejemplo y una descripción.

Cada asistente tiene una lista de definiciones de variables. Una definición incluye:
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
  • URL de la solicitud, valores de encabezado y valores estáticos de parámetros de una herramienta API, sustituidos en el momento en que se ejecuta la herramienta
  • 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
Las herramientas API resuelven las variables en cada solicitud, incluidos los valores recopilados durante la conversación. Los parámetros estáticos numéricos y booleanos conservan sus marcadores hasta ese momento. Usa Variables de llamada en Solicitud de prueba para introducir valores de ejemplo. Los marcadores no resueltos de valores estáticos y encabezados quedan vacíos; los de la URL permanecen sin cambios. 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. Cuando Transfer to assistant traspasa la llamada a otro asistente, el prompt del sistema, el mensaje inicial, los textos del flow y los textos de las herramientas integradas de ese asistente se completan de la misma forma, con los valores actuales de la llamada, incluidos los recopilados hasta ese momento. {{assistant_name}} pasa a ser el nombre del asistente que recibe la llamada, y sus propios valores predeterminados completan cualquier variable para la que la llamada no tenga valor. Las claves ausentes pueden usar los valores predeterminados del asistente receptor; los valores borrados explícitamente permanecen vacíos. Las variables siguen disponibles aunque no se transfieran mensajes. Las acciones API que guardan datos externos deben asignar los valores devueltos a variables de la llamada para los asistentes siguientes. 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:
  1. Explícito: valores pasados con la llamada, por ejemplo mediante variables de la API make-call.
  2. Webhook de variables entrante: enriquecimiento obtenido al inicio de la llamada (ver más abajo).
  3. Valores actuales del contacto y del sistema: Custom Attributes seleccionados y valores completados por la plataforma a partir del contexto de esta llamada.
  4. Variable recordada de quien llama: el último valor consentido guardado en el ámbito compartido o privado configurado.
  5. Predeterminado: el default_value de la definición.
Un marcador con llaves dobles sin valor se convierte en una cadena vacía. El texto desconocido con llaves simples permanece sin cambios.

​
Valores explícitos mediante la API

Pasa las tareas de una sola llamada en variables, también para variables manuales. La misma clave en lead no concede acceso al campo del contacto. La solicitud no modifica el asistente ni el contacto; la conservación sigue la configuración de memoria de cada variable. Usa un objeto plano con claves snake_case en minúsculas (máximo 64 caracteres). Las cadenas admiten hasta 2000 caracteres; números y booleanos se convierten en texto. Se rechazan objetos anidados, arrays y valores null. Se eliminan caracteres de control, formato invisible y prefijos de rol. Tras iniciarse la llamada, usa MCP get_call con expected_variables, o POST /api/v1/calls/{id}/verify-inputs con { "expected_variables": { "auftrag": "Reservar una consulta" } }. La respuesta de solo lectura contiene únicamente las claves solicitadas: matched, missing, different o not_available. La ausencia de evidencia no significa éxito ni fallo; comprueba de nuevo después del inicio. Los valores coincidentes acreditan la entrega, no el éxito del escenario. Una llamada MCP en espera por falta de líneas conserva sus entradas. Las llamadas salientes también rellenan valores predeterminados propios de la llamada y campos de contacto seleccionados antes del enriquecimiento. Estos valores pueden tener prioridad sobre un webhook posterior. Un valor explícito para esta llamada tiene la máxima prioridad.

​
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:
Aquí company_name y appointment_date completan {{company_name}} y {{appointment_date}} solo después de que esos campos existan como Custom Attributes del workspace y se seleccionen para este asistente. Esa selección crea una definición con source: "lead"; los campos arbitrarios o eliminados no se exponen. El nombre del contacto es una identidad separada y está disponible mediante la variable del sistema integrada {{customer_name}}.

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

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

​
Respuesta

Devuelve las variables que quieres fusionar:
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

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

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