API atual/Referência completa/Venddor Intelligence: conversas

Mensagens da conversa

Lista o histórico de uma sessão, envia uma mensagem para a VI (em JSON ou em stream), apaga a partir de uma mensagem e retoma a conversa após um lote.

Cada turno tem duas mensagens: a do administrador e a da VI. Enviar uma mensagem é a única rota da seção que "faz a VI trabalhar": ela consulta dados da loja, monta a resposta e, se for o caso, propõe uma alteração com um bloco de confirmação.

Listar as mensagens

Devolve as mensagens da sessão em ordem cronológica (da mais antiga para a mais nova).

GET/api/v1/admin/intelligence/sessions/{id}/messagesAdmin

Listar as mensagens

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade máxima. Padrão 50, teto 500.

langstring

Idioma dos textos fixos da interface que a plataforma insere nas mensagens (por exemplo pt-BR ou en). Também aceito no cabeçalho X-Venddor-Lang.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/messages?limit=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Mensagens

json

{
  "messages": [
    {
      "id": "a0078ed3-625f-4adf-903c-2253161f817b",
      "session_id": "a0cb371d-96ba-4406-afa1-057ba2594bb6",
      "role": "user",
      "content": "Desative as promoções vencidas",
      "created_at": "2026-09-15T19:55:42.52317Z"
    }
  ],
  "total": 1
}

Campos da resposta

messages[].iduuid

Id da mensagem.

messages[].session_iduuid

Sessão da mensagem.

messages[].rolestring

Autor. Em geral user ou assistant.

messages[].contentstring

Texto em Markdown. Pode conter blocos entre cercas de código (vi:confirm e outros). Ignore os blocos que não conhece.

messages[].metadataobject

Dados de apoio da mensagem (por exemplo, o rastro das consultas feitas no turno). Formato livre: não dependa dele.

messages[].tokens_inputinteger

Tamanho da entrada do turno. Só nas respostas da VI; omitido quando zero.

messages[].tokens_outputinteger

Tamanho da saída do turno. Idem.

messages[].cost_centavosinteger

Custo estimado do turno em centavos de real. Omitido quando zero.

messages[].created_atstring

RFC 3339.

totalinteger

Quantidade devolvida.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
500	O `id` não é um UUID válido (a plataforma responde 500 em vez de 400).	`{"error":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}` (devolvido em português)

Enviar uma mensagem

Envia o texto do administrador e devolve a resposta da VI. A mensagem do administrador e a resposta ficam gravadas na sessão. Com stream: false (padrão) a chamada só volta quando o turno termina; com stream: true a resposta chega como eventos SSE (text/event-stream).

POST/api/v1/admin/intelligence/sessions/{id}/messagesAdmin

Enviar uma mensagem

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

contentstringobrigatório

Texto do administrador.

streambooleanpadrão: false

true para receber SSE.

surfacestring

lateralconversa

De onde o administrador fala: lateral (barra lateral do painel, a VI navega o painel atrás do chat) ou conversa (home e página de chat, a tela abre dentro da própria conversa). Ajusta o texto da resposta.

page_imagestring

Captura da tela atual como data URL (data:image/png;base64,...).

can_capture_pageboolean

Avisa que o cliente consegue enviar uma captura de tela sob demanda. Se a VI precisar dela, o stream termina com o evento need_page e você reenvia a mesma mensagem com page_image.

attachment_imagestring

Imagem anexada a este turno, como data URL devolvida por Anexos.

attachment_textstring

Texto (Markdown) de um documento anexado, como devolvido por Anexos.

attachment_filenamestring

Nome do arquivo anexado, para a VI citar.

voiceboolean

true quando o turno veio de uma conversa por voz; a VI responde mais curto.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Quantos pedidos entraram hoje?",
    "stream": false
  }'

Resposta

200Resposta (stream false)

json

{
  "session_id": "a0cb371d-96ba-4406-afa1-057ba2594bb6",
  "message_id": "91b74361-2426-4ed0-a6f6-10bd133ece8b",
  "user_message_id": "a0078ed3-625f-4adf-903c-2253161f817b",
  "content": "Hoje entraram **12 pedidos**, somando R$ 3.480,00.",
  "prompt_tokens": 5120,
  "output_tokens": 96,
  "cost_centavos": 3
}

200Evento SSE (stream true)

text

event: token
data: {"delta":"Hoje entraram ","chunk":"Hoje entraram "}

event: done
data: {"reply":{"session_id":"...","message_id":"...","content":"Hoje entraram 12 pedidos."}}

Campos da resposta

session_iduuid

Sessão.

message_iduuid

Id da mensagem da VI.

user_message_iduuid

Id da mensagem do administrador.

contentstring

Resposta em Markdown, possivelmente com blocos vi:confirm.

prompt_tokensinteger

Tamanho da entrada do turno.

output_tokensinteger

Tamanho da saída do turno.

cost_centavosinteger

Custo estimado em centavos de real. Ausente quando não há preço declarado.

tool_callsarray

Rastro das consultas e ações do turno (name, args, result, error, elapsed_ms). Informativo, não dependa do conteúdo.

needs_page_captureboolean

true quando a VI pede uma captura de tela (veja can_capture_page).

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	`content` vazio ou corpo que não é JSON.	`{"error":"content required"}` ou `{"error":"invalid request body"}`
403	O recurso de conversa está desligado na loja.	`{"error":"chat widget disabled..."}`
404	Sessão inexistente.	`{"error":"session not found"}`
503	Nenhum provedor de IA configurado na instalação.	`{"error":"no AI provider configured"}`
500	Falha no turno (sem stream). Com stream, o erro vem no evento `error`.	`{"error":"..."}`

Eventos do stream

Cada evento tem a forma event: nome e data: json. Linhas que começam com : são comentários de manutenção da conexão: ignore.

Evento	Quando	Dados
`token`	Cada trecho de texto da resposta	`delta` (e `chunk`, igual)
`tool_call`	A VI começa uma consulta ou ação	`id`, `name`, `args`
`tool_progress`	Andamento de uma consulta longa	`id`, `name`, `label`
`tool_result`	A consulta terminou	`id`, `name`, `result` (reduzido a `ok` se passar de 8000 bytes)
`preamble_done`	Fim da frase de abertura (turnos de voz)	`text`
`lote_settled`	Um lote da conversa terminou	`more`
`need_page`	A VI precisa de `page_image`	`{}`
`done`	Fim do turno	`reply` (objeto da tabela acima)
`error`	O turno falhou	`error` e `message`, em português

Se você só quer o texto, junte os delta dos eventos token e termine em done. Há um comentário : keepalive a cada 15 segundos.

Apagar a partir de uma mensagem

Apaga a mensagem indicada e todas as seguintes da sessão. Serve para editar uma pergunta: apague a partir dela e envie o texto novo, e a VI responde sem o contexto antigo. Um id de mensagem que não existe mais não apaga nada e responde 200.

POST/api/v1/admin/intelligence/sessions/{id}/truncateAdmin

Apagar a partir de uma mensagem

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

from_message_iduuidobrigatório

Primeira mensagem a apagar.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/truncate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_message_id": "a0078ed3-625f-4adf-903c-2253161f817b"
  }'

Resposta

200Apagado

json

{ "ok": true }

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	`from_message_id` ausente.	`{"error":"from_message_id required"}`
500	Falha ao apagar.	`{"error":"could not truncate session"}`

Retomar após um lote

Quando o administrador confirma uma alteração em lote (por exemplo, desativar milhares de promoções), a loja processa em segundo plano e mostra uma barra de progresso. Se o pedido original tinha um complemento ("e depois me diga quantos ficaram acima de R$ 300"), esta rota dispara esse complemento quando o lote termina. Chame-a quando a barra chegar a 100%.

POST/api/v1/admin/intelligence/sessions/{id}/bulk-continuationAdmin

Retomar a conversa após um lote

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

streambooleanpadrão: false

Igual ao campo de mesmo nome de Enviar uma mensagem (acima). O corpo inteiro é opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/bulk-continuation" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": false
  }'

Resposta

200Turno de continuação executado

json

{ "session_id": "...", "message_id": "...", "content": "Ficaram 38 promoções acima de R$ 300." }

204Nada a continuar (ou já reclamado por outro cliente)

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Corpo recusado.	`{"error":"invalid request body"}`

Veja também

API atual/Referência completa/Venddor Intelligence: conversas

Mensagens da conversa

Lista o histórico de uma sessão, envia uma mensagem para a VI (em JSON ou em stream), apaga a partir de uma mensagem e retoma a conversa após um lote.

Listar as mensagens

Devolve as mensagens da sessão em ordem cronológica (da mais antiga para a mais nova).

GET/api/v1/admin/intelligence/sessions/{id}/messagesAdmin

Listar as mensagens

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade máxima. Padrão 50, teto 500.

langstring

Idioma dos textos fixos da interface que a plataforma insere nas mensagens (por exemplo pt-BR ou en). Também aceito no cabeçalho X-Venddor-Lang.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/messages?limit=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Mensagens

json

{
  "messages": [
    {
      "id": "a0078ed3-625f-4adf-903c-2253161f817b",
      "session_id": "a0cb371d-96ba-4406-afa1-057ba2594bb6",
      "role": "user",
      "content": "Desative as promoções vencidas",
      "created_at": "2026-09-15T19:55:42.52317Z"
    }
  ],
  "total": 1
}

Campos da resposta

messages[].iduuid

Id da mensagem.

messages[].session_iduuid

Sessão da mensagem.

messages[].rolestring

Autor. Em geral user ou assistant.

messages[].contentstring

Texto em Markdown. Pode conter blocos entre cercas de código (vi:confirm e outros). Ignore os blocos que não conhece.

messages[].metadataobject

Dados de apoio da mensagem (por exemplo, o rastro das consultas feitas no turno). Formato livre: não dependa dele.

messages[].tokens_inputinteger

Tamanho da entrada do turno. Só nas respostas da VI; omitido quando zero.

messages[].tokens_outputinteger

Tamanho da saída do turno. Idem.

messages[].cost_centavosinteger

Custo estimado do turno em centavos de real. Omitido quando zero.

messages[].created_atstring

RFC 3339.

totalinteger

Quantidade devolvida.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
500	O `id` não é um UUID válido (a plataforma responde 500 em vez de 400).	`{"error":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}` (devolvido em português)

Enviar uma mensagem

POST/api/v1/admin/intelligence/sessions/{id}/messagesAdmin

Enviar uma mensagem

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

contentstringobrigatório

Texto do administrador.

streambooleanpadrão: false

true para receber SSE.

surfacestring

lateralconversa

page_imagestring

Captura da tela atual como data URL (data:image/png;base64,...).

can_capture_pageboolean

Avisa que o cliente consegue enviar uma captura de tela sob demanda. Se a VI precisar dela, o stream termina com o evento need_page e você reenvia a mesma mensagem com page_image.

attachment_imagestring

Imagem anexada a este turno, como data URL devolvida por Anexos.

attachment_textstring

Texto (Markdown) de um documento anexado, como devolvido por Anexos.

attachment_filenamestring

Nome do arquivo anexado, para a VI citar.

voiceboolean

true quando o turno veio de uma conversa por voz; a VI responde mais curto.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Quantos pedidos entraram hoje?",
    "stream": false
  }'

Resposta

200Resposta (stream false)

json

{
  "session_id": "a0cb371d-96ba-4406-afa1-057ba2594bb6",
  "message_id": "91b74361-2426-4ed0-a6f6-10bd133ece8b",
  "user_message_id": "a0078ed3-625f-4adf-903c-2253161f817b",
  "content": "Hoje entraram **12 pedidos**, somando R$ 3.480,00.",
  "prompt_tokens": 5120,
  "output_tokens": 96,
  "cost_centavos": 3
}

200Evento SSE (stream true)

text

event: token
data: {"delta":"Hoje entraram ","chunk":"Hoje entraram "}

event: done
data: {"reply":{"session_id":"...","message_id":"...","content":"Hoje entraram 12 pedidos."}}

Campos da resposta

session_iduuid

Sessão.

message_iduuid

Id da mensagem da VI.

user_message_iduuid

Id da mensagem do administrador.

contentstring

Resposta em Markdown, possivelmente com blocos vi:confirm.

prompt_tokensinteger

Tamanho da entrada do turno.

output_tokensinteger

Tamanho da saída do turno.

cost_centavosinteger

Custo estimado em centavos de real. Ausente quando não há preço declarado.

tool_callsarray

Rastro das consultas e ações do turno (name, args, result, error, elapsed_ms). Informativo, não dependa do conteúdo.

needs_page_captureboolean

true quando a VI pede uma captura de tela (veja can_capture_page).

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	`content` vazio ou corpo que não é JSON.	`{"error":"content required"}` ou `{"error":"invalid request body"}`
403	O recurso de conversa está desligado na loja.	`{"error":"chat widget disabled..."}`
404	Sessão inexistente.	`{"error":"session not found"}`
503	Nenhum provedor de IA configurado na instalação.	`{"error":"no AI provider configured"}`
500	Falha no turno (sem stream). Com stream, o erro vem no evento `error`.	`{"error":"..."}`

Eventos do stream

Cada evento tem a forma event: nome e data: json. Linhas que começam com : são comentários de manutenção da conexão: ignore.

Evento	Quando	Dados
`token`	Cada trecho de texto da resposta	`delta` (e `chunk`, igual)
`tool_call`	A VI começa uma consulta ou ação	`id`, `name`, `args`
`tool_progress`	Andamento de uma consulta longa	`id`, `name`, `label`
`tool_result`	A consulta terminou	`id`, `name`, `result` (reduzido a `ok` se passar de 8000 bytes)
`preamble_done`	Fim da frase de abertura (turnos de voz)	`text`
`lote_settled`	Um lote da conversa terminou	`more`
`need_page`	A VI precisa de `page_image`	`{}`
`done`	Fim do turno	`reply` (objeto da tabela acima)
`error`	O turno falhou	`error` e `message`, em português

Se você só quer o texto, junte os delta dos eventos token e termine em done. Há um comentário : keepalive a cada 15 segundos.

Apagar a partir de uma mensagem

POST/api/v1/admin/intelligence/sessions/{id}/truncateAdmin

Apagar a partir de uma mensagem

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

from_message_iduuidobrigatório

Primeira mensagem a apagar.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/truncate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_message_id": "a0078ed3-625f-4adf-903c-2253161f817b"
  }'

Resposta

200Apagado

json

{ "ok": true }

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	`from_message_id` ausente.	`{"error":"from_message_id required"}`
500	Falha ao apagar.	`{"error":"could not truncate session"}`

Retomar após um lote

POST/api/v1/admin/intelligence/sessions/{id}/bulk-continuationAdmin

Retomar a conversa após um lote

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Corpo da requisição

streambooleanpadrão: false

Igual ao campo de mesmo nome de Enviar uma mensagem (acima). O corpo inteiro é opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/bulk-continuation" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": false
  }'

Resposta

200Turno de continuação executado

json

{ "session_id": "...", "message_id": "...", "content": "Ficaram 38 promoções acima de R$ 300." }

204Nada a continuar (ou já reclamado por outro cliente)

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Corpo recusado.	`{"error":"invalid request body"}`