Enviar sugestões de conteúdo pela API

Se o conteúdo do seu negócio nasce fora da plataforma — uma rotina que lê os atendimentos de outra ferramenta, um script que acompanha a sua documentação, um parceiro que cuida do conteúdo —, esse sistema pode depositar sugestões aqui pela API. Elas entram na mesma caixa de sugestões, e uma pessoa da sua equipe lê e aprova. Nada é publicado automaticamente.

Antes de começar: a chave

Crie uma chave em Administração → Integrações → API, com os escopos do destino que a rotina vai usar:

  • Gerenciar agentes, para sugerir conteúdo para o agente;
  • Gerenciar base de conhecimento, para sugerir artigos para a sua Central.

Se a chave não alcançar o destino pedido, a resposta é 403 dizendo qual escopo falta — em vez de falhar em silêncio.

Enviar uma sugestão

Um POST para /api/v1/suggestions, com o cabeçalho Authorization: Bearer SUA-CHAVE. O corpo em JSON:

  • title (obrigatório): o assunto, como a pessoa vai ler no cartão.
  • body: o conteúdo já escrito. Sem ele, o cartão chega só com o assunto e alguém escreve.
  • format: html (padrão) ou text.
  • target: onde a sugestão quer entrar — knowledge (conhecimento do agente), kb_article (artigo da Central) ou os dois. Omitido, vale conhecimento do agente. Quem aprova pode mudar.
  • score: de 0 a 100, o impacto que você atribui. Ordena a fila e vira o selo de prioridade.
  • external_source e external_id: a identificação da sua rotina e a chave daquele achado.
  • evidence: o porquê. O campo note vira a explicação no cartão, e refs vira a lista de casos que sustentam a sugestão.
  • review_ids: os ids das respostas marcadas como erradas pela equipe que esta sugestão corrige (veja a seção abaixo). Aprovar o cartão fecha essas marcações como corrigidas. Id que não existe, já fechado ou de outra conta devolve 422.

Corrigir a partir das respostas marcadas pela equipe

Quando alguém da equipe marca uma resposta do agente como errada na conversa, a marcação fica disponível pela API — e é o melhor ponto de partida para quem escreve conteúdo de fora, porque já diz o que o cliente perguntou, o que o agente respondeu e o que estava errado.

  • GET /api/v1/ai-answer-reviews lista as marcações. Por padrão vêm as abertas com 👎, mais recentes primeiro; filtre por agent_id, reason, status (open, fixed, dismissed ou all), ticket_id e período (created_from, created_to).
  • Cada item traz question (a pergunta do cliente), answer (a resposta dada), reason e reason_label, note, expected_answer (o que a equipe disse que deveria ter sido respondido), actions_called (as integrações que o agente consultou naquela resposta) e o link da conversa em ticket.url.
  • Escreva o conteúdo certo e deposite com POST /suggestions, informando review_ids. Alguém aprova na caixa, e a marcação fecha sozinha.
  • Gravou direto nos recursos de conhecimento, sem passar pela caixa? Feche a marcação com PATCH /api/v1/ai-answer-reviews/{id}, corpo {"status": "fixed", "resolution_note": "..."}.

Pelo MCP, essas mesmas chamadas viram ferramentas do seu assistente de IA. Um uso que funciona bem: rodar o assistente dentro do repositório do seu sistema e pedir algo como "liste as respostas marcadas como erradas, descubra no código como cada funcionalidade realmente funciona e deposite um conteúdo curto para cada uma como sugestão, com o review_id". A chave precisa alcançar leitura de agentes de IA e o destino da sugestão.

Mandar de novo não duplica

A dupla external_source + external_id é a impressão digital do achado. Reenviar a mesma dupla:

  • atualiza a sugestão que ainda está esperando decisão (texto novo, evidência mais recente) e responde 200;
  • responde 200 com "ignored": true se aquele assunto já foi descartado — descartar é definitivo, e a sua rotina fica sabendo em vez de insistir todo dia;
  • responde 201 quando é a primeira vez.

Use um external_id estável (por exemplo, a data da rodada mais o número do assunto). Sem ele, a plataforma usa o título como chave.

Descobrir os destinos

Um GET em /api/v1/suggestions/targets devolve os destinos disponíveis para aquela chave e o que cada um aceita — é por aí que a sua rotina descobre o que existe, sem adivinhar nomes. E GET /api/v1/suggestions lê a fila.

Uma nota sobre segurança

Conteúdo que chega de fora é tratado como não confiável: a formatação é limpa na entrada, o texto aparece inteiro para quem decide, e só entra na base depois da aprovação de uma pessoa. Toda aprovação fica registrada em Auditoria.