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 32 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/journeys/<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"
        }
    }'

> {
    "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 32 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. Definir um campo reservado como null o limpa, o que é útil para simular contatos sem whatsapp_id.
parent	não		Um objeto exposto à jornada como @parent.*, para simular uma jornada do tipo função invocada por uma jornada pai. Variáveis reservadas (chat, contact, event, global, number, organisation) são ignoradas.
child	não		Um objeto exposto à jornada como @child.*, para simular uma jornada retomando após o término de uma jornada filha. Variáveis reservadas são ignoradas, como em parent.
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. Retornado a cada turno, então escritas de contato que acontecem após uma resposta são observáveis.

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/journeys/<uuid-da-jornada>/simulation" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "simulation_id": "minha-sessao-001",
        "input": "Santiago"
    }'

> {
    "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/journeys/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"
        }
    }'

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

Etapa 2: Enviar entrada do usuário

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

> {
    "state": "waiting_for_input",
    "message": "Ótimo! Qual data funciona para você?"
}

Etapa 3: Continuar a conversa

$ curl -X POST "https://whatsapp.turn.io/v1/journeys/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"
    }'

> {
    "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 32 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 parent, must be an object	O campo parent foi fornecido, mas não é um objeto.
400	Invalid child, must be an object	O campo child foi fornecido, mas não é um objeto.
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, uma opção por linha.
• Campos de contato escritos pela jornada são refletidos em context no turno em que acontecem, então uma escrita que ocorre após uma resposta pode ser verificada diretamente, em vez de inferida a partir do texto da mensagem.
• 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.