---
title: "Variables y contexto por llamada"
description: "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.

```json
{
  "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

```text
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:

```text
<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 `400` en solicitudes de llamadas y sesiones; desde un webhook de configuración, falla el intercambio como `variables` no 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](/es/guides/pricing).

En un agente de [pasos](/es/guides/agent-steps), 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`:

```json
{
  "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.

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
```

```json
{
  "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`](/es/guides/dynamic-call-config) 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](/es/webhooks/call-incoming).
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](/es/guides/sip-addresses) 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](/es/guides/sip-addresses).
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](/es/guides/embed-web-widget)). 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:

```json
{
  "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:

```json
{
  "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](/es/webhooks/call-incoming) 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:

```json
{
  "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](/api-reference/validation-sets),
[ejecuciones de repetición](/api-reference/replay-runs) e
[investigaciones](/api-reference/investigations), 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.
