Journeys API
caution
Journeys were previously called stacks. The words "stacks" and "journeys" may be used interchangeably in our documentation and you may still see stacks referred to in things like function names.
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.
caution
Create, update and publish API operations are only available in the Enterprise plan.
Creating a Journey
To create a Journey, you need to provide a JSON object with the following fields:
name: STRING, requiredpublish_latest_changes: BOOLEAN, defaults tofalseenabled: BOOLEAN, defaults totruenotebook: STRING, required
$ curl https://whatsapp.turn.io/v1/stacks \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"name": "My Code Journey",
"publish_latest_changes": true,
"enabled": true,
"notebook": "stack Journey do\n card Card do\n text(\"hi\")\n end\nend"
}'
> {
"name": "My Code Journey",
"uuid": "d144cb30-f759-4260-82ba-07353f0e389f",
"updated_at": "2024-09-04T19:05:50.802047Z",
"inserted_at": "2024-09-04T19:05:50.802047Z",
"is_canvas": false,
"url": "https://whatsapp.turn.io/v1/stacks/d144cb30-f759-4260-82ba-07353f0e389f",
"is_notebook_valid": true,
"production_notebook_revision_uuid": "1bd73256-8c13-4057-89a7-a8e3b5c139a9"
"enabled": true,
"has_unpublished_changes": false
}
Updating a Journey
To update a Journey, you need to provide a JSON object with the following fields:
name: STRING, optionalpublish_latest_changes: BOOLEAN, defaults tofalseenabled: BOOLEAN, optionalnotebook: STRING, optional
$ curl -X PATCH https://whatsapp.turn.io/v1/stacks/d144cb30-f759-4260-82ba-07353f0e389f \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"name": "New Name",
"publish_latest_changes": true,
"enabled": true,
"notebook": "stack Journey do\n card Card do\n text(\"hello\")\n end\nend"
}'
> {
"name": "New Name",
"uuid": "d144cb30-f759-4260-82ba-07353f0e389f",
"updated_at": "2024-09-04T19:05:50.802047Z",
"inserted_at": "2024-09-05T20:02:51.102046Z",
"is_canvas": false,
"url": "https://whatsapp.turn.io/v1/stacks/d144cb30-f759-4260-82ba-07353f0e389f",
"is_notebook_valid": true,
"enabled": true,
"production_notebook_revision_uuid": "617af2c4-eca6-47d6-9ffc-7a614b5d22f9",
"has_unpublished_changes": false
}
Publish Latest Notebook Revision
Publish the latest version of a Journey.
$ curl -X POST https://whatsapp.turn.io/v1/stacks/2299109f-04aa-4fb4-bb41-a3f653e63658/publish \
-H "Authorization: Bearer <token>"
> {"success": true}
Get all Journey details
Get the details of all Journeys from a given number.
$ curl https://whatsapp.turn.io/v1/stacks \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json"
> '[
{
"inserted_at": "2023-09-05T15:17:43.073516Z",
"name": "My Canvas Journey",
"is_canvas": true,
"is_notebook_valid": true,
"updated_at": "2023-09-05T15:17:43.073516Z",
"url": "https://whatsapp.turn.io/v1/stacks/280f7035-be13-46ab-90e6-15fbc75ca973",
"uuid": "280f7035-be13-46ab-90e6-15fbc75ca973",
"enabled": true,
"has_unpublished_changes": true,
"production_notebook_revision_uuid": nil,
},
{
"inserted_at": "2023-08-05T15:17:43.073516Z",
"name": "My Code Journey",
"is_canvas": false,
"is_notebook_valid": true,
"updated_at": "2023-10-01T12:19:43.073512Z",
"url": "https://whatsapp.turn.io/v1/stacks/2299109f-04aa-4fb4-bb41-a3f653e63658",
"uuid": "2299109f-04aa-4fb4-bb41-a3f653e63658",
"enabled": false,
"has_unpublished_changes": false,
"production_notebook_revision_uuid": "a666d2fc-6843-4d66-84e9-afbd1e898955",
}
]'
Get the Journey's FLOIP specification
Get the FLOIP specification of a given Journey as a JSON file.
$ curl https://whatsapp.turn.io/v1/stacks/2299109f-04aa-4fb4-bb41-a3f653e63658 \
-H "Authorization: Bearer <token>"
> '{
"description": "Default description",
"flows": [
{
"blocks": [
{
"config": {
"prompt": "363a3491-c781-497c-b502-ea195ca0c835"
},
"exits": [
{
"config": {},
"default": true,
"destination_block": null,
"name": "card_text",
"semantic_label": "",
"test": "",
"uuid": "39a1cfcd-c88d-445b-8c43-fdf9c24ace6f",
"vendor_metadata": {}
}
],
"label": null,
"name": "card_text",
"semantic_label": null,
"tags": [],
"type": "MobilePrimitives.Message",
"ui_metadata": {
"canvas_coordinates": {
"x": 0,
"y": 0
}
},
"uuid": "36ca1800-af6a-5f9a-a207-6f57deab175d",
"vendor_metadata": {
"io": {
"turn": {
"stacks_dsl": {
"0.1.0": {
"card": {
"condition": null,
"meta": {
"column": 3,
"line": 2
},
"name": "Card",
"uuid": "4d692c00-9ba9-54f9-a873-e3900b9eb5db"
},
"card_item": {
"meta": {
"column": 5,
"line": 3
},
"text": {},
"type": "text"
},
"index": 0
}
}
}
}
}
}
],
"exit_block_id": "",
"first_block_id": "36ca1800-af6a-5f9a-a207-6f57deab175d",
"interaction_timeout": 300,
"label": null,
"languages": [
{
"bcp_47": null,
"id": "93acf2a1-f165-468a-9e36-ae5b174fe2a2",
"iso_639_3": "eng",
"label": "English",
"variant": null
}
],
"last_modified": "2024-07-28T22:12:41.044217Z",
"name": "journey",
"supported_modes": [
"RICH_MESSAGING"
],
"uuid": "5f397f22-2710-4754-99e5-21e96a85bfac",
"vendor_metadata": {}
}
],
"name": "My Code Journey",
"resources": [
{
"uuid": "363a3491-c781-497c-b502-ea195ca0c835",
"values": [
{
"content_type": "TEXT",
"language_id": "93acf2a1-f165-468a-9e36-ae5b174fe2a2",
"mime_type": "text/plain",
"modes": [
"RICH_MESSAGING"
],
"value": "hi"
}
]
}
],
"specification_version": "1.0.0-rc3",
"uuid": "c666d2fc-6843-4d66-84e9-afbd1e898955",
"vendor_metadata": {}
}'
Get the Journey's raw code
Get the Journey's raw code as a markdown file.
$ curl https://whatsapp.turn.io/v1/stacks/2299109f-04aa-4fb4-bb41-a3f653e63658?format=md \
-H "Authorization: Bearer <token>"
> '
# My first code Journey
<!-- { section: "98ec5f44-da93-479b-a83a-054409eb1107", x: 0, y: 0} -->
```stack
stack Journey do
card Card do
text("hi")
end
end
```
'
Starting a Journey via an HTTP call
caution
If a WhatsApp 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. In Channel HTTP API Channels you can start a journey for a conversation without a template message after more than 24 hours using this API. (For now it's not possible to use Inbox UI to start a journey for a conversation after more than 24 hours)
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_idparameter 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
Get the logs from a given Journey. 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
}
]'