Teste suas jornadas com a API Simulation

Santiago Cardona Atualizado por Santiago Cardona

A API Simulation permite que você execute suas jornadas de maneira programática, sem enviar mensagens reais do WhatsApp. Pense nisso como uma conversa com sua jornada através do código.

Isso é especialmente útil se você estiver criando agentes de IA, pipelines de testes automatizados ou qualquer sistema externo que precise interagir com sua lógica de jornada.

Esta API está em desenvolvimento ativo. Breaking changes are expected before August 2026, so backward compatibility is not guaranteed until then.

Before you start

You’ll need two things:

  1. A Turn.io API token. You can generate one from the Turn.io dashboard under Settings → API & Webhooks. Esse token autentica todas as suas solicitações de API.
  2. Uma jornada publicada. A jornada que você deseja simular deve ter uma revisão de produção (ou preparação) publicada. Você usará o UUID da jornada, que pode ser encontrado no URL ao visualizar a jornada na tela.

Como funciona

A API Simulation usa um único endpoint para tudo:

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

Este endpoint lida com o inicialização de uma simulação e o envio de respostas a ela. A API sabe o que fazer com base na existência de uma sessão para seu simulation_id:

  • Primeira solicitação com um novo simulation_id: Cria uma nova simulação e inicia a jornada.
  • Solicitações subsequentes com o mesmo simulation_id: Envia entrada para o sessão em execução.

O simulation_id é um identificador que você cria. Pode ser qualquer string entre 6 e 32 caracteres — por exemplo, test-run-001 ou agent-session-42. The API uses the combination of your journey UUID and simulation_id to track each session.

Starting a simulation

To kick off a simulation, send a POST request with a simulation_id:

curl -X POST "https://whatsapp.turn.io/v1/journeys/<journey-uuid>/simulation" \
 -H "Autorização: Portador <seu-token>" \
 -H "Tipo de conteúdo: aplicativo/json" \
 -d '{
 "simulation_id": "my-session-001"
 }'

A API responde com a primeira saída da jornada:

{
 "state": "waiting_for_input",
 "mensagem": "Bem-vindo! Qual é o seu nome?",
 "contexto": {
 "contato": {
 "nome": "John",
 "idioma": "eng"
 }
 }
}
Parâmetros opcionais

Você pode personalizar a simulação ao iniciá-la:

Parâmetro

Padrão

Descrição

revisão

"produção"

Qual versão da jornada simular. Use "staging" para testar alterações não publicadas.

contact

{}

Atributos de contato a serem usados ​​durante a simulação. Substitui os padrões (por exemplo, nome, idioma).

input

—

Uma mensagem inicial a ser enviada quando a jornada começar, se o primeiro cartão esperar entrada.

Por exemplo, para simular with a specific contact name and language:

curl -X POST "https://whatsapp.turn.io/v1/journeys/<journey-uuid>/simulation" \
 -H "Autorização: Portador <seu-token>" \
 -H "Tipo de conteúdo: aplicativo/json" \
 -d '{
 "revisão": "produção",
 "contato": {
 "nome": "Maria",
 "idioma": "por"
 }
 }'

Enviando respostas

Quando a jornada estiver aguardando entrada (o estado da resposta é "waiting_for_input"), envie a resposta do usuário com o mesmo simulation_id:

curl -X POST "https://whatsapp.turn.io/v1/journeys/<journey-uuid>/simulation" \
 -H "Autorização: Portador <seu-token>" \
 -H "Tipo de conteúdo: aplicativo/json" \
 -d '{
 "simulation_id": "my-session-001",
 "input": "Maria"
 }'

Resposta:

{
 "estado": "fim",
 "mensagem": "Obrigado Maria! Seu registro foi concluído."
}

Quando estado for "fim", a jornada terminou. Não há mais entradas para enviar.

Um exemplo completo de conversa

Vamos percorrer uma simulação completa de várias voltas. Imagine uma jornada que ajuda os usuários a agendar compromissos.

Etapa 1 — Comece a jornada:

curl -X POST "https://whatsapp.turn.io/v1/journeys/d144cb30-f759-4260-82ba-07353f0e389f/simulation" \
 -H "Autorização: Portador <seu-token>" \
 -H "Tipo de conteúdo: aplicativo/json" \
 -d '{
 "simulation_id": "booking-test-01",
 "contato": { "nome": "Maria" }
 }'
{
 "estado": "esperando_por_input",
 "mensagem": "Olá Maria! Como podemos ajudá-lo hoje?\n\nResponda exclusivamente com uma das seguintes opções:\nAgendar consulta, Verificar status, Falar com agente",
 "contexto": {
 "contato": { "nome": "Maria", "idioma": "eng" }
 }
}

Observe como as opções dos botões aparecem como texto na mensagem. Para selecionar uma, responda com o texto exato da opção.

Etapa 2 — Escolha uma opção:

curl -X POST "https://whatsapp.turn.io/v1/journeys/d144cb30-f759-4260-82ba-07353f0e389f/simulation" \
 -H "Autorização: Portador <seu-token>" \
 -H "Tipo de conteúdo: aplicativo/json" \
 -d '{
 "simulation_id": "booking-test-01",
 "input": "Agendar compromisso"
 }'
{
 "estado": "waiting_for_input",
 "mensagem": "Ótimo! Qual data funciona para você?"
}

Etapa 3 — Conclua a jornada:

curl -X POST "https://whatsapp.turn.io/v1/journeys/d144cb30-f759-4260-82ba-07353f0e389f/simulation" \
 -H "Autorização: Portador <seu-token>" \
 -H "Tipo de conteúdo: aplicativo/json" \
 -d '{
 "simulation_id": "booking-test-01",
 "entrada": "Próxima segunda-feira"
 }'
{
 "estado": "fim",
 "mensagem": "Seu compromisso está marcado para a próxima segunda-feira. See you then!"
}

Understanding the response

Every response from the Simulation API includes these fields:

Field

Description

state

Ou "waiting_for_input" (a jornada espera uma resposta) ou "end" (a jornada terminou).

message

A saída de texto da jornada. This is what would normally be sent as a WhatsApp message.

context

The current variable context, including contact fields and any variables set by the journey. Presente apenas ao iniciar uma simulação.

Como o conteúdo da jornada aparece nas respostas

Como as simulações não enviam mensagens reais do WhatsApp, certos tipos de conteúdo são representados como texto:

  • Botões e listas: As opções são anexadas à mensagem, por exemplo: "Responder exclusivamente com uma das seguintes opções: Opção1, Opção2". Responda com o texto exato da opção.
  • Mídia (imagens, vídeos, documentos, áudio): retornada como texto descritivo com um URL temporário, por exemplo: "Imagem disponível em: https://...".

Coisas para manter em mente

  • As sessões expiram após inactivity. If you don’t send a request for a few minutes, the session will time out. Comece uma nova com um novo simulation_id se isso acontecer.
  • Nenhuma mensagem real é enviada. A jornada é executada inteiramente na memória. Sem mensagens do WhatsApp, sem registros de contato, sem efeitos colaterais.
  • Os agentes de IA também funcionam. Se sua jornada incluir blocos de agentes de IA com memória ativada, a IA se lembrará de mensagens anteriores na mesma sessão de simulação, assim como faria em uma conversa real.
  • Use valores simulation_id exclusivos para sessões paralelas. Cada simulation_id exclusivo cria uma sessão independente, portanto you can run multiple simulations of the same journey at the same time.
  • Test staging changes before publishing. Set revision to "staging" to simulate the latest draft of your journey without publishing it first.

Error reference

If something goes wrong, the API returns a JSON object with an Campo erro:

Status

Erro

O que significa

400

simulation_id é obrigatório

Você não incluiu um simulation_id no corpo da solicitação.

400

simulation_id deve ter entre 6 e 32 caracteres

Seu simulation_id também é curto ou muito longo.

400

UUID de viagem inválido

O UUID de viagem no URL não é um formato UUID válido.

400

A jornada não tem revisão de produção publicada

A jornada ainda não foi publicada. Publique-o primeiro ou use "staging".

400

A jornada não tem revisão de teste

Não há revisão de teste disponível para esta jornada.

400

A jornada está desativada

A jornada está atualmente desativada no Turn.io.

400

A jornada foi excluída

A journey has been deleted.

400

Invalid revision, must be 'production' or 'staging'

The revision value isn’t valid. Use "production" ou "staging".

400

Entrada inválida, deve ser uma string não vazia

O campo input está vazio ou ausente quando respondendo a uma sessão.

404

Viagem não encontrada

Não existe jornada com esse UUID para o seu número.

404

Simulação não found or expired

The session has expired or doesn’t exist. Start a new one.

Esse artigo foi útil?

Como baixar e duplicar jornadas no formato markdown

Contato