Синхронізуйте базу знань

4. Налаштуйте доступ і опублікуйте

Для цього прикладу з приватним центром спершу підключіть вхід для верифікованих клієнтів. Створіть аудиторію та збережіть повернений 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"]}]}}'

Замініть AUDIENCE_ID, ARTICLE_ID і URL входу нижче. Перший запит вмикає довідковий центр і відкриває його лише для клієнтів Pro. Другий публікує статтю. Процес входу у вашому застосунку має передавати довідковому центру підписаний JWT клієнта; одне лише налаштування signInUrl нікого не авторизує.

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

Перевірте вигляд для читача, який увійшов, і для браузера без входу за URL, який повертає GET /help-center. API-ключі та MCP діють від імені співробітників і можуть читати вміст у межах своїх прав; їхня успішна відповідь не доводить, що клієнт бачить статтю.

Для публічного центру задайте audience: "everyone" і audienceId: null для центру та статті, а також перевірте доступ до категорії. Щоб прибрати лише іменовану групу, надішліть audienceId: null; доступ лише для верифікованих клієнтів залишиться, доки ви явно не зміните audience. Якщо audienceId не передано, попереднє призначення зберігається. Читач має відповідати всім обмеженням довідкового центру, категорії та статті.

Іменовані правила використовують match: "all" або "any", до 10 умов і строго типізовані значення. Оператори: eq, neq, in, not_in, exists, not_exists, gt, gte, lt, lte. Числові порівняння приймають числа; in/not_in приймають масиви з 1–100 скалярних значень; для exists/not_exists value не передається. Якщо атрибута немає, порівняння не виконується. Докладніше про поведінку правил, успадкування та проблеми з доступом.

5. Підтримуйте синхронізацію в актуальному стані

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

Той самий процес через MCP

1. Підключіть свій MCP-клієнт і виберіть потрібний робочий простір. Переконайтеся, що він має права kb:read і kb:write та доступ до вашого каналу.
2. Використовуйте ID каналу з панелі керування або викличте list_sources, якщо ваші облікові дані також мають право conversations:read. Ніколи не підставляйте замість нього siteId віджета.
3. Виконайте перші п’ять прикладів нижче по черзі. Замініть SOURCE_ID на ID свого каналу, а ARTICLE_ID/AUDIENCE_ID — на data.id з результату відповідного попереднього кроку. Перед публікацією замініть URL входу та підключіть вхід для клієнтів.
4. Щоб переглянути зміни, використовуйте list_kb_articles. Запускайте впорядкування лише після того, як зберете повний список без фільтрів, разом із чернетками. Після успішних записів оновлюйте свої списки.

Кожен приклад показує назву інструмента та його аргументи. Поля upsert передаються безпосередньо в arguments; інструменти оновлення передають змінені поля всередині updates. Це вхідні дані для виклику інструмента, а не HTTP-запит до 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"
    }
  }
}