Journeys Simulation API

The Journeys Simulation API allows external systems (such as AI agents) to interact with journeys conversationally without sending real WhatsApp messages. This is useful for testing, previewing, and integrating journey logic into external workflows.

warning

This API is under active development and breaking changes are expected over the coming months. Backwards compatibility is not guaranteed until at least August 2026.

Authentication happens as per all other API calls with a Turn.io token specified in the HTTP Authorization header prefixed with Bearer and followed by a token issued by the Turn.io user interface.

How it works

The simulation endpoint uses a single POST route that handles both creating new simulations and submitting input to existing ones:

• If no simulation exists for the given simulation_id: a new simulation session is created and the journey starts executing.
• If a simulation already exists for the given simulation_id: the provided input is submitted to the existing session.

The simulation_id is always required and provided by the caller. It can be any string identifier between 6 and 32 characters. The endpoint uses the combination of the journey UUID (from the URL) and the simulation_id (from the body) to identify simulation sessions.

Starting a simulation

To start a new simulation, make the following request:

$ curl -X POST "https://whatsapp.turn.io/v1/journeys/<journey-uuid>/simulation" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "simulation_id": "my-session-001",
        "revision": "production",
        "contact": {
            "name": "Test User",
            "language": "eng"
        }
    }'

> {
    "state": "waiting_for_input",
    "message": "Welcome! What is your name?",
    "context": {
        "contact": {
            "name": "Test User",
            "language": "eng"
        }
    }
}

Parameters

Name	Required	Default	Description
simulation_id	yes		A caller-provided string identifier (6 to 32 characters) used to track the simulation session.
revision	no	"production"	Which revision of the journey to simulate. Must be "production" or "staging".
contact	no	{}	An object of contact attributes to populate the simulated contact context. Setting a reserved field to null clears it, which is useful for simulating contacts without a whatsapp_id.
parent	no		An object exposed to the journey as @parent.*, for simulating a function-like journey invoked from a parent. Reserved variables (chat, contact, event, global, number, organisation) are ignored.
child	no		An object exposed to the journey as @child.*, for simulating a journey resuming after a child journey has finished. Reserved variables are ignored, as for parent.
input	no		Optional initial input to provide when starting the simulation.

Response fields

Name	Description
simulation_id	The simulation session identifier.
state	The current state of the simulation: "waiting_for_input" (journey expects a reply) or "end" (journey has finished).
message	The text output from the journey. Includes message content, button options, and media URLs.
context	The current variable context of the simulation, including contact fields and any variables set by the journey. Returned on every turn, so contact writes that happen after a reply are observable.

Simulating a contact without a reserved field

Fields the simulator generates for you — such as whatsapp_id, name, and language — can be cleared by passing null explicitly. This is useful for testing journeys against contacts that genuinely lack a field, for example a username-only contact with no WhatsApp number:

{
    "simulation_id": "my-session-001",
    "contact": {
        "whatsapp_id": null
    }
}

An empty string ("") is treated as "not supplied" and falls back to the generated value, since it usually reflects an omitted field rather than an intent to clear it. Use null when you mean to clear.

Simulating a journey that expects parent or child variables

Journeys that are normally invoked by another journey can read @parent.* (values passed in by the journey that called them) and @child.* (values returned by a journey they called). Pass parent and child to exercise these paths directly, without having to run the surrounding journey:

$ curl -X POST "https://whatsapp.turn.io/v1/journeys/<journey-uuid>/simulation" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "simulation_id": "my-session-001",
        "parent": {
            "customer_name": "Alice",
            "order_id": "A-1"
        },
        "child": {
            "status": "approved"
        }
    }'

> {
    "state": "end",
    "message": "Order A-1 for Alice was approved.",
    "context": {
        "contact": {
            "name": "Test User"
        }
    }
}

This makes it practical to test a function-like journey against many combinations of inputs in CI.

Both objects ignore the reserved variables chat, contact, event, global, number, and organisation. These are managed by the simulator itself, so passing them has no effect — set contact fields via the contact parameter instead. Anything else you pass is exposed unchanged.

Note that parent and child are applied when the session is created. Sending them alongside input on a later request has no effect, since that request submits to the existing session.

Submitting input to a simulation

Once a simulation is in the waiting_for_input state, submit user input by making another request with the same simulation_id:

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

> {
    "state": "end",
    "message": "Thanks Santiago! Your registration is complete.",
    "context": {
        "contact": {
            "name": "Santiago"
        }
    }
}

Parameters

Name	Required	Description
simulation_id	yes	The same simulation ID used when starting the session.
input	yes	The user's response as a string. Must be non-empty.

Multi-turn example

A typical multi-turn simulation involves starting the journey and then submitting input for each step that requires a response.

Step 1: Start the journey

$ 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": "demo-session-01",
        "revision": "production",
        "contact": {
            "name": "Maria",
            "language": "eng"
        }
    }'

> {
    "state": "waiting_for_input",
    "message": "Hi Maria! How can we help you today?\n\nExclusively reply with one of the following options:\nBook appointment\nCheck status\nSpeak to agent",
    "context": {
        "contact": {
            "name": "Maria",
            "language": "eng"
        }
    }
}

Step 2: Submit user input

$ 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": "demo-session-01",
        "input": "Book appointment"
    }'

> {
    "state": "waiting_for_input",
    "message": "Great! What date works for you?",
    "context": {
        "contact": {
            "name": "Maria",
            "language": "eng"
        }
    }
}

Step 3: Continue the conversation

$ 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": "demo-session-01",
        "input": "Next Monday"
    }'

> {
    "state": "end",
    "message": "Your appointment is booked for next Monday. See you then!",
    "context": {
        "contact": {
            "name": "Maria",
            "language": "eng",
            "appointment_date": "Next Monday"
        }
    }
}

Because context is returned on this turn too, a test can assert directly that the journey wrote appointment_date to the contact, instead of inferring it from the confirmation message.

Error responses

The API returns appropriate HTTP status codes and error messages:

Status	Error	Description
400	simulation_id is required	The simulation_id field is missing from the request body.
400	simulation_id must be between 6 and 32 characters	The simulation_id is too short or too long.
400	Invalid Journey UUID	The journey UUID in the URL is not a valid UUID.
400	Journey has no published production revision	The journey does not have a published production revision.
400	Journey has no staging revision	The journey does not have a staging revision (when revision is "staging").
400	Journey is disabled	The journey is currently disabled.
400	Journey has been deleted	The journey has been deleted.
400	Invalid revision, must be 'production' or 'staging'	An invalid revision value was provided.
400	Invalid parent, must be an object	The parent field was provided but is not an object.
400	Invalid child, must be an object	The child field was provided but is not an object.
400	Invalid input, must be a non-empty string	The input field is empty or not a string.
404	Journey not found	No journey exists with the given UUID.
404	Simulation not found or expired	The simulation session has expired or does not exist.

Notes

• Simulation sessions are ephemeral and will expire after a period of inactivity. If a session expires, start a new one with a fresh simulation_id.
• No real WhatsApp messages are sent during a simulation. The journey logic is executed in-memory.
• Media content (images, videos, audio, documents) in journey messages is returned as descriptive text with URLs, for example: "Image available at: https://...".
• When the journey includes button or list options, they are appended to the message text, one option per line.
• Contact fields written by the journey are reflected in context on the turn they happen, so a write that occurs after a reply can be asserted on directly rather than inferred from the message text.
• AI agent blocks with memory enabled will persist conversation context across simulation turns, allowing the AI to reference earlier messages in the session.