Wissensdatenbank synchronisieren

4. Zugriff festlegen, dann veröffentlichen

Für dieses Beispiel mit privatem Hilfecenter verbindest du zuerst die Anmeldung verifizierter Kunden. Erstelle die Zielgruppe und speichere die zurückgegebene data.id:

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

Ersetze unten AUDIENCE_ID, ARTICLE_ID und die Login-URL. Die erste Anfrage schaltet das Hilfecenter live und beschränkt es auf Pro-Kunden. Die zweite veröffentlicht den Artikel. Der Login-Ablauf deiner App muss ein signiertes Kunden-JWT mit dem Hilfecenter austauschen; signInUrl allein meldet niemanden an.

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

Teste mit der URL aus GET /help-center die Leseransicht im angemeldeten Zustand und in einem abgemeldeten Browser. API-Schlüssel und MCP handeln als Mitarbeitende und können Inhalte innerhalb ihrer Berechtigungen lesen; eine erfolgreiche Antwort beweist also nicht, dass ein Kunde den Artikel sehen kann.

Für ein öffentliches Hilfecenter verwendest du audience: "everyone" und audienceId: null für Hilfecenter und Artikel – und prüfst auch den Zugriff der Kategorie. Um nur eine benannte Gruppe zu entfernen, sende audienceId: null; der Zugriff nur für verifizierte Kunden bleibt bestehen, solange du audience nicht ausdrücklich änderst. Fehlt audienceId, bleibt die bisherige Zuordnung erhalten. Alle Einschränkungen von Hilfecenter, Kategorie und Artikel müssen zutreffen.

Benannte Regeln nutzen match: "all" oder "any", bis zu 10 Bedingungen und streng typisierte Werte. Operatoren: eq, neq, in, not_in, exists, not_exists, gt, gte, lt, lte. Numerische Vergleiche erwarten Zahlen; in/not_in erwarten Arrays mit 1–100 skalaren Werten; exists/not_exists kommen ohne value aus. Fehlende Merkmale lassen Vergleiche fehlschlagen. Regelverhalten, Vererbung und Fehlerbehebung beim Zugriff.

5. Synchronisierung aktuell halten

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

Derselbe Ablauf über MCP

1. Verbinde deinen MCP-Client und wähle den richtigen Arbeitsbereich. Prüfe, dass er kb:read und kb:write hat und auf deinen Kanal zugreifen darf.
2. Verwende die Kanal-ID aus dem Dashboard oder rufe list_sources auf, wenn deine Zugangsdaten auch conversations:read haben. Verwende nie stattdessen die siteId des Widgets.
3. Führe die ersten fünf Beispiele unten der Reihe nach aus. Ersetze SOURCE_ID durch deine Kanal-ID und ARTICLE_ID/AUDIENCE_ID durch die data.id des jeweils vorherigen Ergebnisses. Ersetze die Login-URL und verbinde die Anmeldung, bevor du veröffentlichst.
4. Prüfe Änderungen mit list_kb_articles. Ordne erst neu, nachdem du die vollständige, ungefilterte Liste inklusive Entwürfen abgerufen hast. Aktualisiere deine Listen nach erfolgreichen Schreibvorgängen.

Jedes Beispiel zeigt den Tool-Namen und seine Argumente. Upsert-Felder stehen direkt in den Argumenten; Update-Tools erwarten geänderte Felder in updates. Das sind Eingaben für Tool-Aufrufe, keine HTTP-Anfragen an den MCP-Endpunkt.

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