Sincronizza la tua base di conoscenza

4. Imposta l'accesso, poi pubblica

Per questo esempio di centro privato, collega prima il sistema di accesso dei clienti verificati. Crea il pubblico e salva il data.id restituito:

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"]}]}}'

Sostituisci AUDIENCE_ID, ARTICLE_ID e l'URL di login qui sotto. La prima richiesta rende il centro assistenza Pubblicato e lo riserva ai clienti Pro. La seconda pubblica l'articolo. Il flusso di login della tua app deve scambiare un JWT firmato del cliente con il centro assistenza; impostare solo signInUrl non fa accedere nessuno.

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"}'

Usa l'URL restituito da GET /help-center per provare la vista del lettore con accesso e un browser senza accesso. Le chiavi API e MCP agiscono come staff e possono leggere i contenuti entro i loro ambiti; una loro risposta positiva non dimostra che un cliente possa vedere l'articolo.

Per un centro pubblico, usa audience: "everyone" e audienceId: null sul centro e sull'articolo, e controlla anche l'accesso della categoria. Per rimuovere solo un gruppo con nome, invia audienceId: null; l'accesso riservato ai verificati resta a meno che tu non cambi esplicitamente audience. Un audienceId omesso mantiene l'assegnazione precedente. Tutte le restrizioni di centro assistenza, categoria e articolo devono essere soddisfatte.

Le regole con nome usano match: "all" o "any", fino a 10 condizioni e valori con tipo rigoroso. Operatori: eq, neq, in, not_in, exists, not_exists, gt, gte, lt, lte. I confronti numerici accettano numeri; in/not_in accettano array da 1 a 100 valori scalari; exists/not_exists omettono value. Gli attributi mancanti non soddisfano i confronti. Vedi comportamento delle regole, ereditarietà e risoluzione dei problemi di accesso.

5. Mantieni aggiornata la sincronizzazione

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"]}'

Usa lo stesso flusso tramite MCP

1. Collega il tuo client MCP e scegli lo spazio di lavoro corretto. Verifica che abbia kb:read e kb:write, con accesso al tuo canale.
2. Usa l'ID del canale della dashboard, oppure chiama list_sources se la tua credenziale ha anche conversations:read. Non usare mai al suo posto il siteId del widget.
3. Esegui in ordine i primi cinque esempi qui sotto. Sostituisci SOURCE_ID con l'ID del tuo canale e ARTICLE_ID/AUDIENCE_ID con il data.id di ciascun risultato precedente. Sostituisci l'URL di login e collega l'accesso prima di pubblicare.
4. Usa list_kb_articles per controllare le modifiche. Esegui un riordino solo dopo aver raccolto l'elenco completo non filtrato, comprese le bozze. Aggiorna i tuoi elenchi dopo le scritture riuscite.

Ogni esempio mostra il nome dello strumento e i suoi argomenti. I campi di upsert vanno direttamente negli argomenti; gli strumenti di aggiornamento mettono i campi modificati dentro updates. Sono input di chiamate agli strumenti, non richieste HTTP all'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"
    }
  }
}