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

Listas de opções

Responde a uma lista de opções que a VI mostrou na conversa, busca dentro dela e consulta o estado.

Quando o pedido é ambíguo ("aumente o preço do mouse" e existem sete mouses), a VI não chuta: mostra uma lista de opções na conversa e espera o clique. Cada lista tem um selection_id e uma ou mais posições (slot), por exemplo "qual produto". Estas três rotas deixam uma interface própria renderizar a lista e devolver a escolha. O ciclo de vida da lista é pending (esperando), answered (respondida) ou expired (venceu).

Responder a uma lista

Envia a escolha do administrador. Depois de aceita, a VI retoma a ação que estava esperando e grava a continuação na conversa. Se a ação for destrutiva, a resposta pede aprovação (requires_approval) em vez de executar.

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

Responder a uma lista de opções

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

selection_idstringobrigatório

Id da lista, vindo no bloco da mensagem.

choicesobject

Escolha única por posição: {"slot": "id-do-registro"}.

multi_choicesobject

Escolha múltipla por posição: {"slot": ["id1", "id2"]}. No máximo 200 ids por envio.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/selection" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "selection_id": "sel_01",
    "choices": {
      "produto": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d"
    }
  }'

Resposta

200Escolha aceita

json

{
  "status": "answered",
  "messages": [
    { "role": "assistant", "content": "Preço do Mouse Gamer atualizado.", "created_at": "2026-10-11T21:10:00Z" }
  ],
  "selection": {
    "selection_id": "sel_01",
    "status": "answered",
    "chosen": { "produto": { "id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d", "label": "Mouse Gamer Titan" } }
  },
  "requires_approval": false
}

Campos da resposta

statusstring

Estado da lista após o envio.

messagesarray

Mensagens novas gravadas na conversa (role, content, created_at, id).

selectionobject

Resumo: selection_id, status, chosen (uma escolha por posição) e chosen_multi.

requires_approvalboolean

true quando falta o "sim" de uma ação destrutiva.

approval_tokenstring

Token para Confirmar ações, quando requires_approval é true.

duplicateboolean

Aparece só no corpo do 409 de uma lista já respondida: true quando result repete a primeira submissão (a ação rodou exatamente uma vez).

continue_in_chatstring

Texto que a interface deve enviar como próxima mensagem para continuar o assunto.

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"]}`
404	Conversa ou lista de opções inexistente (os dois casos são indistinguíveis de propósito).	`{"error":"não encontrei essa lista de opções..."}` (devolvido em português)
400	Escolha incompleta, posição desconhecida, mais de 200 ids, corpo ilegível ou id que não está mais na lista.	`{"error":"escolha incompleta: falta escolher o produto"}` (devolvido em português)
409	Lista já respondida, vencida ou ação recusada por regra de dados (cupom em uso, valor acima do teto, sem permissão).	`{"error":"...","status":"answered"}` (a lista respondida traz também `selection`, o resumo, e `result` com `duplicate: true`, a primeira resposta) ou `{"error":"...","status":"expired"}`
502	A ação retomada falhou; a lista volta a `pending` e o clique pode ser repetido.	`{"error":"não consegui aplicar a ação agora..."}`

Buscar dentro da lista

Quando a lista mostra poucas opções (6 por página), esta rota busca outras dentro da mesma posição, com paginação, ordenação e filtros. Só uma busca por lista pode estar em andamento.

POST/api/v1/admin/intelligence/sessions/{id}/selection/searchAdmin

Buscar dentro de uma lista de opções

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

selection_idstringobrigatório

Id da lista.

slotstringobrigatório

Posição onde buscar.

querystringobrigatório

Texto da busca.

offsetintegerpadrão: 0

Deslocamento para paginar.

limitinteger

Itens por página.

orderstring

Ordenação, quando a posição oferece.

include_inactivebooleanpadrão: false

Inclui registros inativos.

filtersarray

Filtros: objetos {"field", "op", "value", "value2"}. op é um de eq, ne, gt, gte, lt, lte, between, is_null, not_null, zero, contains.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/selection/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "selection_id": "sel_01",
    "slot": "produto",
    "query": "mouse",
    "offset": 6
  }'

Resposta

200Candidatos

json

{
  "slot": "produto",
  "query": "mouse",
  "offset": 6,
  "page_size": 6,
  "candidates": [
    { "id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d", "label": "Mouse Gamer Titan", "sublabel": "SKU MG-01", "score": 0.91 }
  ],
  "total_found": 7
}

Campos da resposta

slotstring

Posição pesquisada.

querystring

Texto da busca.

offsetinteger

Deslocamento usado.

page_sizeinteger

Tamanho da página.

candidatesarray

Opções: id, label, sublabel, thumb, badges, score.

total_foundinteger

Total de resultados da busca.

empty_hintstring

Dica quando não houve resultados.

facetsarray

Filtros sugeridos (key, label, options). Devolva a opção escolhida em filters.

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"]}`
404	Conversa ou lista de opções inexistente (os dois casos são indistinguíveis de propósito).	`{"error":"não encontrei essa lista de opções..."}` (devolvido em português)
400	Busca vazia, entidade desconhecida ou corpo ilegível.	`{"error":"não entendi a busca enviada"}` (devolvido em português)
429	Já há uma busca em andamento nesta lista.	`{"error":"uma busca já está em andamento..."}` (devolvido em português)

Ler o estado da lista

Devolve o estado atual da lista. Use ao reabrir uma conversa para saber se um cartão antigo ainda está esperando resposta (interactive: true) ou já foi respondido.

GET/api/v1/admin/intelligence/sessions/{id}/selection/{selectionId}Admin

Ler o estado de uma lista de opções

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

selectionIdstringobrigatório

Id da lista.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/selection/$SELECTION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estado da lista

json

{
  "selection_id": "sel_01",
  "session_id": "a0cb371d-96ba-4406-afa1-057ba2594bb6",
  "status": "pending",
  "interactive": true,
  "destructive": false,
  "slots": [
    { "key": "produto", "entity": "product", "query": "mouse", "multi": false, "total_found": 7, "page_size": 6, "candidates": [] }
  ],
  "created_at": "2026-10-11T21:09:00Z",
  "expires_at": "2026-10-11T22:09:00Z"
}

Campos da resposta

statusstring

pendingansweredexpired

Estado da lista.

interactiveboolean

true só quando status é pending. Só então candidates vem preenchido.

destructiveboolean

A ação que vai retomar é destrutiva.

action_labelstring

Nome da ação em espera.

slotsarray

Posições: key, entity, label, query, multi, total_found, page_size, candidates, chosen.

chosenobject

Escolhas já feitas, por posição.

created_atstring

RFC 3339.

expires_atstring

RFC 3339. Depois disso a lista deixa de aceitar resposta.

answered_atstring

RFC 3339. Só em listas respondidas.

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"]}`
404	Conversa ou lista de opções inexistente (os dois casos são indistinguíveis de propósito).	`{"error":"não encontrei essa lista de opções..."}` (devolvido em português)

Veja também

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

Listas de opções

Responde a uma lista de opções que a VI mostrou na conversa, busca dentro dela e consulta o estado.

Responder a uma lista

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

Responder a uma lista de opções

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

selection_idstringobrigatório

Id da lista, vindo no bloco da mensagem.

choicesobject

Escolha única por posição: {"slot": "id-do-registro"}.

multi_choicesobject

Escolha múltipla por posição: {"slot": ["id1", "id2"]}. No máximo 200 ids por envio.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/selection" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "selection_id": "sel_01",
    "choices": {
      "produto": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d"
    }
  }'

Resposta

200Escolha aceita

json

{
  "status": "answered",
  "messages": [
    { "role": "assistant", "content": "Preço do Mouse Gamer atualizado.", "created_at": "2026-10-11T21:10:00Z" }
  ],
  "selection": {
    "selection_id": "sel_01",
    "status": "answered",
    "chosen": { "produto": { "id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d", "label": "Mouse Gamer Titan" } }
  },
  "requires_approval": false
}

Campos da resposta

statusstring

Estado da lista após o envio.

messagesarray

Mensagens novas gravadas na conversa (role, content, created_at, id).

selectionobject

Resumo: selection_id, status, chosen (uma escolha por posição) e chosen_multi.

requires_approvalboolean

true quando falta o "sim" de uma ação destrutiva.

approval_tokenstring

Token para Confirmar ações, quando requires_approval é true.

duplicateboolean

Aparece só no corpo do 409 de uma lista já respondida: true quando result repete a primeira submissão (a ação rodou exatamente uma vez).

continue_in_chatstring

Texto que a interface deve enviar como próxima mensagem para continuar o assunto.

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"]}`
404	Conversa ou lista de opções inexistente (os dois casos são indistinguíveis de propósito).	`{"error":"não encontrei essa lista de opções..."}` (devolvido em português)
400	Escolha incompleta, posição desconhecida, mais de 200 ids, corpo ilegível ou id que não está mais na lista.	`{"error":"escolha incompleta: falta escolher o produto"}` (devolvido em português)
409	Lista já respondida, vencida ou ação recusada por regra de dados (cupom em uso, valor acima do teto, sem permissão).	`{"error":"...","status":"answered"}` (a lista respondida traz também `selection`, o resumo, e `result` com `duplicate: true`, a primeira resposta) ou `{"error":"...","status":"expired"}`
502	A ação retomada falhou; a lista volta a `pending` e o clique pode ser repetido.	`{"error":"não consegui aplicar a ação agora..."}`

Buscar dentro da lista

Quando a lista mostra poucas opções (6 por página), esta rota busca outras dentro da mesma posição, com paginação, ordenação e filtros. Só uma busca por lista pode estar em andamento.

POST/api/v1/admin/intelligence/sessions/{id}/selection/searchAdmin

Buscar dentro de uma lista de opções

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

selection_idstringobrigatório

Id da lista.

slotstringobrigatório

Posição onde buscar.

querystringobrigatório

Texto da busca.

offsetintegerpadrão: 0

Deslocamento para paginar.

limitinteger

Itens por página.

orderstring

Ordenação, quando a posição oferece.

include_inactivebooleanpadrão: false

Inclui registros inativos.

filtersarray

Filtros: objetos {"field", "op", "value", "value2"}. op é um de eq, ne, gt, gte, lt, lte, between, is_null, not_null, zero, contains.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/selection/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "selection_id": "sel_01",
    "slot": "produto",
    "query": "mouse",
    "offset": 6
  }'

Resposta

200Candidatos

json

{
  "slot": "produto",
  "query": "mouse",
  "offset": 6,
  "page_size": 6,
  "candidates": [
    { "id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d", "label": "Mouse Gamer Titan", "sublabel": "SKU MG-01", "score": 0.91 }
  ],
  "total_found": 7
}

Campos da resposta

slotstring

Posição pesquisada.

querystring

Texto da busca.

offsetinteger

Deslocamento usado.

page_sizeinteger

Tamanho da página.

candidatesarray

Opções: id, label, sublabel, thumb, badges, score.

total_foundinteger

Total de resultados da busca.

empty_hintstring

Dica quando não houve resultados.

facetsarray

Filtros sugeridos (key, label, options). Devolva a opção escolhida em filters.

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"]}`
404	Conversa ou lista de opções inexistente (os dois casos são indistinguíveis de propósito).	`{"error":"não encontrei essa lista de opções..."}` (devolvido em português)
400	Busca vazia, entidade desconhecida ou corpo ilegível.	`{"error":"não entendi a busca enviada"}` (devolvido em português)
429	Já há uma busca em andamento nesta lista.	`{"error":"uma busca já está em andamento..."}` (devolvido em português)

Ler o estado da lista

Devolve o estado atual da lista. Use ao reabrir uma conversa para saber se um cartão antigo ainda está esperando resposta (interactive: true) ou já foi respondido.

GET/api/v1/admin/intelligence/sessions/{id}/selection/{selectionId}Admin

Ler o estado de uma lista de opções

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

selectionIdstringobrigatório

Id da lista.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/selection/$SELECTION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estado da lista

json

{
  "selection_id": "sel_01",
  "session_id": "a0cb371d-96ba-4406-afa1-057ba2594bb6",
  "status": "pending",
  "interactive": true,
  "destructive": false,
  "slots": [
    { "key": "produto", "entity": "product", "query": "mouse", "multi": false, "total_found": 7, "page_size": 6, "candidates": [] }
  ],
  "created_at": "2026-10-11T21:09:00Z",
  "expires_at": "2026-10-11T22:09:00Z"
}

Campos da resposta

statusstring

pendingansweredexpired

Estado da lista.

interactiveboolean

true só quando status é pending. Só então candidates vem preenchido.

destructiveboolean

A ação que vai retomar é destrutiva.

action_labelstring

Nome da ação em espera.

slotsarray

Posições: key, entity, label, query, multi, total_found, page_size, candidates, chosen.

chosenobject

Escolhas já feitas, por posição.

created_atstring

RFC 3339.

expires_atstring

RFC 3339. Depois disso a lista deixa de aceitar resposta.

answered_atstring

RFC 3339. Só em listas respondidas.

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"]}`
404	Conversa ou lista de opções inexistente (os dois casos são indistinguíveis de propósito).	`{"error":"não encontrei essa lista de opções..."}` (devolvido em português)