VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
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

Resposta

200Escolha aceita

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

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}
404Conversa 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)
400Escolha 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)
409Lista 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"}
502A ação retomada falhou; a lista volta a pending e o clique pode ser repetido.{"error":"não consegui aplicar a ação agora..."}
Limites

O corpo aceita até 256 KB. Os erros dessas rotas chegam em português, ou em inglês quando a requisição pede inglês (Accept-Language).

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

Resposta

200Candidatos

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

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}
404Conversa 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)
400Busca vazia, entidade desconhecida ou corpo ilegível.{"error":"não entendi a busca enviada"} (devolvido em português)
429Já 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

Resposta

200Estado da lista

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

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}
404Conversa 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

  • Mensagens
  • Confirmar ações
Anterior
Confirmar ações da VI
Próxima
Pedido montado na conversa
Nesta página
  • Responder a uma lista
  • Exemplo de requisição
  • Resposta
  • Erros
  • Buscar dentro da lista
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ler o estado da lista
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
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"
    }
  }'
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
  }'
bash
curl "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/selection/$SELECTION_ID" \
  -H "Authorization: Bearer $TOKEN"
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
}
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
}
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"
}