VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: fluxos do bot

Sessões de fluxo

Consulta as sessões (conversas em andamento ou encerradas dentro de um fluxo), suas variações e roda uma mensagem de teste.

Cada cliente que entra num fluxo ganha uma sessão, que guarda em que bloco ele está e o que já respondeu. Uma sessão ativa vence depois de um tempo sem uso (expires_at).

Listar sessões

Uma sessão é uma conversa de um cliente dentro de um fluxo. A lista mostra quem está no meio do fluxo, quem terminou, quem desistiu e onde houve erro. Do mais novo ao mais antigo.

GET/api/v1/admin/whatsapp/flow-sessionsAdmin

Lista as sessões de fluxo

Parâmetros de consulta

vendor_iduuid
Filtra por seller.
flow_iduuid
Filtra por fluxo.
statestring
activecompletedabandonederrored
Filtra por estado.
phone_numberstring
Filtra por telefone, igualdade exata, como está gravado.
limitintegerpadrão: 50
Itens por página, de 1 a 200. Acima de 200 vira 200.
offsetintegerpadrão: 0
Quantos itens pular.

Exemplo de requisição (Listar sessões)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/flow-sessions?state=active&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar sessões)

200Sessões devolvidas
json
{
  "sessions": [
    {
      "id": "0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "flow_id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
      "thread_id": "5b1f0c7e-2a3d-4c88-9e41-0a7d6b3c9f22",
      "phone_number": "5511999990000",
      "current_block_id": "b8c1057a-d5b6-448f-af73-31734882b110",
      "state": "active",
      "session_data": {
        "cart_id": "c-123"
      },
      "last_block_entered_at": "2026-10-11T14:40:00Z",
      "last_interaction_at": "2026-10-11T14:40:00Z",
      "started_at": "2026-10-11T14:39:50Z",
      "expires_at": "2026-10-12T14:39:50Z",
      "created_at": "2026-10-11T14:39:50Z",
      "updated_at": "2026-10-11T14:40:00Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

Campos da resposta

sessionsarray

Sessões da página.

iduuid
Identificador da sessão.
vendor_iduuid
Seller da sessão.
flow_iduuid
Fluxo que está rodando.
thread_iduuid
Conversa da caixa de entrada. Ausente quando não há.
phone_numberstring
Telefone do cliente (ou +sim-... numa simulação).
current_block_iduuid
Bloco em que a sessão está. Ausente quando terminou.
statestring
activecompletedabandonederrored
Estado da sessão.
session_dataobject
Variáveis guardadas durante a conversa (respostas do cliente, escolhas).
error_messagestring
Motivo do erro, quando state é errored.
last_block_entered_atstring
Quando entrou no bloco atual (RFC 3339).
last_interaction_atstring
Última mensagem do cliente (RFC 3339).
started_atstring
Início (RFC 3339).
expires_atstring
Vencimento (RFC 3339). Depois disso a sessão é abandonada na próxima mensagem.
completed_atstring
Fim (RFC 3339). Ausente enquanto ativa.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).
limitinteger
Limite aplicado.
offsetinteger
Deslocamento aplicado.

Erros (Listar sessões)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
500Falha ao consultar (inclusive vendor_id ou flow_id que não é UUID).{"error":"Failed to list flow sessions: ..."}

Ver uma sessão

Devolve uma sessão pelo id, com as variáveis guardadas até agora.

GET/api/v1/admin/whatsapp/flow-sessions/{id}Admin

Lê uma sessão de fluxo

Parâmetros de caminho

iduuidobrigatório
Id da sessão.

Exemplo de requisição (Ver uma sessão)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/flow-sessions/0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Ver uma sessão)

200Sessão devolvida
json
{
  "id": "0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "flow_id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
  "thread_id": "5b1f0c7e-2a3d-4c88-9e41-0a7d6b3c9f22",
  "phone_number": "5511999990000",
  "current_block_id": "b8c1057a-d5b6-448f-af73-31734882b110",
  "state": "active",
  "session_data": {
    "cart_id": "c-123"
  },
  "last_block_entered_at": "2026-10-11T14:40:00Z",
  "last_interaction_at": "2026-10-11T14:40:00Z",
  "started_at": "2026-10-11T14:39:50Z",
  "expires_at": "2026-10-12T14:39:50Z",
  "created_at": "2026-10-11T14:39:50Z",
  "updated_at": "2026-10-11T14:40:00Z"
}

Campos da resposta

iduuid
Identificador da sessão.
vendor_iduuid
Seller da sessão.
flow_iduuid
Fluxo que está rodando.
thread_iduuid
Conversa da caixa de entrada. Ausente quando não há.
phone_numberstring
Telefone do cliente (ou +sim-... numa simulação).
current_block_iduuid
Bloco em que a sessão está. Ausente quando terminou.
statestring
activecompletedabandonederrored
Estado da sessão.
session_dataobject
Variáveis guardadas durante a conversa (respostas do cliente, escolhas).
error_messagestring
Motivo do erro, quando state é errored.
last_block_entered_atstring
Quando entrou no bloco atual (RFC 3339).
last_interaction_atstring
Última mensagem do cliente (RFC 3339).
started_atstring
Início (RFC 3339).
expires_atstring
Vencimento (RFC 3339). Depois disso a sessão é abandonada na próxima mensagem.
completed_atstring
Fim (RFC 3339). Ausente enquanto ativa.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros (Ver uma sessão)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
404Sessão não encontrada.{"error":"Flow session not found"}
500O id não é um UUID válido (a plataforma devolve 500 em vez de 400).{"error":"Failed to load flow session: whatsapp/flow_session: get by id: pq: invalid input syntax for type uuid: \"xyz\" (22P02)"}

Variações escolhidas na sessão

Quando o cliente monta uma compra com tamanho e cor dentro do fluxo, cada escolha fica registrada como uma variação da sessão. Esta rota lista essas escolhas.

GET/api/v1/admin/whatsapp/flow-sessions/{id}/variantsAdmin

Lista as variações escolhidas numa sessão

Parâmetros de caminho

iduuidobrigatório
Id da sessão.

Exemplo de requisição (Listar variações)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/flow-sessions/0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10/variants" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar variações)

200Variações devolvidas
json
{
  "session_id": "0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10",
  "variants": [
    {
      "id": "7d6e5f4a-3b2c-4a19-8e07-6f5d4c3b2a10",
      "flow_session_id": "0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10",
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "variant_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "selected_variants": {
        "Tamanho": "M",
        "Cor": "Azul"
      },
      "combination_hash": "m-azul",
      "quantity": 2,
      "price_centavos": 19990,
      "complete": true,
      "created_at": "2026-10-11T14:41:00Z",
      "updated_at": "2026-10-11T14:41:30Z"
    }
  ]
}

Campos da resposta

session_iduuid
A sessão pedida.
variantsarray

Variações, na ordem em que o cliente escolheu.

iduuid
Identificador da escolha.
flow_session_iduuid
A sessão.
product_iduuid
Produto escolhido.
variant_iduuid
Variação do produto, quando já resolvida.
selected_variantsobject
Atributos escolhidos, por exemplo tamanho e cor.
combination_hashstring
Chave da combinação escolhida.
quantityinteger
Quantidade.
price_centavosinteger
Preço unitário em centavos inteiros (19990 = R$ 199,90). Ausente quando não definido.
completeboolean
true quando todos os atributos foram escolhidos.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros (Listar variações)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
500O id não é um UUID válido.{"error":"Failed to list variants: ..."}
Sessão inexistente devolve lista vazia

A rota não confere se a sessão existe: um id válido sem registros devolve variants: [] com status 200.

Rodar uma mensagem numa sessão

Alimenta uma sessão existente com uma mensagem de texto e devolve a resposta e as ações que o bot geraria. É o botão "testar" do editor de fluxos.

POST/api/v1/admin/whatsapp/flow-sessions/{id}/test-runAdmin

Roda uma mensagem de teste numa sessão

Parâmetros de caminho

iduuidobrigatório
Id da sessão.

Corpo da requisição

inbound_textstring
Texto que o cliente teria enviado.

Exemplo de requisição (Rodar uma mensagem)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/flow-sessions/0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10/test-run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_text": "1"
  }'

Resposta (Rodar uma mensagem)

200Rodada executada
json
{
  "session_id": "0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10",
  "reply_text": "Ótimo! Veja nossos produtos.",
  "actions": [
    {
      "kind": "send_text",
      "body": "Ótimo! Veja nossos produtos."
    },
    {
      "kind": "wait_for_input"
    }
  ]
}

Campos da resposta

session_iduuid
A sessão usada.
reply_textstring
Texto principal da resposta.
actionsarray
Ações do bot, na ordem. Cada uma tem kind (send_text, send_media, send_cta_url, send_buttons, send_list, wait_for_input, complete, handoff_to_human) e, conforme o tipo, body, media_url, content_type, buttons ou items.

Erros (Rodar uma mensagem)

StatusQuandoCorpo
400Corpo que não é JSON, sessão inexistente ou terminada, ou erro do bloco atual.{"error":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
A sessão avança de verdade

A rota executa o motor sobre a sessão indicada e grava o novo estado. Nada é enviado ao cliente, mas se você usar o id de uma sessão de um cliente real a conversa dele avança sem que ele saiba. Para testar, prefira POST /flows/{id}/simulate, que usa sessões sintéticas.

Veja também

  • Testar um fluxo
  • Visão geral
Anterior
Testar um fluxo
Próxima
Pedidos de mudança
Nesta página
  • Listar sessões
  • Exemplo de requisição (Listar sessões)
  • Resposta (Listar sessões)
  • Erros (Listar sessões)
  • Ver uma sessão
  • Exemplo de requisição (Ver uma sessão)
  • Resposta (Ver uma sessão)
  • Erros (Ver uma sessão)
  • Variações escolhidas na sessão
  • Exemplo de requisição (Listar variações)
  • Resposta (Listar variações)
  • Erros (Listar variações)
  • Rodar uma mensagem numa sessão
  • Exemplo de requisição (Rodar uma mensagem)
  • Resposta (Rodar uma mensagem)
  • Erros (Rodar uma mensagem)
  • Veja também