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

Entradas da base de conhecimento

Lista, cria, lê, altera e apaga as entradas de perguntas e respostas que o assistente do WhatsApp usa para atender o cliente.

Cada entrada tem um title (o assunto), um content_text (a resposta que o assistente pode usar) e tags opcionais. As rotas só enxergam as entradas do seller do token. Escreva em linguagem natural, como a loja falaria com o cliente: "Trocas: aceitamos em até 7 dias com a nota fiscal".

Listar as entradas

GET/api/v1/vendor/whatsapp/kbSeller

Lista as entradas da base de conhecimento do seller

Parâmetros de consulta

statusstring
activedraftarchived
Filtra por estado. Sem o parâmetro, devolve todos.
searchstring
Busca por trecho do título ou do conteúdo, sem diferenciar maiúsculas.
limitintegerpadrão: 50
Itens por chamada, de 1 a 200. Acima de 200 volta para 50.
offsetintegerpadrão: 0
Quantos itens pular.

Exemplo de requisição

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

Resposta

200Entradas devolvidas
json
{
  "entries": [
    {
      "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "title": "Política de troca",
      "content_text": "Aceitamos trocas em até 7 dias corridos, com a nota fiscal e a etiqueta.",
      "embedding_model": "default",
      "has_embedding": true,
      "tags": ["troca", "devolução"],
      "status": "active",
      "created_at": "2026-10-02T13:00:00Z",
      "updated_at": "2026-10-02T13:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Campos da resposta

entriesarray
Entradas da página.
entries[].iduuid
Id da entrada.
entries[].vendor_iduuid
Seller dono.
entries[].titlestring
Título.
entries[].content_textstring
Conteúdo.
entries[].embedding_modelstring
Identificador do método que gerou o vetor (sem uso na integração). Ausente enquanto não há vetor.
entries[].has_embeddingboolean
true quando a entrada tem vetor e entra na busca por significado.
entries[].tagsarray
Etiquetas. Sempre um array.
entries[].statusstring
activedraftarchived
Estado.
entries[].created_atstring
RFC 3339.
entries[].updated_atstring
RFC 3339.
totalinteger
Total de entradas que atendem ao filtro.
limitinteger
Tamanho de página usado.
offsetinteger
Deslocamento usado.

Erros

StatusQuandoCorpo
401Sem token{"error":"authentication required"}
403Token que não é de seller{"error":"insufficient permissions"}
403Módulo desligado{"error":"module_disabled","module":"whatsapp-commerce"}
403Falta o privilégio{"error":"insufficient vendor privileges","required":"vendor_manage_whatsapp"}
404Usuário sem cadastro de seller{"error":"vendor profile not found","code":"vendor_profile_not_found"}
500Falha ao listar{"error":"Failed to list knowledge base entries: ..."}

Criar uma entrada

POST/api/v1/vendor/whatsapp/kbSeller

Cria uma entrada na base de conhecimento

Devolve 201 com a entrada. Com a IA configurada, o vetor é gerado na hora; sem ela, has_embedding fica false e a entrada só aparece na busca por texto simples.

Corpo da requisição

titlestringobrigatório
Assunto da entrada.
content_textstringobrigatório
Texto da resposta.
tagsarray
Etiquetas livres.
statusstringpadrão: active
activedraftarchived
Estado inicial.
vendor_iduuid
Ignorado para sellers: vale sempre o seller do token.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/kb" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Política de troca",
  "content_text": "Aceitamos trocas em até 7 dias corridos, com a nota fiscal e a etiqueta.",
  "tags": [
    "troca",
    "devolução"
  ]
}'

Resposta

201Entrada criada
json
{
  "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "title": "Política de troca",
  "content_text": "Aceitamos trocas em até 7 dias corridos, com a nota fiscal e a etiqueta.",
  "embedding_model": "default",
  "has_embedding": true,
  "tags": ["troca", "devolução"],
  "status": "active",
  "created_at": "2026-10-02T13:00:00Z",
  "updated_at": "2026-10-02T13:00:00Z"
}

Erros

StatusQuandoCorpo
400JSON inválido{"error":"Invalid JSON body"}
400Falta title{"error":"whatsapp kb: title required"}
400Falta content_text{"error":"whatsapp kb: content_text required"}
400status fora dos três valores{"error":"whatsapp kb: invalid status \"x\""}
401 / 403Autenticação, módulo ou privilégioveja Listar as entradas

Ler uma entrada

GET/api/v1/vendor/whatsapp/kb/{id}Seller

Lê uma entrada da base de conhecimento

Parâmetros de caminho

iduuidobrigatório
Id da entrada.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp/kb/$KB_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entrada
json
{
  "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "title": "Política de troca",
  "content_text": "Aceitamos trocas em até 7 dias corridos, com a nota fiscal e a etiqueta.",
  "has_embedding": true,
  "tags": ["troca", "devolução"],
  "status": "active",
  "created_at": "2026-10-02T13:00:00Z",
  "updated_at": "2026-10-02T13:00:00Z"
}

Os campos são os de um item da listagem.

Erros

StatusQuandoCorpo
401 / 403Autenticação, módulo ou privilégioveja Listar as entradas
404Entrada inexistente, apagada ou de outro seller{"error":"Knowledge base entry not found"}
500Falha ao ler{"error":"Failed to load knowledge base entry: ..."}

Alterar uma entrada

PATCH/api/v1/vendor/whatsapp/kb/{id}Seller

Altera uma entrada da base de conhecimento

Atualização parcial: só os campos enviados mudam. Mudar o content_text regera o vetor (quando a IA está configurada); mudar só o título não. Devolve a entrada atualizada.

Parâmetros de caminho

iduuidobrigatório
Id da entrada.

Corpo da requisição

titlestring
Novo título.
content_textstring
Novo conteúdo.
tagsarray
Nova lista de etiquetas. Substitui a lista inteira; [] apaga todas. Omita para manter.
statusstring
activedraftarchived
Novo estado.

Exemplo de requisição

bash
curl -X PATCH "$BASE_URL/api/v1/vendor/whatsapp/kb/$KB_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "content_text": "Aceitamos trocas em até 10 dias corridos, com a nota fiscal e a etiqueta."
}'

Resposta

200Entrada atualizada
json
{
  "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "title": "Política de troca",
  "content_text": "Aceitamos trocas em até 10 dias corridos, com a nota fiscal e a etiqueta.",
  "has_embedding": true,
  "tags": ["troca", "devolução"],
  "status": "active",
  "created_at": "2026-10-02T13:00:00Z",
  "updated_at": "2026-10-11T15:00:00Z"
}

Erros

StatusQuandoCorpo
400JSON inválido{"error":"Invalid JSON body"}
400status inválido{"error":"whatsapp kb: invalid status \"x\""}
401 / 403Autenticação, módulo ou privilégioveja Listar as entradas
404Entrada inexistente, apagada ou de outro seller{"error":"Knowledge base entry not found"}

Alterar uma entrada (PUT)

PUT/api/v1/vendor/whatsapp/kb/{id}Seller

Altera uma entrada (mesmo comportamento do PATCH)

Atende pelo mesmo tratamento do PATCH: também é parcial, apesar do verbo. Campos ausentes não são apagados. Use o que o seu cliente HTTP preferir.

Parâmetros de caminho

iduuidobrigatório
Id da entrada.

Corpo da requisição

titlestring
Novo título.
content_textstring
Novo conteúdo.
tagsarray
Nova lista de etiquetas, como no PATCH.
statusstring
activedraftarchived
Novo estado.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/whatsapp/kb/$KB_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "archived"
}'

Resposta

200Entrada atualizada
json
{
  "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "title": "Política de troca",
  "content_text": "Aceitamos trocas em até 10 dias corridos, com a nota fiscal e a etiqueta.",
  "has_embedding": true,
  "tags": ["troca", "devolução"],
  "status": "archived",
  "created_at": "2026-10-02T13:00:00Z",
  "updated_at": "2026-10-11T15:05:00Z"
}

Resposta e erros são os do PATCH.

Apagar uma entrada

DELETE/api/v1/vendor/whatsapp/kb/{id}Seller

Apaga uma entrada da base de conhecimento

Exclusão lógica: a entrada sai das listas e da busca.

Parâmetros de caminho

iduuidobrigatório
Id da entrada.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/whatsapp/kb/$KB_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entrada apagada
json
{ "status": "deleted", "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" }

Erros

StatusQuandoCorpo
401 / 403Autenticação, módulo ou privilégioveja Listar as entradas
404Entrada inexistente, já apagada ou de outro seller{"error":"Knowledge base entry not found"}
500Falha ao apagar{"error":"Failed to delete entry: ..."}
Rascunho antes de publicar

Crie com status: "draft" para escrever com calma e mude para active quando estiver pronto. A busca considera só entradas active: uma em rascunho ou arquivada não é usada.

Veja também

  • Busca e vetores
  • Dicionário de marcas
Anterior
Conhecimento do assistente
Próxima
Busca e vetores
Nesta página
  • Listar as entradas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar uma entrada
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ler uma entrada
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar uma entrada
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar uma entrada (PUT)
  • Exemplo de requisição
  • Resposta
  • Apagar uma entrada
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também