Sincroniza tu base de conocimiento

4. Define el acceso y publica

Para este ejemplo de centro privado, conecta primero el inicio de sesión de clientes verificados. Crea la audiencia y guarda el data.id que devuelve:

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

Sustituye AUDIENCE_ID, ARTICLE_ID y la URL de inicio de sesión de abajo. La primera petición publica el centro de ayuda y lo restringe a los clientes Pro. La segunda publica el artículo. El flujo de inicio de sesión de tu aplicación debe intercambiar un JWT de cliente firmado con el centro de ayuda; definir signInUrl por sí solo no inicia la sesión de nadie.

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 la URL que devuelve GET /help-center para probar la vista del lector con sesión iniciada y un navegador sin sesión. Las claves de API y MCP actúan como personal del equipo y pueden leer el contenido dentro de sus permisos; una respuesta correcta no demuestra que un cliente pueda ver el artículo.

Para un centro público, usa audience: "everyone" y audienceId: null en el centro y en el artículo, y revisa también el acceso de la categoría. Para quitar solo un grupo con nombre, envía audienceId: null; el acceso solo para verificados se mantiene salvo que cambies audience explícitamente. Si omites audienceId, se conserva la asignación anterior. Las restricciones del centro de ayuda, la categoría y el artículo deben coincidir.

Las reglas con nombre usan match: "all" o "any", hasta 10 condiciones y valores de tipo estricto. Operadores: eq, neq, in, not_in, exists, not_exists, gt, gte, lt, lte. Las comparaciones numéricas aceptan números; in/not_in aceptan arrays de 1 a 100 valores escalares; exists/not_exists omiten value. Los atributos ausentes no superan las comparaciones. Consulta el comportamiento de las reglas, la herencia y la resolución de problemas de acceso.

5. Mantén la sincronización al día

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 el mismo flujo a través de MCP

1. Conecta tu cliente MCP y elige el espacio de trabajo correcto. Comprueba que tiene kb:read y kb:write, con acceso a tu canal.
2. Usa el ID de canal del panel, o llama a list_sources si tu credencial también tiene conversations:read. Nunca uses en su lugar el siteId del widget.
3. Ejecuta en orden los cinco primeros ejemplos de abajo. Sustituye SOURCE_ID por el ID de tu canal, y ARTICLE_ID/AUDIENCE_ID por el data.id de cada resultado anterior. Sustituye la URL de inicio de sesión y conecta el inicio de sesión antes de publicar.
4. Usa list_kb_articles para revisar los cambios. Ejecuta una reordenación solo después de reunir la lista completa sin filtros, borradores incluidos. Actualiza tus listas tras cada escritura correcta.

Cada ejemplo muestra el nombre de la herramienta y sus argumentos. Los campos de upsert van directamente en los argumentos; las herramientas de actualización ponen los campos cambiados dentro de updates. Son entradas de llamadas a herramientas, no una petición HTTP al 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"
    }
  }
}