Journeys
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.
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:
- 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.
- 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
. Amessage_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. - 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
}
]'