ThunderPhone v3 ya está disponible.Empieza por tu cuenta desde 2¢/min.Lee el anuncio

Developer cookbook

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

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.