Variables por llamada

Personaliza un agente guardado para cada llamada sin cambiar su prompt, herramientas ni configuración implementados.

Coloca marcadores de posición en el prompt de tu agente guardado y luego proporciona un objeto variables al iniciar una llamada. La configuración guardada y el historial de versiones permanecen sin cambios. ThunderPhone procesa el texto antes de enviar la configuración de la llamada al entorno de ejecución de voz.

Cuando no se necesiten valores, omite variables; no envíes null (se rechaza con 400).

Marcadores de posición y valores predeterminados

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

Los nombres distinguen entre mayúsculas y minúsculas y siguen el patrón [A-Za-z_][A-Za-z0-9_]*. Se permiten espacios en blanco alrededor del nombre; los espacios en blanco después de | forman parte del valor predeterminado y se conservan. {{name|Friend}} usa Friend cuando falta name o es null; una cadena vacía es un valor proporcionado explícitamente. Los valores faltantes sin un valor predeterminado se convierten en cadenas vacías y sus nombres aparecen en unresolved_variables. Se elimina el texto entre llaves dobles que no sea un marcador de posición válido. El texto entre llaves dobles dentro de cada valor proporcionado se elimina de forma independiente; un valor no puede eliminar el texto circundante del prompt ni otro valor. También se eliminan los delimitadores de llaves dobles sin pareja. Los ejemplos de JSON en los prompts no deben usar {{. Los valores son texto sin formato y nunca se evalúan como código ni se expanden recursivamente como plantillas.

Las variables también pueden aparecer en los prompts de confirmación, los mensajes de buzón de voz salientes y el texto del anuncio de consentimiento cuando ese campo se envía para una llamada telefónica. El agente no tiene un campo first_message independiente: incluye sus instrucciones de apertura en el prompt. Los marcadores de posición existentes de buzón de voz {agent_name} y {org_name} siguen funcionando.

Los valores pueden ser cadenas, números, valores booleanos o null; los valores booleanos se representan como true y false. Se eliminan los caracteres de control Unicode (Cc), excepto salto de línea (\n), tabulación (\t) y retorno de carro (\r); todos los caracteres de formato (Cf) y los puntos de código sustitutos (Cs); \r\n se normaliza a \n. Cada valor está limitado a 2,000 caracteres al procesarse. Las cadenas proporcionadas también se limpian y truncan antes de almacenarse. El objeto original debe caber en 32 KB de JSON UTF-8; los objetos más grandes reciben 400 en las solicitudes de llamada/sesión, mientras que las importaciones de campañas informan las filas no válidas individualmente. No se aceptan arreglos ni objetos anidados como valores. Las claves de metadatos que no coincidan (por ejemplo, un encabezado de CSV con un espacio) se conservan y se devuelven, pero no pueden referenciarse mediante un marcador de posición.

De dónde provienen los valores

API de llamadas salientes

Envía variables junto con agent_id en POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

También funciona con el agente saliente predeterminado del número de teléfono o con un config.prompt en línea. No se puede reutilizar una clave de idempotencia con variables diferentes.

CSV de campañas

Las columnas de CSV que no son de teléfono ya se almacenan como variables de contacto. Cada marcación ahora las usa automáticamente. Usa encabezados como name, account_id y appointment_slot para que coincidan con tus marcadores de posición. La asignación de nombre existente puede combinar las columnas de nombre y apellido en la variable name.

Webhook de configuración dinámica

En la ruta bloqueante del webhook de configuración, devuelve un agente guardado en tu organización junto con los valores por llamada:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

Las claves de la respuesta sobrescriben las variables del nivel de solicitud, mientras que las demás claves de la solicitud se mantienen. Un valor de respuesta de null selecciona el valor predeterminado del marcador de posición. El objeto combinado también debe caber en 32 KB. Las respuestas de agentes guardados aceptan solo agent_id y variables; devuelve una configuración en línea cuando necesites reemplazar el prompt o la configuración. Una respuesta que contiene prompt siempre usa una configuración en línea: cualquier agent_id de esa respuesta se ignora, incluidos los metadatos nulos o que no sean enteros. El prompt en línea aún debe superar la validación normal. Las respuestas de webhook en línea también pueden incluir variables. Las respuestas de webhook de agentes guardados usan la división A/B implementada del agente tanto en llamadas telefónicas como de widget; las variables se procesan después de seleccionar la variante. En las llamadas telefónicas entrantes, usa un número sin agente entrante asignado y configura su webhook de número de teléfono o de organización; las claves de widget usan mode="webhook". Las notificaciones entrantes del sistema de endpoints no proporcionan respuestas de configuración bloqueantes.

POST /v1/widget/session acepta un objeto variables de nivel superior. Su clave publicable selecciona el agente guardado. Las claves en modo webhook reenvían estos valores al webhook de configuración y combinan la respuesta como se describió anteriormente. Las variables de widget/realtime proporcionadas por el navegador están controladas por el cliente, se reenvían sin cambios en web.incoming después de la validación y limpieza de cadenas descritas anteriormente, y se incluyen en los webhooks de finalización y el historial de llamadas. No las trates como datos confiables de identidad o autorización.

POST /v1/realtime/sessions acepta variables junto con agent_id (o config en línea). Estos son campos de la API de creación de sesiones. El puente WebSocket de Realtime no reenvía una opción de variables; proporciónala directamente a la API de creación de sesiones. Los clientes de Widget deben incluir variables en la carga útil de sesión enviada; el reenvío del SDK no forma parte de este cambio de API. Las llamadas de prueba con micrófono y simuladas del Builder resuelven valores predeterminados y marcadores de posición faltantes, pero no tienen entrada de variables por llamada.

Valores devueltos después de la llamada

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete y web.complete incluyen las variables y unresolved_variables combinadas finales. Las cargas útiles de finalización heredadas que incluyen data.history también las incluyen:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

Almacena tu identificador de CRM o de tarea en el objeto de variables para vincular la llamada completada con su registro de origen. Estos campos se conservan con el registro de llamada; envía solo información que sea apropiada conservar en el historial de llamadas y los webhooks.

Compatibilidad con prompts existentes

El renderizado también se aplica a los prompts existentes de agentes guardados y variantes A/B, configuraciones integradas de llamadas salientes y en tiempo real, y prompts devueltos por webhooks de configuración. Los marcadores de posición {{name}} desconocidos se convierten en texto en blanco, incluso cuando no se proporcionan variables. Revisa los prompts existentes antes del lanzamiento, incluidos los prompts integrados o de webhook proporcionados externamente que ThunderPhone no puede inventariar. Las llamadas de micrófono y simulación del Builder aplican el mismo comportamiento predeterminado/en blanco.