Pular para o conteúdo principal

API de Jornadas

cuidado

As jornadas eram anteriormente chamadas de "stacks". As palavras "stacks" e "jornadas" podem ser usadas de forma intercambiável em nossa documentação, e você ainda pode ver o termo "stacks" em nomes de funções e outros locais.

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.

cuidado

As operações de criação, atualização e publicação da API estão disponíveis apenas no plano Enterprise.

Criando uma Jornada​

Para criar uma jornada, você precisa fornecer um objeto JSON com os seguintes campos:

  • name: STRING, obrigatório
  • publish_latest_changes: BOOLEAN, padrão é false
  • enabled: BOOLEAN, padrão é true
  • notebook: STRING, obrigatório
$ curl https://whatsapp.turn.io/v1/stacks \
       -H "Authorization: Bearer <token>" \
       -H "Content-Type: application/json" \
       -d '{
            "name": "Minha Jornada de Código",
            "publish_latest_changes": true,
            "enabled": true,
            "notebook": "stack Jornada do\n  card Cartão do\n    text(\"olá\")\n  end\nend"
        }'
> {
  "name": "Minha Jornada de Código",
  "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
}

Atualizando uma Jornada​

Para atualizar uma jornada, você precisa fornecer um objeto JSON com os seguintes campos:

  • name: STRING, opcional
  • publish_latest_changes: BOOLEAN, padrão é false
  • enabled: BOOLEAN, opcional
  • notebook: STRING, opcional
$ 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": "Novo Nome",
            "publish_latest_changes": true,
            "enabled": true,
            "notebook": "stack Jornada do\n  card Cartão do\n    text(\"oi\")\n  end\nend"
        }'
> {
  "name": "Novo Nome",
  "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
}

Publicar Última Revisão do Notebook​

Publique a versão mais recente de uma jornada.

$ curl -X POST https://whatsapp.turn.io/v1/stacks/2299109f-04aa-4fb4-bb41-a3f653e63658/publish \
       -H "Authorization: Bearer <token>"

> {"success": true}

Obter detalhes de todas as Jornadas​

Obtenha os detalhes de todas as jornadas de um determinado número.

$ 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": "Minha Jornada Canvas",
              "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": null
       },
       {
              "inserted_at": "2023-08-05T15:17:43.073516Z",
              "name": "Minha Jornada de Código",
              "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"
       }
]'

Obter especificação FLOIP da Jornada​

Obtenha a especificação FLOIP de uma jornada específica como um arquivo JSON.

$ curl https://whatsapp.turn.io/v1/stacks/2299109f-04aa-4fb4-bb41-a3f653e63658 \
       -H "Authorization: Bearer <token>"

> '{
       "description": "Descrição padrão",
       "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": "Inglês",
                                   "variant": null
                            }
                     ],
                     "last_modified": "2024-07-28T22:12:41.044217Z",
                     "name": "jornada",
                     "supported_modes": [
                            "RICH_MESSAGING"
                     ],
                     "uuid": "5f397f22-2710-4754-99e5-21e96a85bfac",
                     "vendor_metadata": {}
              }
       ],
       "name": "Minha Jornada de Código",
       "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": "olá"
                            }
                     ]
              }
       ],
       "specification_version": "1.0.0-rc3",
       "uuid": "c666d2fc-6843-4d66-84e9-afbd1e898955",
       "vendor_metadata": {}
}'

Obter o código cru da Jornada​

Obtenha o código cru da Jornada como um arquivo markdown.

$ curl https://whatsapp.turn.io/v1/stacks/2299109f-04aa-4fb4-bb41-a3f653e63658?format=md \
       -H "Authorization: Bearer <token>"

> '
# Minha primeira Jornada em código

<!-- { section: "98ec5f44-da93-479b-a83a-054409eb1107", x: 0, y: 0} -->

```stack
stack Jornada do
  card Card do
    text("hi")
  end
end
```
'

Iniciar uma Jornada via chamada HTTP​

cuidado

Se uma jornada no WhatsApp for iniciada para uma conversa após mais de 24 horas, ela deve começar enviando uma mensagem de modelo (template). O WhatsApp exige que você inicie uma conversa com um modelo (template) se a última mensagem do usuário tiver mais de 24 horas.

Nos canais de API HTTP da Turn.io, você pode iniciar uma jornada para uma conversa sem uma mensagem de modelo (template) após mais de 24 horas usando esta API. (Por enquanto, não é possível usar a interface Inbox UI para iniciar uma jornada para uma conversa após mais de 24 horas).

Para iniciar uma jornada, as seguintes condições precisam ser atendidas:

  1. Deve-se fornecer o ID do WhatsApp (ou número de telefone) do contato para quem a jornada será iniciada. Uma jornada pode ser iniciada atualmente apenas para um único usuário. Vários usuários exigirão várias chamadas da API HTTP.
  2. Pode-se iniciar uma jornada apenas para um contato que já tenha enviado uma mensagem para o serviço na Turn.io anteriormente. Isso ocorre porque a jornada requer uma mensagem para criar o contexto necessário para a execução da jornada. Essa mensagem estará disponível no contexto de variáveis da jornada sob event.message. Um parâmetro message_id pode ser fornecido opcionalmente e essa mensagem será usada para preencher o contexto. Caso contrário, a última mensagem no chat será usada.
  3. Se o contato em questão já estiver em uma sessão ativa na Turn.io, a jornada não será iniciada.
$ curl -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -X POST \
       -d '{"wa_id": "<o-id-do-whatsapp-do-usuario>"}' \
       https://whatsapp.turn.io/v1/stacks/<o-uuid-da-jornada-a-iniciar>/start

A jornada será iniciada imediatamente, não há como agendar uma jornada neste momento.

Para iniciar uma jornada com uma mensagem de referência diferente da mais recente:

$ curl -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -X POST \
       -d '{
            "wa_id": "<o-id-do-whatsapp-do-usuario>",
            "message_id": "<o-id-da-mensagem-de-referencia>"
        }' \
       https://whatsapp.turn.io/v1/stacks/<o-uuid-da-jornada-a-iniciar>/start

Quando uma jornada é iniciada corretamente, ela responderá com um status HTTP 201 e o JSON {"success": true}.

Se falhar, retornará um erro no intervalo HTTP 400 com um JSON explicando o motivo da falha.

Obter logs da Jornada​

Obtenha os logs de uma jornada específica. Retorna os 1000 logs mais recentes, ordenados por timestamp de forma ascendente.

Parâmetros opcionais​

  • from: mostra apenas logs que foram registrados após um timestamp específico (em microssegundos).
$ curl https://whatsapp.turn.io/v1/stacks/<o-uuid-da-jornada>/logs?from=1687569529563008 \
       -H "Authorization: Bearer <token>" \
       -H "Content-Type: application/json"

> '[
       {
              "level": "info",
              "message": "olá mundo",
              "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
       }
]'