Sincronize sua base de conhecimento

4. Defina o acesso e publique

Para este exemplo de central privada, conecte primeiro o login verificado dos clientes. Crie o público e guarde o data.id retornado:

curl --fail-with-body -X POST "$BASE/audiences" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pro customers","rules":{"match":"all","conditions":[{"trait":"plan","op":"in","value":["pro","business"]}]}}'

Substitua AUDIENCE_ID, ARTICLE_ID e a URL de login abaixo. A primeira requisição coloca a central de ajuda como Publicado e a restringe a clientes Pro. A segunda publica o artigo. O fluxo de login do seu app precisa trocar um JWT assinado do cliente com a central de ajuda; definir signInUrl sozinho não faz o login de ninguém.

curl --fail-with-body -X PATCH "$BASE/help-center" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"title":"Acme Help Center","audience":"verified","audienceId":"AUDIENCE_ID","signInUrl":"https://app.example.com/login"}'

# Replace ARTICLE_ID and AUDIENCE_ID with the returned data.id values.
curl --fail-with-body -X PATCH "$BASE/articles/ARTICLE_ID" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audienceId":"AUDIENCE_ID","status":"published"}'

Use a URL retornada por GET /help-center para testar a visão do leitor conectado e a de um navegador sem login. Chaves de API e MCP atuam como equipe e podem ler o conteúdo dentro dos seus escopos; uma resposta bem-sucedida delas não prova que um cliente consegue ver o artigo.

Para uma central pública, use audience: "everyone" e audienceId: null na central e no artigo, e confira também o acesso da categoria. Para remover apenas um grupo nomeado, envie audienceId: null; o acesso só para verificados continua, a menos que você altere audience explicitamente. Omitir audienceId mantém a atribuição anterior. Todas as restrições da central de ajuda, da categoria e do artigo precisam corresponder.

Regras nomeadas usam match: "all" ou "any", até 10 condições e valores com tipo estrito. Operadores: eq, neq, in, not_in, exists, not_exists, gt, gte, lt, lte. Comparações numéricas recebem números; in/not_in recebem arrays de 1 a 100 valores escalares; exists/not_exists omitem value. Atributos ausentes reprovam nas comparações. Veja o comportamento das regras, a herança e a solução de problemas de acesso.

5. Mantenha a sincronização em dia

curl --fail-with-body --get "$BASE/articles" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  --data-urlencode "page=1" --data-urlencode "limit=100" \
  --data-urlencode "status=published" \
  --data-urlencode "updatedSince=2026-09-01T00:00:00Z"

# Get the full sanitized HTML and read-only analytics for one article.
curl --fail-with-body "$BASE/articles/ARTICLE_ID" \
  -H "Authorization: Bearer $SONNY_API_KEY"

curl --fail-with-body -X POST "$BASE/media" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  -F "file=@billing.png;type=image/png"

curl --fail-with-body -X PUT "$BASE/articles/reorder" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["ARTICLE_ID_1","ARTICLE_ID_2"]}'

Use o mesmo fluxo pelo MCP

1. Conecte seu cliente MCP e escolha o espaço de trabalho correto. Confirme que ele tem kb:read e kb:write, com acesso ao seu canal.
2. Use o ID do canal que aparece no painel ou chame list_sources se a sua credencial também tiver conversations:read. Nunca use o siteId do widget no lugar dele.
3. Execute os cinco primeiros exemplos abaixo, na ordem. Substitua SOURCE_ID pelo ID do seu canal e ARTICLE_ID/AUDIENCE_ID pelo data.id de cada resultado anterior. Substitua a URL de login e conecte o login antes de publicar.
4. Use list_kb_articles para revisar as alterações. Só execute uma reordenação depois de reunir a lista completa e sem filtros, incluindo os rascunhos. Atualize suas listas depois de gravações bem-sucedidas.

Cada exemplo mostra o nome da ferramenta e seus argumentos. Os campos de upsert vão direto nos argumentos; as ferramentas de atualização colocam os campos alterados dentro de updates. Estas são entradas de chamadas de ferramenta, não uma requisição HTTP ao endpoint MCP.

{
  "name": "upsert_kb_category",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "externalId": "billing",
    "name": "Billing",
    "position": 0
  }
}

{
  "name": "upsert_kb_article",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "externalId": "billing-guide",
    "title": "Manage billing",
    "body": "## Find your invoices\n\nOpen **Settings → Billing** in your account.",
    "bodyFormat": "markdown",
    "categoryExternalId": "billing",
    "status": "draft"
  }
}

{
  "name": "create_kb_audience",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "name": "Pro customers",
    "rules": {
      "match": "all",
      "conditions": [
        {
          "trait": "plan",
          "op": "in",
          "value": [
            "pro",
            "business"
          ]
        }
      ]
    }
  }
}

{
  "name": "update_help_center",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "updates": {
      "enabled": true,
      "title": "Acme Help Center",
      "audience": "verified",
      "audienceId": "AUDIENCE_ID",
      "signInUrl": "https://app.example.com/login"
    }
  }
}

{
  "name": "update_kb_article",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "articleId": "ARTICLE_ID",
    "updates": {
      "audience": "verified",
      "audienceId": "AUDIENCE_ID",
      "status": "published"
    }
  }
}

{
  "name": "list_kb_articles",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "page": 1,
    "limit": 100,
    "updatedSince": "2026-09-01T00:00:00Z"
  }
}

{
  "name": "reorder_kb_articles",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "ids": [
      "ARTICLE_ID_1",
      "ARTICLE_ID_2"
    ]
  }
}

{
  "name": "update_kb_audience",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "audienceId": "AUDIENCE_ID",
    "updates": {
      "name": "Paid customers"
    }
  }
}