Zendesk Guide API Content Management: Eine vollständige Entwickleranleitung

Das Verwalten von Help Center-Inhalten in großem Umfang wird mühsam, wenn Sie es manuell tun. Ob Sie Artikel von einer anderen Plattform migrieren, Assets von Ihrem Marketingteam synchronisieren oder Inhalte über mehrere Marken hinweg organisieren, die Zendesk Guide API gibt Ihnen die programmatische Kontrolle über Ihre Wissensdatenbank.

Diese Anleitung führt Sie durch alles, was Sie über das Zendesk Guide API Content Management wissen müssen. Wir behandeln Authentifizierung, Kern-Endpunkte, praktische Implementierungsmuster und wann es sinnvoll ist, die API gegenüber Alternativen wie eesel AI zu verwenden.

Was Sie benötigen

Bevor Sie eintauchen, stellen Sie sicher, dass Sie Folgendes haben:

• Ein Zendesk-Konto mit aktiviertem Guide (Suite Team-Plan oder höher)
• Administratorzugriff zum Generieren von API-Token
• Grundlegende Vertrautheit mit REST-APIs und JSON
• Ihr bevorzugter HTTP-Client (cURL, Postman oder eine Programmiersprache wie Python)

Die Authentifizierung der Zendesk Guide API verstehen

Die Zendesk Guide API verwendet die gleichen Authentifizierungsmuster wie andere Zendesk APIs. Hier ist, was Sie wissen müssen.

API-Token-Authentifizierung (empfohlen)

API-Token sind der einfachste Weg zur Authentifizierung. Sie generieren sie im Admin Center unter Apps und Integrationen > APIs > Zendesk API.

Wichtige Details:

• Formatieren Sie Ihre Anmeldeinformationen als {email_address}/token:{api_token}
• Base64-kodieren Sie die gesamte Zeichenfolge für den Authorization-Header
• Sie können bis zu 256 aktive Token haben (2048 für Legacy-Konten)
• Token können jeden Benutzer imitieren, einschließlich Administratoren, also bewahren Sie sie sicher auf

Beispiel für eine cURL-Anfrage:

curl https://{subdomain}.zendesk.com/api/v2/guide/medias \
  -v -u {email_address}/token:{api_token}

OAuth für Multi-Kunden-Apps

Wenn Sie eine Integration erstellen, die an mehrere Zendesk-Kunden verteilt wird, müssen Sie OAuth anstelle von API-Token verwenden. Reguläre API-Token funktionieren nicht für Apps, die sich über verschiedene Zendesk-Instanzen hinweg authentifizieren müssen.

Ratenbegrenzungen und SSL

Die meisten Endpunkte erlauben 700 Anfragen pro Minute. Wenn Sie das Limit erreichen, erhalten Sie einen 429-Statuscode. Alle Anfragen müssen HTTPS mit TLS 1.2 oder höher verwenden.

Kern-Content-Management-Endpunkte

Die Guide API bietet mehrere Endpunkte für die Verwaltung verschiedener Arten von Inhalten. Lassen Sie uns die nützlichsten aufschlüsseln.

Guide Medias API

Die Guide Medias API verwaltet Datei-Uploads und Medienverwaltung für Ihr Zendesk Help Center. Dies ist unerlässlich, wenn Sie programmgesteuert Bilder oder Anhänge zu Artikeln hinzufügen möchten.

Der 3-stufige Upload-Prozess:

1. Anfordern einer Upload-URL POST an /api/v2/guide/medias/upload_url mit Inhaltstyp und Dateigröße
2. Hochladen der Datei PUT der Datei an die in Schritt 1 zurückgegebene signierte URL
3. Erstellen des Medienobjekts POST an /api/v2/guide/medias mit der Asset-Upload-ID

Dateien können bis zu 20 MB groß sein. Die API verwendet ULID-basierte Kennungen, die im Gegensatz zu herkömmlichen UUIDs sortierbar sind.

Python-Beispiel:

import requests
import base64

auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
headers = {"Authorization": f"Basic {auth}", "Content-Type": "application/json"}

upload_data = {"content_type": "image/png", "file_size": 12345}
response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/guide/medias/upload_url",
    json=upload_data,
    headers=headers
)
upload_url = response.json()["upload_url"]["url"]
asset_id = response.json()["upload_url"]["asset_upload_id"]

media_data = {"asset_upload_id": asset_id, "filename": "screenshot.png"}
media = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/guide/medias",
    json=media_data,
    headers=headers
)

Content Tags API

Content-Tags helfen Ihnen, Artikel und Beiträge zu organisieren. Die Content Tags API ermöglicht es Ihnen, Tags programmgesteuert zu erstellen, zu aktualisieren und zu verwalten.

Hauptfunktionen:

• Erstellen und Verwalten von Tags mit POST/PUT/DELETE-Anfragen
• Batch-Operationen über /api/v2/guide/content_tags/jobs (Tags löschen oder zusammenführen)
• Filtern von Tags nach Namenspräfix
• Sortieren nach ID oder Name in aufsteigender oder absteigender Reihenfolge

Batch-Operationen sind nützlich für Bereinigungsaufgaben, wie das Zusammenführen doppelter Tags oder das Entfernen veralteter Tags in Ihrer gesamten Wissensdatenbank.

Dynamic Content API

Wenn Sie mehrere Sprachen unterstützen, ist die Dynamic Content API unerlässlich. Sie verwaltet lokalisierte Inhaltsvarianten mithilfe von Platzhaltern wie {{dc.password_reset_instructions}}.

Wie es funktioniert:

• Jedes dynamische Inhaltselement hat ein Standardgebietsschema und mehrere Varianten
• Varianten enthalten den tatsächlich übersetzten Text
• Zendesk liefert automatisch die richtige Variante basierend auf dem Gebietsschema des Benutzers
• Fällt auf den Standard zurück, wenn keine übereinstimmende Variante vorhanden ist

Hinweis: Dynamischer Inhalt erfordert einen Professional-Plan oder höher.

External Content Sources API

Die External Content Sources API ermöglicht die föderierte Suche, sodass Sie Ergebnisse aus externen Systemen in Ihre Help Center-Suche ziehen können.

Anwendungsfälle:

• Indizieren von Inhalten aus einem Lernmanagementsystem
• Einbeziehen von Forenbeiträgen in die Suchergebnisse
• Durchsuchbar machen von Jira-Tickets aus dem Help Center

Dies erfordert Help Center-Managerberechtigungen und funktioniert mit dem Crawler von Zendesk, um externe Inhalte zu indizieren.

Praktische Implementierung: Automatisieren von Medien-Uploads

Betrachten wir ein reales Szenario. Ihr Marketingteam erstellt Screenshots in Figma und speichert sie in Google Drive. Sie möchten, dass diese automatisch zu Ihrer Zendesk-Mediengalerie hinzugefügt werden, damit Autoren sie in Artikeln verwenden können.

Hier ist eine vollständige Python-Implementierung:

import requests
import base64
import time

class ZendeskMediaUploader:
    def __init__(self, subdomain, email, token):
        self.subdomain = subdomain
        self.base_url = f"https://{subdomain}.zendesk.com/api/v2"
        self.auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
        self.headers = {
            "Authorization": f"Basic {self.auth}",
            "Content-Type": "application/json"
        }

    def upload_file(self, file_path, content_type):
        """Upload a file to Zendesk media gallery."""
        file_size = os.path.getsize(file_path)
        filename = os.path.basename(file_path)

        # Step 1: Get upload URL
        upload_data = {"content_type": content_type, "file_size": file_size}
        resp = requests.post(
            f"{self.base_url}/guide/medias/upload_url",
            json=upload_data,
            headers=self.headers
        )
        resp.raise_for_status()

        upload_info = resp.json()["upload_url"]

        # Step 2: Upload file to signed URL
        with open(file_path, "rb") as f:
            put_headers = {
                "Content-Disposition": upload_info["headers"]["Content-Disposition"],
                "Content-Type": content_type,
                "X-Amz-Server-Side-Encryption": "AES256"
            }
            put_resp = requests.put(upload_info["url"], data=f, headers=put_headers)
            put_resp.raise_for_status()

        # Step 3: Create media object
        media_data = {
            "asset_upload_id": upload_info["asset_upload_id"],
            "filename": filename
        }
        media_resp = requests.post(
            f"{self.base_url}/guide/medias",
            json=media_data,
            headers=self.headers
        )
        media_resp.raise_for_status()

        return media_resp.json()["media"]

Tipps zur Fehlerbehandlung:

• 401 Unauthorized: Überprüfen Sie Ihr Token und das E-Mail-Format (muss /token enthalten)
• 403 Forbidden: Stellen Sie sicher, dass Sie über Guide-Managerberechtigungen verfügen
• 409 Conflict: Wiederholen Sie die Anfrage (vorübergehender Fehler)
• 429 Rate Limited: Implementieren Sie exponentielles Backoff

Wann die Zendesk Guide API vs. Alternativen verwendet werden soll

Die API ist nicht immer die richtige Wahl. So entscheiden Sie.

Verwenden Sie die API, wenn:

• Sie große Mengen an Inhalten von einer anderen Plattform migrieren müssen
• Sie eine benutzerdefinierte Integration mit Ihren vorhandenen Tools erstellen
• Sie sich wiederholende Aufgaben automatisieren möchten (wie z. B. Massen-Tagging)
• Ihnen Entwicklerressourcen für die laufende Wartung zur Verfügung stehen

Erwägen Sie native Zendesk-Funktionen, wenn:

• Sie nur gelegentliche manuelle Uploads benötigen
• Ihr Team sich mit der Arbeit in der Zendesk-Oberfläche wohlfühlt
• Die föderierte Suche Ihre externen Inhaltsanforderungen ohne Code erfüllt

Erwägen Sie Integrationsplattformen, wenn:

• Sie eine einfache Automatisierung ohne benutzerdefinierten Code benötigen
• Ihr Anwendungsfall zu Standardauslösern und -aktionen passt
• Sie möchten, dass etwas schnell und ohne Entwicklungszeit läuft

Erwägen Sie eesel AI, wenn:

Sie sollten sich eesel AI ansehen, wenn Ihr Ziel darin besteht, Ihre Zendesk-Wissensdatenbank intelligenter zu machen, ohne benutzerdefinierte Integrationen zu erstellen. Anstatt Skripte zu schreiben, um Inhalte zu synchronisieren, verbindet sich eesel direkt mit Zendesk, Confluence, Google Docs und anderen Quellen.

Hier ist der Unterschied: Mit der Guide API können Sie Inhalte programmgesteuert in Zendesk verschieben. eesel AI indiziert Ihre Inhalte dort, wo sie sich befinden, und macht sie Ihrem Support-Team über einen KI-Agenten zugänglich, der in Zendesk funktioniert. Sie migrieren nichts. Sie schreiben keinen Code. Sie verbinden Ihre Quellen und die KI lernt von ihnen.

Für Teams ohne dedizierte Entwickler kann dies ein schnellerer Weg zu einheitlichem Wissen sein. Unsere Preise beginnen bei 299 $/Monat für den Team-Plan, der bis zu 3 Bots und 1.000 KI-Interaktionen beinhaltet.

Best Practices und Fehlerbehebung

Sicherheit

• Speichern Sie API-Token in Umgebungsvariablen, niemals in Ihrem Code
• Rotieren Sie Token regelmäßig (Zendesk erlaubt Ihnen bis zu 256, sodass Sie neue erstellen können, bevor Sie alte löschen)
• Verwenden Sie separate Token für verschiedene Integrationen, damit Sie eines widerrufen können, ohne andere zu beeinträchtigen

Paginierung

Listenendpunkte geben paginierte Ergebnisse zurück. Verwenden Sie die Cursor-basierte Paginierung für große Datensätze (sie ist zuverlässiger als die Offset-Paginierung für sich ändernde Daten):

params = {"page[size]": 100}
while True:
    resp = requests.get(url, params=params, headers=headers)
    data = resp.json()

    # Process records
    for record in data["records"]:
        process(record)

    # Check for more pages
    if not data["meta"]["has_more"]:
        break
    params["page[after]"] = data["meta"]["after_cursor"]

Testen

• Testen Sie in einer Sandbox-Umgebung, bevor Sie sie in der Produktion ausführen
• Verwenden Sie die Postman-Sammlung von Zendesk, um Endpunkte zu erkunden
• Protokollieren Sie API-Antworten während der Entwicklung, um Fehlerbedingungen zu verstehen

Häufige Fehler

• Das /token-Suffix in der E-Mail-Adresse vergessen
• Die Anmeldeinformationen nicht Base64-kodieren
• Ratenbegrenzungen während Massenvorgängen erreichen
• 409-Konflikte nicht mit Wiederholungslogik behandeln

Beginnen Sie mit der effizienteren Verwaltung von Zendesk-Inhalten

Die Zendesk Guide API bietet Ihnen leistungsstarke Tools für das Content Management in großem Umfang. Ob Sie Medien-Uploads automatisieren, Inhalte mit Tags organisieren oder Mehrsprachenunterstützung erstellen, die API bietet die Primitiven, die Sie benötigen.

Aber das Erstellen benutzerdefinierter Integrationen ist nicht der einzige Weg. Wenn Sie Ihre Wissensquellen vereinheitlichen möchten, ohne Code zu schreiben, bietet eesel AI eine Alternative. Unser KI-Agent verbindet sich mit Zendesk und lernt aus Ihrer vorhandenen Dokumentation, wo immer sie sich befindet, ohne dass eine Migration erforderlich ist.

Die richtige Wahl hängt von den technischen Ressourcen und den spezifischen Bedürfnissen Ihres Teams ab. Wenn Sie Entwickler und spezielle Anforderungen haben, ist die Guide API eine solide Grundlage. Wenn Sie schnell mit KI-gestütztem Support loslegen möchten, erkunden Sie, was eesel AI für Ihr Zendesk-Setup tun kann.