Pruebe sus viajes con la API de simulación

Santiago Cardona Actualizado por Santiago Cardona

La API de simulación te permite ejecutar tus viajes de forma programática, sin enviar mensajes reales de WhatsApp. Piense en ello como si tuviera una conversación con su recorrido a través del código.

Esto es especialmente útil si está creando agentes de IA, canales de pruebas automatizados o cualquier sistema externo que necesite interactuar con la lógica de su recorrido.

Esta API está en desarrollo activo. Se esperan cambios importantes antes de agosto de 2026, por lo que la compatibilidad con versiones anteriores no está garantizada hasta entonces.

Antes de comenzar

Necesitará dos cosas:

  1. Un token de API de Turn.io. Puede generar uno desde el panel de Turn.io en Configuración → API y aplicaciones. Ganchos web. Este token autentica todas sus solicitudes de API.
  2. Un recorrido publicado. El recorrido que desea simular debe tener una revisión de producción (o prueba) publicada. Utilizará el UUID del recorrido, que puede encontrar en la URL al visualizar el recorrido en el lienzo.

Cómo funciona

La API de simulación utiliza un único punto final para todo:

POST https://whatsapp.turn.io/v1/journeys/<journey-uuid>/simulation

Este punto final se encarga tanto de iniciar una simulación como de enviarle respuestas. La API sabe qué hacer en función de si ya existe una sesión para su simulation_id:

  • Primera solicitud con un nuevo simulation_id: Crea una nueva simulación e inicia el viaje.
  • Solicitudes posteriores con el mismo simulation_id: Envía información a la sesión en ejecución.

El simulation_id es un identificador que usted crea. Puede ser cualquier cadena de entre 6 y 32 caracteres, por ejemplo, test-run-001 o agent-session-42. La API utiliza la combinación de su UUID de viaje y simulation_id para realizar un seguimiento de cada sesión.

Iniciar una simulación

Para iniciar una simulación, envíe una solicitud POST con un simulation_id:

curl -X POST "https://whatsapp.turn.io/v1/journeys/<journey-uuid>/simulación" \
 -H "Autorización: Portador <su-token>" \
 -H "Tipo de contenido: aplicación/json" \
 -d '{
 "simulation_id": "my-session-001"
 }'

La API responde con el primer resultado del recorrido:

{
 "state": "esperando_entrada",
 "mensaje": "¡Bienvenido! ¿Cuál es tu nombre?",
 "contexto": {
 "contacto": {
 "nombre": "John",
 "idioma": "eng"
 }
 }
}
Parámetros opcionales

Puedes personalizar la simulación al iniciarla:

Parámetro

Predeterminado

Descripción

revisión

"producción"

Qué versión del viaje simular. Utilice "staging" para probar los cambios no publicados.

contact

{}

Atributos de contacto que se usarán durante la simulación. Anula los valores predeterminados (por ejemplo, nombre, idioma).

entrada

—

Un mensaje inicial para enviar cuando comienza el viaje, si la primera tarjeta espera una entrada.

Por ejemplo, para simular con un nombre de contacto e idioma específicos:

curl -X POST "https://whatsapp.turn.io/v1/journeys/<journey-uuid>/simulation" \
 -H "Autorización: Portador <su-token>" \
 -H "Tipo de contenido: aplicación/json" \
 -d '{
 "revisión": "producción",
 "contacto": {
 "nombre": "María",
 "idioma": "por"
 }
 }'

Enviando respuestas

Cuando el recorrido está esperando entrada (la respuesta state es "waiting_for_input"), envía la respuesta del usuario con el mismo simulation_id:

curl -X POST "https://whatsapp.turn.io/v1/journeys/<journey-uuid>/simulación" \
 -H "Autorización: Portador <su-token>" \
 -H "Tipo de contenido: aplicación/json" \
 -d '{
 "simulación_id": "mi-sesión-001",
 "entrada": "Maria"
 }'

Respuesta:

{
 "estado": "fin",
 "mensaje": "¡Gracias María! Su registro está completo."
}

Cuando state es "end", el viaje ha terminado. No hay más datos que enviar.

Un ejemplo de conversación completa

Veamos una simulación completa de varios turnos. Imagine un recorrido que ayude a los usuarios a reservar citas.

Paso 1: comience el recorrido:

curl -X POST "https://whatsapp.turn.io/v1/journeys/d144cb30-f759-4260-82ba-07353f0e389f/simulation" \
 -H "Autorización: Portador <su-token>" \
 -H "Tipo de contenido: aplicación/json" \
 -d '{
 "simulación_id": "booking-test-01",
 "contacto": { "nombre": "Maria" }
 }'
{
 "estado": "esperando_entrada",
 "mensaje": "¡Hola María! ¿Cómo podemos ayudarle hoy?\n\nResponda exclusivamente con una de las siguientes opciones:\nReservar cita, Verificar estado, Hablar con el agente",
 "context": {
 "contacto": { "nombre": "Maria", "idioma": "ing" }
 }
}

Observe cómo las opciones de los botones aparecen como texto en el mensaje. Para seleccionar una, responde con el texto de opción exacto.

Paso 2: elige una opción:

curl -X POST "https://whatsapp.turn.io/v1/journeys/d144cb30-f759-4260-82ba-07353f0e389f/simulation" \
 -H "Autorización: Portador <su-token>" \
 -H "Tipo de contenido: aplicación/json" \
 -d '{
 "simulación_id": "booking-test-01",
 "entrada": "Reservar cita"
 }'
{
 "estado": "esperando_entrada",
 "mensaje": "¡Genial! ¿Qué fecha te conviene?"
}

Paso 3: completa el viaje:

curl -X POST "https://whatsapp.turn.io/v1/journeys/d144cb30-f759-4260-82ba-07353f0e389f/simulation" \
 -H "Autorización: Portador <su-token>" \
 -H "Tipo de contenido: aplicación/json" \
 -d '{
 "simulación_id": "booking-test-01",
 "entrada": "El próximo lunes"
 }'
{
 "estado": "fin",
 "mensaje": "Tu cita está reservada para el próximo lunes. ¡Hasta entonces!"
}

Comprensión de la respuesta

Cada respuesta de la API de simulación incluye estos campos:

Campo

Descripción

estado

O "waiting_for_input" (el viaje espera una respuesta) o "end" (el viaje ha terminado).

mensaje

El texto resultante del viaje. Esto es lo que normalmente se enviaría como un mensaje de WhatsApp.

context

El contexto variable actual, incluidos los campos de contacto y cualquier variable establecida por el viaje. Solo está presente al iniciar una simulación.

Cómo aparece el contenido del viaje en las respuestas

Dado que las simulaciones no envían mensajes reales de WhatsApp, ciertos tipos de contenido se representan como texto:

  • Botones y listas: Las opciones se agregan al mensaje, por ejemplo: "Responder exclusivamente con una de las siguientes opciones: Opción1, Opción2". Responda con la opción de texto exacta.
  • Medios (imágenes, vídeos, documentos, audio): Devueltos como texto descriptivo con una URL temporal, por ejemplo: "Imagen disponible en: https://...".

Cosas a tener en cuenta

  • Las sesiones caducan después inactividad. Si no envía una solicitud durante unos minutos, la sesión finalizará. Inicie uno nuevo con un simulation_id nuevo si eso sucede.
  • No se envían mensajes reales. El viaje se ejecuta completamente en memoria. Sin mensajes de WhatsApp, sin registros de contactos, sin efectos secundarios.
  • Los agentes de IA también funcionan. Si su viaje incluye bloques de agentes de IA con memoria habilitada, la IA recordará los mensajes anteriores en la misma sesión de simulación, tal como lo haría en una conversación real.
  • Utilice valores únicos simulation_id para sesiones paralelas. Cada simulation_id exclusivo crea una sesión independiente. para que pueda ejecutar múltiples simulaciones del mismo viaje al mismo tiempo.
  • Pruebe los cambios de preparación antes de publicarlos. Establezca revision en "staging" para simular el último borrador de su viaje sin publicarlo primero.

Referencia de error

Si algo sale mal, la API devuelve un objeto JSON con un Campo error:

Estado

Error

Qué significa

400

simulation_id es requerido

No incluiste un simulation_id en el cuerpo de la solicitud.

400

simulation_id debe tener entre 6 y 32 caracteres

Tu simulation_id es demasiado corto o demasiado largo.

400

UUID de viaje no válido

El UUID de viaje en la URL no es un formato de UUID válido.

400

El viaje no tiene una revisión de producción publicada

El viaje aún no se ha publicado. Publíquelo primero o use "staging".

400

El viaje no tiene revisión de preparación

No hay ninguna revisión de preparación disponible para este viaje.

400

El viaje está deshabilitado

El viaje está actualmente deshabilitado en Turn.io.

400

El viaje ha sido eliminado

El el viaje ha sido eliminado.

400

Revisión no válida, debe ser 'producción' o 'puesta en escena'

El valor de revisión no es válido. Utilice "production" o "staging".

400

Entrada no válida, debe ser una cadena que no esté vacía

El campo input está vacío o falta cuando respondiendo a una sesión.

404

Viaje no encontrado

No existe ningún viaje con ese UUID para su número.

404

Simulación no encontrada o caducada

La sesión ha caducado o no existe. Inicie uno nuevo.

¿Cómo lo hicimos?

Cómo migrar viajes entre cuentas

Contacto