VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: conhecimento do assistente

Entradas da base

Cria, lista, lê, altera e apaga os textos da base de conhecimento que o assistente de WhatsApp consulta.

A base de conhecimento é um conjunto de textos curtos (políticas, horários, respostas a dúvidas frequentes). O assistente de WhatsApp os consulta antes de responder o cliente. Estas rotas fazem o cadastro dessas entradas.

Listar entradas

Devolve as entradas da base, com filtros e paginação.

GET/api/v1/admin/whatsapp/kbAdmin

Lista as entradas da base de conhecimento

Parâmetros de consulta

vendor_iduuid
Filtra por seller.
statusstring
activedraftarchivedARD
Filtra por estado. Aceita palavra ou letra. Um valor desconhecido é tratado como active.
searchstring
Trecho a procurar no título e no texto.
limitintegerpadrão: 50
Itens por página. Valores menores que 1 ou maiores que 200 voltam para 50 (e a resposta ecoa o valor que você enviou).
offsetintegerpadrão: 0
Quantos itens pular.

Exemplo de requisição (Listar entradas)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/kb?status=active&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar entradas)

200Entradas devolvidas
json
{
  "entries": [
    {
      "id": "6e1b7a54-0c3d-4f29-b8a6-2d9c5e4f1a07",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "title": "Política de troca",
      "content_text": "Aceitamos troca em até 7 dias corridos após o recebimento, com a etiqueta original e sem sinais de uso.",
      "embedding_model": "text-embedding-3-small",
      "has_embedding": true,
      "tags": [
        "troca",
        "pós-venda"
      ],
      "status": "A",
      "created_at": "2026-10-11T14:02:10.114233Z",
      "updated_at": "2026-10-11T14:02:10.114233Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Campos da resposta

entriesarray

Entradas da página.

iduuid
Identificador da entrada.
vendor_iduuid
Seller dono da entrada. Ausente quando a entrada vale para a loja toda.
titlestring
Título curto.
content_textstring
Texto da resposta que o assistente pode usar.
embedding_modelstring
Modelo que gerou o índice de busca por significado. Ausente quando não há índice.
has_embeddingboolean
true quando a entrada já tem índice de busca por significado.
tagsarray
Etiquetas de texto livre. Lista vazia quando não há.
statusstring
ARD
Estado da entrada. Volta como letra: A (ativa), R (rascunho) ou D (arquivada). Na entrada você pode enviar a palavra ou a letra.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).
totalinteger
Total que casa com os filtros.
limitinteger
Limite pedido (veja o aviso sobre o teto de 200).
offsetinteger
Deslocamento pedido.

Erros (Listar entradas)

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.{"error":"Failed to list knowledge base entries: ..."}
Entrada de seller ou da loja

Uma entrada sem vendor_id vale para a loja toda e é usada pelo assistente de qualquer seller. Uma entrada com vendor_id só vale para aquele seller. A listagem sem vendor_id mostra as duas.

Criar uma entrada

Cadastra um texto que o assistente pode usar para responder perguntas dos clientes (política de troca, horário, formas de pagamento). A plataforma tenta gerar o índice de busca por significado na hora; se não conseguir, a entrada é criada mesmo assim.

POST/api/v1/admin/whatsapp/kbAdmin

Cria uma entrada na base de conhecimento

Corpo da requisição

titlestringobrigatório
Título. Obrigatório, não pode ser vazio.
content_textstringobrigatório
Texto da resposta. Obrigatório, não pode ser vazio.
vendor_iduuid
Seller dono da entrada. Omitido, a entrada vale para a loja toda.
tagsarray
Lista de etiquetas de texto.
statusstringpadrão: active
activedraftarchivedARD
Estado inicial.

Exemplo de requisição (Criar uma entrada)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/kb" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Política de troca",
    "content_text": "Aceitamos troca em até 7 dias corridos após o recebimento, com a etiqueta original e sem sinais de uso.",
    "tags": [
      "troca",
      "pós-venda"
    ]
  }'

Resposta (Criar uma entrada)

201Entrada criada
json
{
  "id": "6e1b7a54-0c3d-4f29-b8a6-2d9c5e4f1a07",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "title": "Política de troca",
  "content_text": "Aceitamos troca em até 7 dias corridos após o recebimento, com a etiqueta original e sem sinais de uso.",
  "embedding_model": "text-embedding-3-small",
  "has_embedding": true,
  "tags": [
    "troca",
    "pós-venda"
  ],
  "status": "A",
  "created_at": "2026-10-11T14:02:10.114233Z",
  "updated_at": "2026-10-11T14:02:10.114233Z"
}

Campos da resposta

iduuid
Identificador da entrada.
vendor_iduuid
Seller dono da entrada. Ausente quando a entrada vale para a loja toda.
titlestring
Título curto.
content_textstring
Texto da resposta que o assistente pode usar.
embedding_modelstring
Modelo que gerou o índice de busca por significado. Ausente quando não há índice.
has_embeddingboolean
true quando a entrada já tem índice de busca por significado.
tagsarray
Etiquetas de texto livre. Lista vazia quando não há.
statusstring
ARD
Estado da entrada. Volta como letra: A (ativa), R (rascunho) ou D (arquivada). Na entrada você pode enviar a palavra ou a letra.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Criar uma entrada)

StatusQuandoCorpo
400Corpo que não é JSON, título ou texto vazio, ou estado inválido.{"error":"whatsapp kb: title required"} ou {"error":"whatsapp kb: content_text required"} ou {"error":"whatsapp kb: invalid status \"x\""}
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"}
Só entradas ativas respondem

A busca do assistente ignora rascunhos (draft) e arquivadas (archived). Crie como rascunho enquanto revisa o texto e ative depois com PATCH.

Ver uma entrada

Devolve uma entrada pelo id.

GET/api/v1/admin/whatsapp/kb/{id}Admin

Lê uma entrada da base de conhecimento

Parâmetros de caminho

iduuidobrigatório
Id da entrada.

Exemplo de requisição (Ver uma entrada)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/kb/6e1b7a54-0c3d-4f29-b8a6-2d9c5e4f1a07" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Ver uma entrada)

200Entrada devolvida
json
{
  "id": "6e1b7a54-0c3d-4f29-b8a6-2d9c5e4f1a07",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "title": "Política de troca",
  "content_text": "Aceitamos troca em até 7 dias corridos após o recebimento, com a etiqueta original e sem sinais de uso.",
  "embedding_model": "text-embedding-3-small",
  "has_embedding": true,
  "tags": [
    "troca",
    "pós-venda"
  ],
  "status": "A",
  "created_at": "2026-10-11T14:02:10.114233Z",
  "updated_at": "2026-10-11T14:02:10.114233Z"
}

Campos da resposta

iduuid
Identificador da entrada.
vendor_iduuid
Seller dono da entrada. Ausente quando a entrada vale para a loja toda.
titlestring
Título curto.
content_textstring
Texto da resposta que o assistente pode usar.
embedding_modelstring
Modelo que gerou o índice de busca por significado. Ausente quando não há índice.
has_embeddingboolean
true quando a entrada já tem índice de busca por significado.
tagsarray
Etiquetas de texto livre. Lista vazia quando não há.
statusstring
ARD
Estado da entrada. Volta como letra: A (ativa), R (rascunho) ou D (arquivada). Na entrada você pode enviar a palavra ou a letra.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Ver uma entrada)

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"}
404Entrada não encontrada.{"error":"Knowledge base entry not found"}
500O id não é um UUID válido (a plataforma devolve 500 em vez de 400).{"error":"Failed to load knowledge base entry: whatsapp kb: get: pq: invalid input syntax for type uuid: \"xyz\" (22P02)"}

Alterar uma entrada

Altera só os campos enviados. Quando o content_text muda, o índice de busca por significado é refeito.

PATCH/api/v1/admin/whatsapp/kb/{id}Admin

Altera uma entrada da base de conhecimento

Parâmetros de caminho

iduuidobrigatório
Id da entrada.

Corpo da requisição

titlestring
Novo título.
content_textstring
Novo texto.
tagsarray
Novas etiquetas, que substituem todas as atuais. Envie [] para limpar. Omita para manter.
statusstring
activedraftarchivedARD
Novo estado.

Exemplo de requisição (Alterar uma entrada)

bash
curl -X PATCH "$BASE_URL/api/v1/admin/whatsapp/kb/6e1b7a54-0c3d-4f29-b8a6-2d9c5e4f1a07" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "draft",
    "tags": [
      "troca",
      "pós-venda"
    ]
  }'

Resposta (Alterar uma entrada)

200Entrada atualizada
json
{
  "id": "6e1b7a54-0c3d-4f29-b8a6-2d9c5e4f1a07",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "title": "Política de troca",
  "content_text": "Aceitamos troca em até 7 dias corridos após o recebimento, com a etiqueta original e sem sinais de uso.",
  "embedding_model": "text-embedding-3-small",
  "has_embedding": true,
  "tags": [
    "troca",
    "pós-venda"
  ],
  "status": "R",
  "created_at": "2026-10-11T14:02:10.114233Z",
  "updated_at": "2026-10-11T14:02:10.114233Z"
}

Campos da resposta

iduuid
Identificador da entrada.
vendor_iduuid
Seller dono da entrada. Ausente quando a entrada vale para a loja toda.
titlestring
Título curto.
content_textstring
Texto da resposta que o assistente pode usar.
embedding_modelstring
Modelo que gerou o índice de busca por significado. Ausente quando não há índice.
has_embeddingboolean
true quando a entrada já tem índice de busca por significado.
tagsarray
Etiquetas de texto livre. Lista vazia quando não há.
statusstring
ARD
Estado da entrada. Volta como letra: A (ativa), R (rascunho) ou D (arquivada). Na entrada você pode enviar a palavra ou a letra.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Alterar uma entrada)

StatusQuandoCorpo
400Corpo que não é JSON ou estado inválido.{"error":"Invalid JSON body"} ou {"error":"whatsapp kb: invalid status \"x\""}
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"}
404Entrada não encontrada.{"error":"Knowledge base entry not found"}
500O id não é um UUID válido (a plataforma devolve 500 em vez de 400).{"error":"Failed to load knowledge base entry: whatsapp kb: get: pq: invalid input syntax for type uuid: \"xyz\" (22P02)"}
Vale PATCH, não PUT

O código do manipulador cita PUT, mas a rota registrada no servidor é PATCH.

Apagar uma entrada

Apaga a entrada: ela some das listagens e da busca. É uma remoção lógica, o registro não é destruído.

DELETE/api/v1/admin/whatsapp/kb/{id}Admin

Apaga uma entrada da base de conhecimento

Parâmetros de caminho

iduuidobrigatório
Id da entrada.

Exemplo de requisição (Apagar uma entrada)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/whatsapp/kb/6e1b7a54-0c3d-4f29-b8a6-2d9c5e4f1a07" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar uma entrada)

200Entrada apagada
json
{
  "status": "deleted",
  "id": "6e1b7a54-0c3d-4f29-b8a6-2d9c5e4f1a07"
}

Campos da resposta

statusstring
deleted
Sempre deleted.
iduuid
O id apagado.

Erros (Apagar uma entrada)

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"}
404Entrada não encontrada.{"error":"Knowledge base entry not found"}
500O id não é um UUID válido, ou falha ao apagar.{"error":"Failed to delete entry: ..."}
Não há como desfazer pela API

Nenhuma rota restaura uma entrada apagada. Se quiser só tirar do ar, mude o estado para archived com PATCH.

Veja também

  • Busca e índice
  • Visão geral
Anterior
WhatsApp: conhecimento do assistente
Próxima
Busca e índice da base
Nesta página
  • Listar entradas
  • Exemplo de requisição (Listar entradas)
  • Resposta (Listar entradas)
  • Erros (Listar entradas)
  • Criar uma entrada
  • Exemplo de requisição (Criar uma entrada)
  • Resposta (Criar uma entrada)
  • Erros (Criar uma entrada)
  • Ver uma entrada
  • Exemplo de requisição (Ver uma entrada)
  • Resposta (Ver uma entrada)
  • Erros (Ver uma entrada)
  • Alterar uma entrada
  • Exemplo de requisição (Alterar uma entrada)
  • Resposta (Alterar uma entrada)
  • Erros (Alterar uma entrada)
  • Apagar uma entrada
  • Exemplo de requisição (Apagar uma entrada)
  • Resposta (Apagar uma entrada)
  • Erros (Apagar uma entrada)
  • Veja também