API de Simulação de Jornadas

A API de Simulação de Jornadas permite que sistemas externos (como agentes de IA) interajam com jornadas de forma conversacional sem enviar mensagens reais pelo WhatsApp. Isso é útil para testes, pré-visualizações e integração da lógica de jornadas em fluxos de trabalho externos.

atenção

Esta API está em desenvolvimento ativo e mudanças incompatíveis são esperadas nos próximos meses. A compatibilidade com versões anteriores não é garantida até pelo menos agosto de 2026.

A autenticação ocorre como em outras chamadas de API, com um token da Turn.io especificado no header HTTP Authorization, prefixado por Bearer e seguido de um token emitido pela interface do usuário da Turn.io.

Como funciona

O endpoint de simulação utiliza uma única rota POST que gerencia tanto a criação de novas simulações quanto o envio de entradas para simulações existentes:

Se não existir uma simulação para o simulation_id fornecido: uma nova sessão de simulação é criada e a jornada começa a ser executada.
Se já existir uma simulação para o simulation_id fornecido: a entrada (input) fornecida é enviada para a sessão existente.

O simulation_id é sempre obrigatório e fornecido pelo chamador. Pode ser qualquer identificador de string entre 6 e 24 caracteres. O endpoint usa a combinação do UUID da jornada (da URL) e do simulation_id (do corpo da requisição) para identificar sessões de simulação.

Iniciando uma simulação

Para iniciar uma nova simulação, faça a seguinte requisição:

$ curl -X POST "https://whatsapp.turn.io/v1/stacks/<uuid-da-jornada>/simulation" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "simulation_id": "minha-sessao-001",
        "revision": "production",
        "contact": {
            "name": "Usuário Teste",
            "language": "eng"
        }
    }'

> {
    "simulation_id": "minha-sessao-001",
    "state": "waiting_for_input",
    "message": "Bem-vindo! Qual é o seu nome?",
    "context": {
        "contact": {
            "name": "Usuário Teste",
            "language": "eng"
        }
    }
}

Parâmetros

Nome	Obrigatório	Padrão	Descrição
simulation_id	sim		Um identificador de string fornecido pelo chamador (6 a 24 caracteres) para rastrear a sessão.
revision	não	`"production"`	Qual revisão da jornada simular. Deve ser `"production"` ou `"staging"`.
contact	não	`{}`	Um objeto com atributos de contato para preencher o contexto do contato simulado.
input	não		Entrada inicial opcional a ser fornecida ao iniciar a simulação.

Campos da resposta

Nome	Descrição
simulation_id	O identificador da sessão de simulação.
state	O estado atual da simulação: `"waiting_for_input"` (a jornada espera uma resposta) ou `"end"` (a jornada terminou).
message	A saída de texto da jornada. Inclui conteúdo de mensagem, opções de botões e URLs de mídia.
context	O contexto de variáveis atual da simulação, incluindo campos de contato e variáveis definidas pela jornada.

Enviando entrada para uma simulação

Quando uma simulação está no estado waiting_for_input, envie a entrada do usuário fazendo outra requisição com o mesmo simulation_id:

$ curl -X POST "https://whatsapp.turn.io/v1/stacks/<uuid-da-jornada>/simulation" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "simulation_id": "minha-sessao-001",
        "input": "Santiago"
    }'

> {
    "simulation_id": "minha-sessao-001",
    "state": "end",
    "message": "Obrigado Santiago! Seu cadastro está completo."
}

Parâmetros

Nome	Obrigatório	Descrição
simulation_id	sim	O mesmo ID de simulação usado ao iniciar a sessão.
input	sim	A resposta do usuário como uma string. Deve ser não vazia.

Exemplo de múltiplos turnos

Uma simulação típica de múltiplos turnos envolve iniciar a jornada e depois enviar entradas para cada etapa que requer uma resposta.

Etapa 1: Iniciar a jornada

$ curl -X POST "https://whatsapp.turn.io/v1/stacks/d144cb30-f759-4260-82ba-07353f0e389f/simulation" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "simulation_id": "sessao-demo-01",
        "revision": "production",
        "contact": {
            "name": "Maria",
            "language": "eng"
        }
    }'

> {
    "simulation_id": "sessao-demo-01",
    "state": "waiting_for_input",
    "message": "Olá Maria! Como podemos ajudá-la hoje?\n\nResponda exclusivamente com uma das seguintes opções:\nAgendar consulta, Verificar status, Falar com atendente",
    "context": {
        "contact": {
            "name": "Maria",
            "language": "eng"
        }
    }
}

Etapa 2: Enviar entrada do usuário

$ curl -X POST "https://whatsapp.turn.io/v1/stacks/d144cb30-f759-4260-82ba-07353f0e389f/simulation" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "simulation_id": "sessao-demo-01",
        "input": "Agendar consulta"
    }'

> {
    "simulation_id": "sessao-demo-01",
    "state": "waiting_for_input",
    "message": "Ótimo! Qual data funciona para você?"
}

Etapa 3: Continuar a conversa

$ curl -X POST "https://whatsapp.turn.io/v1/stacks/d144cb30-f759-4260-82ba-07353f0e389f/simulation" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "simulation_id": "sessao-demo-01",
        "input": "Próxima segunda-feira"
    }'

> {
    "simulation_id": "sessao-demo-01",
    "state": "end",
    "message": "Sua consulta está agendada para a próxima segunda-feira. Até lá!"
}

Respostas de erro

A API retorna códigos de status HTTP e mensagens de erro apropriados:

Status	Erro	Descrição
400	`simulation_id is required`	O campo `simulation_id` está ausente no corpo da requisição.
400	`simulation_id must be between 6 and 24 characters`	O `simulation_id` é muito curto ou muito longo.
400	`Invalid Journey UUID`	O UUID da jornada na URL não é um UUID válido.
400	`Journey has no published production revision`	A jornada não possui uma revisão de produção publicada.
400	`Journey has no staging revision`	A jornada não possui uma revisão de staging (quando `revision` é `"staging"`).
400	`Journey is disabled`	A jornada está desativada.
400	`Journey has been deleted`	A jornada foi excluída.
400	`Invalid revision, must be 'production' or 'staging'`	Um valor inválido de `revision` foi fornecido.
400	`Invalid input, must be a non-empty string`	O campo `input` está vazio ou não é uma string.
404	`Journey not found`	Nenhuma jornada existe com o UUID fornecido.
404	`Simulation not found or expired`	A sessão de simulação expirou ou não existe.

Observações

As sessões de simulação são efêmeras e expiram após um período de inatividade. Se uma sessão expirar, inicie uma nova com um simulation_id diferente.
Nenhuma mensagem real do WhatsApp é enviada durante uma simulação. A lógica da jornada é executada em memória.
Conteúdo de mídia (imagens, vídeos, áudio, documentos) nas mensagens da jornada é retornado como texto descritivo com URLs, por exemplo: "Image available at: https://...".
Quando a jornada inclui opções de botões ou listas, elas são adicionadas ao texto da mensagem, por exemplo: "Exclusively reply with one of the following options: Opção1, Opção2".
Blocos de agente de IA com memória ativada mantêm o contexto da conversa entre os turnos da simulação, permitindo que a IA faça referência a mensagens anteriores na sessão.

Como funciona​

Iniciando uma simulação​

Parâmetros​

Campos da resposta​

Enviando entrada para uma simulação​

Parâmetros​

Exemplo de múltiplos turnos​

Respostas de erro​

Observações​

Como funciona

Iniciando uma simulação

Parâmetros

Campos da resposta

Enviando entrada para uma simulação

Parâmetros

Exemplo de múltiplos turnos

Respostas de erro

Observações