Synchroniser votre base de connaissances

4. Définir l'accès, puis publier

Pour cet exemple de centre privé, connectez d'abord la connexion des clients vérifiés. Créez l'audience et conservez le data.id renvoyé :

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

Remplacez AUDIENCE_ID, ARTICLE_ID et l'URL de connexion ci-dessous. La première requête met le centre d'aide en ligne et le réserve aux clients Pro. La seconde publie l'article. Le processus de connexion de votre application doit échanger un JWT client signé avec le centre d'aide ; définir signInUrl seul ne connecte personne.

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

Utilisez l'URL renvoyée par GET /help-center pour tester la vue lecteur connecté et un navigateur déconnecté. Les clés API et MCP agissent en tant que membres de l'équipe et peuvent lire le contenu dans les limites de leurs portées ; une réponse réussie ne prouve pas qu'un client peut voir l'article.

Pour un centre public, utilisez audience: "everyone" et audienceId: null sur le centre et l'article, et vérifiez aussi l'accès de la catégorie. Pour retirer uniquement un groupe nommé, envoyez audienceId: null ; l'accès réservé aux clients vérifiés reste en place, sauf si vous modifiez explicitement audience. Un audienceId omis conserve l'attribution précédente. Toutes les restrictions du centre d'aide, de la catégorie et de l'article doivent correspondre.

Les règles nommées utilisent match: "all" ou "any", jusqu'à 10 conditions et des valeurs strictement typées. Opérateurs : eq, neq, in, not_in, exists, not_exists, gt, gte, lt, lte. Les comparaisons numériques prennent des nombres ; in/not_in prennent des tableaux de 1 à 100 valeurs scalaires ; exists/not_exists omettent value. Les attributs manquants font échouer les comparaisons. Voir le comportement des règles, l'héritage et le dépannage des accès.

5. Garder la synchronisation à jour

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

Utiliser le même processus via MCP

1. Connectez votre client MCP et choisissez le bon espace de travail. Vérifiez qu'il dispose de kb:read et kb:write, avec l'accès à votre canal.
2. Utilisez l'identifiant de canal du tableau de bord, ou appelez list_sources si votre identifiant dispose aussi de conversations:read. Ne le remplacez jamais par le siteId du widget.
3. Exécutez dans l'ordre les cinq premiers exemples ci-dessous. Remplacez SOURCE_ID par l'identifiant de votre canal, et ARTICLE_ID/AUDIENCE_ID par le data.id de chaque résultat précédent. Remplacez l'URL de connexion et connectez la connexion client avant de publier.
4. Utilisez list_kb_articles pour vérifier les changements. Ne lancez une réorganisation qu'après avoir récupéré la liste complète non filtrée, brouillons compris. Actualisez vos listes après chaque écriture réussie.

Chaque exemple montre le nom de l'outil et ses arguments. Les champs d'upsert vont directement dans les arguments ; les outils de mise à jour placent les champs modifiés dans updates. Il s'agit d'entrées d'appel d'outil, pas d'une requête HTTP vers le point de terminaison 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"
    }
  }
}