API atual/Referência completa/Mini-loja WhatsApp: atendimento

Assistente da loja

Conversa com o assistente de compras da mini-loja, toca nos cartões do chat e lê as mensagens que um atendente da loja escreve no mesmo chat.

A mini-loja tem um chat com um assistente que ajuda a achar produtos, montar a sacola, fechar o pedido e tirar dúvidas, usando o catálogo e as regras da loja. O cliente conversa com ele em linguagem natural. As rotas abaixo são o que o chat chama.

O assistente só vê o que o próprio cliente (o dono do token) veria: a mesma sacola, o mesmo catálogo e os mesmos preços. O que ele faz na sacola aparece de verdade nela.

Quando um atendente da loja assume a conversa pelo painel, o assistente para de responder e as mensagens da pessoa chegam ao chat pela rota de leitura do atendimento.

Enviar uma mensagem

POST/api/v1/storefront/wa-coex/intelligence/{token}/assistPública

Envia uma mensagem (ou um toque em cartão) ao assistente e recebe a resposta

Um "turno" é uma mensagem do cliente e a resposta do assistente. O histórico não fica guardado no servidor para o seu uso: o chat reenvia as mensagens anteriores em history (as 40 últimas valem) para o assistente manter o contexto. O servidor guarda cada turno para o painel da loja.

Dois modos de enviar:

Mensagem: message com o texto do cliente.
Toque em cartão: action, quando o cliente toca num botão de um cartão que o assistente mostrou (escolher entrega, pagamento, endereço, confirmar o pedido). Roda direto, como um passo fixo, e message não é necessário.

Para receber a resposta aos poucos (texto provisório enquanto o turno roda), envie ?stream=1 ou Accept: text/event-stream. A resposta vira um fluxo de eventos (SSE): eventos de texto provisório, e por fim final (o mesmo corpo da resposta normal, mais stream.total_ms), error (em falha) e done. Ignore eventos que você não conhece.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

streamstring

1

1 pede a resposta em fluxo de eventos (SSE).

Corpo da requisição

messagestring

Texto do cliente. Obrigatório, a menos que action seja enviado.

displaystring

Texto que aparece como "balão" do cliente quando difere do que o assistente recebe (por exemplo, o toque num botão de boas-vindas). O painel da loja mostra este texto.

historyarray

Turnos anteriores do chat, em ordem: objetos com role (user ou assistant) e content. Só os 40 últimos são usados.

page_contextobject

Em que tela o cliente está, para o assistente responder sobre o que ele vê.

kindstring

homesearchcategoryproductcartcheckoutordersorderprofileotherassistant

Tipo da tela.

idstring

Id do que a tela mostra (por exemplo, o produto).

labelstring

Nome da tela ou do item, para exibir.

routestring

Caminho da tela.

productobject

Produto aberto: id, name, qty, options (mapa de opção para valor).

cartobject

Sacola: count (quantidade de itens).

checkoutobject

Passo do checkout: step (address, delivery, payment ou review), shipping, payment, coupon e missing (o que falta).

actionobject

Toque num cartão do chat. Quando enviado, o assistente não usa message.

typestringobrigatório

confirm_orderchoose_shippingchoose_paymentchoose_addressset_documentedit_stepcard_order

Qual toque: confirmar o pedido, escolher entrega, escolher pagamento, escolher endereço, informar o documento, voltar a um passo ou registrar o pedido criado pela folha do cartão.

payloadobject

Dados do toque, tirados do cartão que o assistente devolveu em cards. Campos usados conforme o tipo: summary_key (confirmar), option_id (entrega), method_id, plan_id e installments (pagamento), address_id ou address (endereço), document, terms_accepted, age_confirmed e cnpj, step (voltar a um passo) e order_id (pedido do cartão).

O corpo aceita até 1 MB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/intelligence/$TOKEN/assist" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Coloca um Notebook Slim Rosa na minha sacola",
    "history": [],
    "page_context": {"kind": "home", "id": "", "label": "Início"}
  }'

Resposta

200Resposta do assistente

json

{
  "reply": "Coloquei 1 Notebook Slim Rosa na sua sacola. Quer finalizar o pedido?",
  "tool_calls": [],
  "latency_ms": 1840,
  "effects": [{ "type": "cart_updated" }],
  "last_id": 42
}

200Um atendente assumiu a conversa

json

{ "reply": "", "tool_calls": [], "human": true, "last_id": 43 }

Campos da resposta

replystring

Texto da resposta para o cliente. Vazio quando human é true.

humanboolean

true quando um atendente assumiu a conversa: o assistente não responde e o chat deve passar a ler as mensagens da pessoa (/inbox). Ausente nas respostas normais.

tool_callsarray

Só informativo e muitas vezes vazio: não dependa dele. Use effects para saber o que atualizar na tela.

latency_msinteger

Tempo do turno, em milissegundos.

cardsarray

Cartões ricos para o chat desenhar (produtos, resumo do pedido, escolhas de entrega e pagamento...). Cada cartão é um objeto cujo formato depende do tipo; os que têm botões trazem os dados que você devolve em action.payload.

actionsarray

Botões sugeridos: label, href (caminho dentro da mini-loja), variant e intent.

effectsarray

O que a página deve fazer depois do turno: type (cart_updated para reler a sacola, checkout_updated para reler o checkout, navigate com href, checkout_step com step).

last_idinteger

Cursor do atendimento: use como after em /inbox.

Erros

Status	Quando	Corpo
400	Corpo ilegível, ou sem `message` e sem `action`.	`{"error":"message required"}`
400	`action` com tipo desconhecido ou dado obrigatório faltando.	`{"error":"invalid_action","message":"..."}`
403	A loja não fecha pedidos pelo chat e o toque era de checkout.	`{"error":"assistant_checkout_disabled"}`
404	`card_order` com um pedido que não é desta sessão.	`{"error":"order_not_found"}`
502	O assistente não conseguiu responder agora.	`{"error":"<texto>"}` ou `{"error":"assistant_unavailable"}`

Ler as mensagens do atendente

GET/api/v1/storefront/wa-coex/intelligence/{token}/inboxPública

Mensagens que um atendente escreveu no chat e se a conversa está com uma pessoa

O chat consulta esta rota de tempos em tempos (polling) para mostrar o que o atendente escreve e saber se a conversa continua com uma pessoa. A resposta nunca é guardada em cache.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

afterintegerpadrão: 0

Cursor: devolve só as mensagens com id maior que ele. Com 0, devolve só o cursor atual (o chat já tem o próprio histórico).

Resposta

200Com mensagens de um atendente

json

{
  "human": true,
  "last_id": 45,
  "messages": [
    { "id": 44, "body": "Oi! Sou a Paula, vou te ajudar com o pedido.", "created_at": "2026-10-11T19:10:00Z", "from": "attendant" }
  ]
}

Campos da resposta

humanboolean

Um atendente está com a conversa (o assistente não responde).

last_idinteger

Cursor para a próxima consulta (after).

messagesarray

Mensagens novas: id, body, created_at (RFC 3339) e from (attendant, uma pessoa da loja; ou assistant, um aviso do assistente quando ninguém da equipe respondeu a tempo). [] quando não há.

Veja também

Assistente da loja

Conversa com o assistente de compras da mini-loja, toca nos cartões do chat e lê as mensagens que um atendente da loja escreve no mesmo chat.

O assistente só vê o que o próprio cliente (o dono do token) veria: a mesma sacola, o mesmo catálogo e os mesmos preços. O que ele faz na sacola aparece de verdade nela.

Quando um atendente da loja assume a conversa pelo painel, o assistente para de responder e as mensagens da pessoa chegam ao chat pela rota de leitura do atendimento.

Enviar uma mensagem

POST/api/v1/storefront/wa-coex/intelligence/{token}/assistPública

Envia uma mensagem (ou um toque em cartão) ao assistente e recebe a resposta

Dois modos de enviar:

Mensagem: message com o texto do cliente.
Toque em cartão: action, quando o cliente toca num botão de um cartão que o assistente mostrou (escolher entrega, pagamento, endereço, confirmar o pedido). Roda direto, como um passo fixo, e message não é necessário.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

streamstring

1

1 pede a resposta em fluxo de eventos (SSE).

Corpo da requisição

messagestring

Texto do cliente. Obrigatório, a menos que action seja enviado.

displaystring

Texto que aparece como "balão" do cliente quando difere do que o assistente recebe (por exemplo, o toque num botão de boas-vindas). O painel da loja mostra este texto.

historyarray

Turnos anteriores do chat, em ordem: objetos com role (user ou assistant) e content. Só os 40 últimos são usados.

page_contextobject

Em que tela o cliente está, para o assistente responder sobre o que ele vê.

kindstring

homesearchcategoryproductcartcheckoutordersorderprofileotherassistant

Tipo da tela.

idstring

Id do que a tela mostra (por exemplo, o produto).

labelstring

Nome da tela ou do item, para exibir.

routestring

Caminho da tela.

productobject

Produto aberto: id, name, qty, options (mapa de opção para valor).

cartobject

Sacola: count (quantidade de itens).

checkoutobject

Passo do checkout: step (address, delivery, payment ou review), shipping, payment, coupon e missing (o que falta).

actionobject

Toque num cartão do chat. Quando enviado, o assistente não usa message.

typestringobrigatório

confirm_orderchoose_shippingchoose_paymentchoose_addressset_documentedit_stepcard_order

Qual toque: confirmar o pedido, escolher entrega, escolher pagamento, escolher endereço, informar o documento, voltar a um passo ou registrar o pedido criado pela folha do cartão.

payloadobject

O corpo aceita até 1 MB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/intelligence/$TOKEN/assist" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Coloca um Notebook Slim Rosa na minha sacola",
    "history": [],
    "page_context": {"kind": "home", "id": "", "label": "Início"}
  }'

Resposta

200Resposta do assistente

json

{
  "reply": "Coloquei 1 Notebook Slim Rosa na sua sacola. Quer finalizar o pedido?",
  "tool_calls": [],
  "latency_ms": 1840,
  "effects": [{ "type": "cart_updated" }],
  "last_id": 42
}

200Um atendente assumiu a conversa

json

{ "reply": "", "tool_calls": [], "human": true, "last_id": 43 }

Campos da resposta

replystring

Texto da resposta para o cliente. Vazio quando human é true.

humanboolean

true quando um atendente assumiu a conversa: o assistente não responde e o chat deve passar a ler as mensagens da pessoa (/inbox). Ausente nas respostas normais.

tool_callsarray

Só informativo e muitas vezes vazio: não dependa dele. Use effects para saber o que atualizar na tela.

latency_msinteger

Tempo do turno, em milissegundos.

cardsarray

actionsarray

Botões sugeridos: label, href (caminho dentro da mini-loja), variant e intent.

effectsarray

O que a página deve fazer depois do turno: type (cart_updated para reler a sacola, checkout_updated para reler o checkout, navigate com href, checkout_step com step).

last_idinteger

Cursor do atendimento: use como after em /inbox.

Erros

Status	Quando	Corpo
400	Corpo ilegível, ou sem `message` e sem `action`.	`{"error":"message required"}`
400	`action` com tipo desconhecido ou dado obrigatório faltando.	`{"error":"invalid_action","message":"..."}`
403	A loja não fecha pedidos pelo chat e o toque era de checkout.	`{"error":"assistant_checkout_disabled"}`
404	`card_order` com um pedido que não é desta sessão.	`{"error":"order_not_found"}`
502	O assistente não conseguiu responder agora.	`{"error":"<texto>"}` ou `{"error":"assistant_unavailable"}`

Ler as mensagens do atendente

GET/api/v1/storefront/wa-coex/intelligence/{token}/inboxPública

Mensagens que um atendente escreveu no chat e se a conversa está com uma pessoa

O chat consulta esta rota de tempos em tempos (polling) para mostrar o que o atendente escreve e saber se a conversa continua com uma pessoa. A resposta nunca é guardada em cache.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

afterintegerpadrão: 0

Cursor: devolve só as mensagens com id maior que ele. Com 0, devolve só o cursor atual (o chat já tem o próprio histórico).

Resposta

200Com mensagens de um atendente

json

{
  "human": true,
  "last_id": 45,
  "messages": [
    { "id": 44, "body": "Oi! Sou a Paula, vou te ajudar com o pedido.", "created_at": "2026-10-11T19:10:00Z", "from": "attendant" }
  ]
}

Campos da resposta

humanboolean

Um atendente está com a conversa (o assistente não responde).

last_idinteger

Cursor para a próxima consulta (after).

messagesarray