Open in
Variables y contexto por llamada
Proporciona a cada llamada sus propios detalles, como variables con nombre para el prompt o un resumen de formato libre, sin cambiar el agente.
Cada llamada puede incluir dos tipos de datos de entrada por llamada. Usa uno de ellos o ambos a la vez:
variables: valores con nombre que completan{{placeholders}}en el prompt. Úsalos para los campos a los que el prompt se refiere por nombre, como el nombre de quien llama, un número de cuenta o un horario de cita.context: texto de formato libre que se agrega después del prompt. Úsalo para un resumen que no encaja en una plantilla, como una descripción de la tarea para esta llamada o notas recopiladas anteriormente.
Ambos funcionan con un agente guardado y con una configuración en línea, en todas las formas de iniciar una llamada que se describen a continuación. Ninguno modifica el agente guardado, su historial de versiones ni sus demás configuraciones.
{
"agent_id": 12,
"variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
"context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}Variables
Coloca marcadores de posición en el prompt de tu agente guardado y luego proporciona un objeto variables
al iniciar una llamada. 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.
Valores y límites
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 nueva línea (\n), tabulación (\t)
y retorno de carro (\r); los caracteres de formato (Cf), excepto el separador y conector de ancho cero (U+200C, U+200D, que forman palabras en idiomas índicos y con escritura árabe); y los puntos de código sustitutos (Cs); \r\n
se normaliza como \n. Cada valor
está limitado a 2,000 caracteres al representarse. 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 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 coinciden (por ejemplo, un encabezado CSV con un
espacio) se conservan y se devuelven, pero no pueden referenciarse mediante un marcador de posición.
Contexto
context es una cadena de hasta 20,000 caracteres. ThunderPhone la agrega después
del prompt, una vez que se completan las variables del prompt, como un bloque delimitado:
<your prompt, with its variables filled in>
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>El agente lo lee junto con sus instrucciones, así que escríbelo como si
informaras a un colega antes de la llamada. El contexto no es una plantilla:
{{name}} dentro de él permanece tal como está escrito. Si el texto necesita un valor, agrega el valor
tú mismo antes de enviarlo.
null, una cadena vacía o solo espacios en blanco significa que no hay contexto.- Un valor que no es una cadena, o que supera los 20,000 caracteres, se rechaza con
400en solicitudes de llamadas y sesiones; desde un webhook de configuración, falla el intercambio comovariablesno válidas (consulta más abajo). - Se recortan los espacios en blanco iniciales y finales, y se eliminan los mismos caracteres de control y formato que en los valores de las variables.
- El contexto forma parte del prompt de la llamada, por lo que cuenta para el tamaño del prompt.
En un agente de pasos, el contexto sigue el prompt de cada agente en la llamada, no las instrucciones de cada paso.
De dónde provienen los valores
API de llamadas salientes
Envía variables y context en POST /v1/call:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"variables": {
"name": "Ada",
"account_id": "A-17",
"appointment_slot": "Tuesday at 10 AM"
},
"context": "Ada asked to be called back about the late fee on her March invoice."
}Ambos también funcionan con el agente saliente predeterminado del número de teléfono o con un config.prompt integrado. Con una configuración integrada, context también puede ir dentro de config, el mismo campo que devuelve un webhook de configuración; si envías ambos, deben tener el mismo texto. No puedes reutilizar una clave de idempotencia con variables diferentes o un contexto diferente.
CSV de campañas
Las columnas del 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. Los contactos de campaña no tienen contexto por contacto.
Webhook de configuración dinámica
En la ruta del webhook de configuración bloqueante, devuelve un agente guardado en tu organización junto con cualquier valor por llamada. Para un agente Full duplex, la llamada conserva la voz del agente incluso cuando comienza en otro idioma compatible: las asignaciones de voz por idioma y el cambio de voz nativo no se aplican en esa llamada.
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}Las variables de la respuesta sobrescriben las variables a nivel de solicitud, mientras que las demás claves de la solicitud se conservan. 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, variables, context, language y una
timezone por llamada; devuelve una configuración en línea cuando necesites
reemplazar el prompt u otras opciones. 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. Cuando la respuesta establece language para un
agente que no es Full duplex, la llamada también usa la voz propia de ese idioma si el
agente tiene una configurada para él. Una respuesta que contiene prompt siempre usa
configuración en línea: se ignora cualquier agent_id en esa respuesta, incluidos los metadatos nulos o
no enteros. El prompt en línea aún debe pasar la validación normal.
Las respuestas de webhook en línea también pueden incluir variables y context. Un context
que no sea una cadena o que sea demasiado largo hace que falle el intercambio: se
rechaza una llamada telefónica y una solicitud de sesión de widget falla con 400. 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 un
agente entrante asignado y configura su webhook de número telefónico 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.
Webhook de configuración de llamadas del agente
Para mantener un número asignado a su agente y completar solo los valores de la llamada, proporciona al agente un webhook de configuración de llamada.
Antes de cada llamada entrante que el agente atiende en un número, el webhook recibe la llamada y el ID, nombre y versión del agente, y responde con las mismas
variables, context, language y timezone por llamada indicadas anteriormente, sin necesidad de un agent_id. Un agente
cuya configuración use un marcador de posición sin valor predeterminado necesita este webhook para atender un número de teléfono: la llamada no se inicia cuando el webhook falla. Los marcadores de posición con un valor predeterminado, como {{name|there}}, permiten que el agente atienda sin él.
Encabezados SIP
Las llamadas que llegan a un agente mediante SIP (una dirección SIP o
un número en una conexión SIP manual) pueden incluir contexto en los encabezados X-* y
User-to-User. Cada uno se convierte en una variable sip_, como
{{sip_x_amzn_connectcontactid}} o {{sip_uui}}, con la prioridad más baja:
prevalece un valor con el mismo nombre de la API o un webhook. Consulta
Pasar contexto de llamada en encabezados SIP.
Los valores de los encabezados los establece el remitente, así que trátalos como no confiables,
igual que cualquier valor proporcionado por el navegador.
API de sesión del widget
POST /v1/widget/session acepta variables y language 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 del widget proporcionadas por el navegador son controladas por el cliente, se reenvían literalmente en web.incoming después de la validación y limpieza de cadenas descritas anteriormente, y se reflejan en los webhooks de finalización y el historial de llamadas. No las trates como datos confiables de identidad o autorización.
El campo context del navegador del propio widget es diferente: transporta texto de la
página en la que se encuentra el visitante, que el agente trata como contenido del sitio web (consulta
Incrustar el widget web). El contexto por llamada de una llamada del widget
proviene del webhook de configuración de una clave en modo webhook, como se indicó anteriormente. Cuando una
llamada tiene ambos, el contexto por llamada aparece primero y luego el contenido de la página.
API de sesión en tiempo real
POST /v1/realtime/sessions acepta variables, context y language de nivel superior junto con agent_id o una config integrada:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context solo se incluye en el nivel superior; una config en línea lo rechaza como un
campo desconocido.
WebSocket en tiempo real
Con un agente guardado, el prompt implementado del agente guardado sigue siendo su prompt.
session.instructions se convierte en el contexto de la llamada, session.prompt.variables
(o session.config.variables) se convierten en sus variables y session.language
se convierte en su idioma por llamada. Selecciona el agente con
session.prompt.id en el primer session.update, que inicia la sesión cuando
llega esa actualización:
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {"id": "12", "variables": {"name": "Ada"}},
"instructions": "Ada asked for a callback about her delivery window."
}
}?agent_id=12 en la URL de conexión inicia el agente en cuanto se conecta el socket,
antes de cualquier session.update, por lo que no incluye datos de entrada por llamada. Agrega
&wait_for_session_update=1 para esperar el primer session.update y usar sus
instrucciones y variables.
En una sesión en línea (sin un agente guardado), session.instructions es el propio prompt, como antes. Las llamadas de prueba en el navegador y las simulaciones resuelven los valores predeterminados y los marcadores de posición faltantes. Para realizar pruebas con valores, guarda un
ejemplo de configuración de llamada en el
agente y selecciónalo cuando inicies la prueba; la llamada se ejecuta como si tu webhook de
configuración de llamada hubiera respondido con él.
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"]
}El prompt_snapshot de la llamada (GET /v1/calls/{call_id}) muestra el
prompt del agente con sus variables completadas y el bloque de contexto agregado.
Almacena tu identificador de CRM o tarea en el objeto de variables para vincular la llamada completada con su registro de origen. Las variables y el contexto se conservan con el registro de la llamada; envía solo información que sea apropiado conservar en el historial de llamadas y los webhooks.
Las repeticiones de una llamada, en conjuntos de validación, ejecuciones de repetición e investigaciones, usan las variables y el contexto de esa llamada con el prompt en prueba, por lo que una repetición prueba lo que se le habría indicado al agente en esa llamada.
Compatibilidad con prompts existentes
La representación también se aplica a los prompts existentes de agentes guardados y variantes A/B, las configuraciones integradas de llamadas salientes y en tiempo real, y los prompts devueltos por webhooks de configuración. Los marcadores de posición desconocidos {{name}} 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 prueba y simulaciones en el navegador aplican el mismo comportamiento predeterminado o en blanco, a menos que elijas una muestra de configuración de llamada guardada.