Journeys

caution

Journeys were previously called stacks. The words "stacks" and "journeys" may be used interchangably in our documentation and you may still see stacks referred to in things like function names.

caution

If a journey is started for a conversation after more than 24 hours, it must start by sending a message template. WhatsApp requires you to start a conversation with a template if the user's last message is more than 24 hours old.

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

Starting a Journey via an HTTP call

To start a journey the following conditions need to be met:

1. One must supply the WhatsApp ID (or phone number) of the contact needing to start a journey for. A journey can currently only be started for a single user. Multiple users will require multiple HTTP API calls.
2. One can only start a journey for a contact who has already messaged the service on turn prior. This is because the journey requires a message to be present in order to create the context for the journey to run. This message will be available in the journey variable context under event.message. A message_id parameter can optionally be supplied and that will message will then be used to populate the context. If not supplied the last message in the chat will be used instead.
3. If the contact in question is already in an active session on Turn, the journey will not be started.

$ curl -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -X POST \
       -d '{"wa_id": "<the-whatsapp-id-of-the-user>"}' \
       https://whatsapp.turn.io/v1/stacks/<the-uuid-of-the-journey-to-start>/start

The Journey will start immediately, there is no way to schedule a journey at this point.

To start a journey with a different reference message than the most recent one:

$ curl -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -X POST \
       -d '{
            "wa_id": "<the-whatsapp-id-of-the-user>",
            "message_id": "<the-reference-message-id>"
        }' \
       https://whatsapp.turn.io/v1/stacks/<the-uuid-of-the-journey-to-start>/start

When a Journey is correctly started it will respond with an HTTP 201 status with the {"success": true} as the JSON response.

If it fails to start it will return an error in the HTTP 400 range with a JSON error explaining the reason of the failure.

Get Journey logs

To get the logs for a given journey, perform an HTTP GET request including our vendor specific Accept: application/vnd.v1+json. It returns the 1000 most recent logs, ordered by timestamp ascending.

Optional parameters

• from: only show logs that were recorded after a given timestamp in microseconds.

$ curl https://whatsapp.turn.io/v1/stacks/<the-uuid-of-the-journey>/logs?from=1687569529563008
       -H "Authorization: Bearer <token>" \
       -H "Content-Type: application/json"

> '[
       {
              "level": "info",
              "message": "hello world",
              "metadata": {
                     "app": "https://whatsapp.turn.io/app/number/39de874e-e916-49b4-9670-e6f6ce704ae9",
                     "chat": "https://whatsapp.turn.io/app/c/3d8009e1-9b2e-4872-a601-debc74185fcf",
                     "card": %{
                            "condition": null,
                            "meta": %{"column": 3, "line": 8},
                            "name": "Greeting"
                     },
                     "session_id": "001056e6-b9d5-4c3f-bddf-74d66483d072",
                     "stack": "https://whatsapp.turn.io/app/stacks/39de874e-e916-49b4-9670-e6f6ce704ae9/12719410-6fab-4ff2-8029-2f136dafd5e0"
              },
              "timestamp": 1687569529563012
       },
       {
              "level": "error",
              "message": "[body: \"ERROR: timeout\", status: nil, type: \"webhook\"]",
              "metadata": {
                     "app": "https://whatsapp.turn.io/app/number/39de874e-e916-49b4-9670-e6f6ce704ae9",
                     "chat": "https://whatsapp.turn.io/app/c/3d8009e1-9b2e-4872-a601-debc74185fcf",
                     "card": %{
                            "condition": null,
                            "meta": %{"column": 8, "line": 24},
                            "name": "CallApi"
                     },
                     "session_id": "001056e6-b9d5-4c3f-bddf-74d66483d072",
                     "stack": "https://whatsapp.turn.io/app/stacks/39de874e-e916-49b4-9670-e6f6ce704ae9/12719410-6fab-4ff2-8029-2f136dafd5e0",
                     "support_id": "fcb6d55f95e4406db2b583b8f2004449"
              },
              "timestamp": 3012569529564529
       }
]'