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)

Resposta (Listar sessões)

200Sessões devolvidas

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)

Resposta (Ver uma sessão)

200Sessão devolvida

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)

Resposta (Listar variações)

200Variações devolvidas

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)

Resposta (Rodar uma mensagem)

200Rodada executada

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
bash
curl "$BASE_URL/api/v1/admin/whatsapp/flow-sessions?state=active&limit=20" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/whatsapp/flow-sessions/0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/whatsapp/flow-sessions/0b7d3c1e-5a42-4d8f-9e61-3c2a7f4b8d10/variants" \
  -H "Authorization: Bearer $TOKEN"
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"
  }'
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
}
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"
}
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"
    }
  ]
}
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"
    }
  ]
}