Zendesk Requests API: Eine vollständige Anleitung für Endbenutzer (2026)

Wenn Sie ein Kundenportal oder eine Self-Service-Integration erstellen, benötigen Sie eine Möglichkeit für Endbenutzer, Tickets zu erstellen und anzuzeigen, ohne ihnen vollen Administratorzugriff zu gewähren. Die Zendesk Requests API ist genau für diesen Zweck konzipiert.

Die Requests API bietet eine Endbenutzerperspektive auf Tickets. Benutzer können Anfragen erstellen, ihren Ticketverlauf einsehen und Kommentare hinzufügen, während sie nur öffentliche Informationen sehen. Sie ist die sichere Alternative mit eingeschränktem Zugriff zur vollständigen Tickets API.

Wenn Sie den Support automatisieren möchten, ohne benutzerdefinierte API-Integrationen zu erstellen, können Tools wie eesel AI das gesamte Spektrum der Supportautomatisierung abdecken, vom Ticket-Routing bis hin zu KI-gestützten Antworten. eesel integriert sich direkt in Zendesk und lernt aus Ihren bestehenden Tickets und Ihrer Dokumentation. Wenn Sie jedoch direkten API-Zugriff für benutzerdefinierte Integrationen benötigen, führt Sie diese Anleitung durch alles, was Sie wissen müssen.

Was Sie benötigen

Bevor Sie mit dem Absetzen von API-Aufrufen beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Ein Zendesk-Konto mit den entsprechenden Berechtigungen (Administratorzugriff zum Einrichten von API-Token)
• API-Token oder OAuth-Anmeldeinformationen (wir werden behandeln, wie diese generiert werden)
• Grundlegende Vertrautheit mit REST-APIs (Sie sollten GET-, POST- und PUT-Anfragen verstehen)
• Eine Entwicklungsumgebung (cURL, Python oder Node.js funktionieren gut)

Die Requests API verstehen

Was ist eine Anfrage?

In Zendesk ist eine Anfrage die Perspektive eines Endbenutzers auf ein Ticket. Während Agenten das vollständige Ticket mit internen Notizen, benutzerdefinierten Feldern und privaten Kommentaren sehen, sehen Endbenutzer nur öffentliche Kommentare und eine begrenzte Anzahl von Feldern.

So sieht das JSON-Format für eine Anfrage aus:

{
  "id": 35436,
  "subject": "Hilfe, mein Drucker brennt!",
  "description": "Das Feuer ist sehr farbenfroh.",
  "status": "open",
  "priority": "normal",
  "type": "problem",
  "requester_id": 1462,
  "created_at": "2009-07-20T22:55:29Z",
  "updated_at": "2011-05-05T10:38:52Z"
}

Zu den wichtigsten Eigenschaften gehören:

• subject (erforderlich) - Die Betreffzeile, die für den Endbenutzer sichtbar ist
• description - Schreibgeschützter erster Kommentar zur Anfrage
• status - neu, offen, wartend, gehalten, gelöst oder geschlossen
• priority - niedrig, normal, hoch oder dringend
• type - Frage, Vorfall, Problem oder Aufgabe

Quelle: Zendesk Requests API Reference

Requests vs. Tickets API: Welche sollten Sie verwenden?

Dies ist eine kritische Entscheidung, die sich auf das Verhalten Ihrer Integration auswirkt. Hier ist die Aufschlüsselung:

Das Problem mit Agent Copilot ist wichtig. Wenn Sie ein Ticket über die Tickets API im Namen eines Endbenutzers erstellen, interpretiert Zendesk es als von einem Agenten erstellt. Das bedeutet, dass Agent Copilot nicht ausgelöst wird, weil er auf eine Kundenantwort wartet, die nie kommt. Die Verwendung der Requests API stellt sicher, dass sich Tickets genau wie solche verhalten, die per E-Mail oder Messaging erstellt wurden.

Quelle: Internal Note - API Requests and Agent Copilot

Authentifizierungsmethoden

Endbenutzerauthentifizierung

Endbenutzer können sich mit ihren eigenen Anmeldeinformationen authentifizieren. Bei Verwendung des Requests-Endpunkts werden Admins und Agenten wie Endbenutzer behandelt, sodass sie dieselbe eingeschränkte Ansicht sehen.

API-Token-Authentifizierung:

curl https://your-subdomain.zendesk.com/api/v2/requests.json \
  -u user@example.com/token:your_api_token_here

Wichtiger Hinweis: Ein Endbenutzer kann seine Anfragen nicht einsehen, wenn er nach dem 17. September 2017 eine E-Mail-Identität hinzugefügt und die E-Mail-Adresse nicht verifiziert hat. Die API gibt in diesem Fall eine 403-Antwort zurück.

Quelle: Zendesk Requests API Reference

Anfragen im Namen von Endbenutzern stellen (Admin-Impersonierung)

Manchmal müssen Admins Tickets für Endbenutzer erstellen. Dies erfordert OAuth mit einem Impersonate-Scope (impersonate = imitieren).

Schritt 1: Erstellen Sie einen OAuth-Client im Admin Center (Apps und Integrationen > APIs > OAuth-Clients)

Schritt 2: Fordern Sie ein Zugriffstoken mit dem Scope "impersonate" an:

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
  -H "Content-Type: application/json" \
  -d '{
    "token": {
      "client_id": "your_client_id",
      "scopes": ["impersonate", "write"]
    }
  }' \
  -X POST -v -u {email_address}/token:{api_token}

Schritt 3: Fügen Sie den X-On-Behalf-Of-Header in Ihre Anfragen ein:

curl https://z3napi.zendesk.com/api/v2/requests.json \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: customer@example.com" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "request": {
      "subject": "Hilfeanfrage",
      "comment": {"body": "Ich benötige Hilfe bei meiner Bestellung"}
    }
  }'

Wichtig: Der imitierte Endbenutzer muss ein bestehendes Benutzerprofil haben. Andernfalls schlägt die Anfrage mit einem invalid_token-Fehler fehl.

Quelle: Making API requests on behalf of end users

Anonyme Anfragen

Wenn Ihr Zendesk-Admin dies aktiviert hat, können Sie Anfragen ohne Authentifizierung erstellen. Dies ist nützlich für öffentliche Kontaktformulare.

Anforderungen:

• Anonyme Anfragen müssen im Admin Center aktiviert sein
• Fügen Sie ein requester-Objekt mit mindestens einem Namen hinzu

{
  "request": {
    "requester": {"name": "Anonymer Kunde"},
    "subject": "Hilfe!",
    "comment": {"body": "Mein Drucker brennt!"}
  }
}

Ratenbegrenzungen: Anonyme Anfragen sind auf 5 pro Stunde für Testkonten begrenzt.

Quelle: Creating and managing requests

Wichtige API-Endpunkte

Anfragen auflisten

Rufen Sie alle Anfragen für den authentifizierten Benutzer ab:

GET /api/v2/requests

Parameter:

• page - Paginierung (unterstützt Offset- oder Cursor-basiert)
• per_page - Anzahl der Datensätze pro Seite
• sort_by - "updated_at" oder "created_at"
• sort_order - "asc" oder "desc"

Eine Anfrage erstellen

Erstellen Sie ein neues Ticket aus der Perspektive eines Endbenutzers:

POST /api/v2/requests

Erforderliche Felder:

• subject - Der Ticketbetreff
• comment - Objekt mit body, das die Beschreibung enthält

Optionale Felder:

• requester - Für anonyme Anfragen (Objekt mit Name, E-Mail)
• collaborators - Array von Benutzer-IDs oder E-Mails, die in CC gesetzt werden sollen
• custom_fields - Array von benutzerdefinierten Feldwerten
• tags - Array von Tags, die angewendet werden sollen

Eine Anfrage aktualisieren

Fügen Sie Kommentare hinzu oder markieren Sie eine Anfrage als gelöst:

PUT /api/v2/requests/{id}

Beschreibbare Eigenschaften:

• comment - Einen neuen Kommentar hinzufügen
• solved - Auf true setzen, um als gelöst zu markieren (nur wenn can_be_solved_by_me true ist)
• additional_collaborators - CCs zur Anfrage hinzufügen

Kommentare auflisten

Zeigen Sie den Konversationsverlauf an:

GET /api/v2/requests/{request_id}/comments

Standardmäßig werden Kommentare nach Erstellungsdatum in aufsteigender Reihenfolge sortiert.

Quelle: Zendesk Requests API Reference

Codebeispiele

Eine Anfrage mit cURL erstellen

#!/bin/bash

SUBDOMAIN="your-subdomain"
EMAIL="admin@example.com"
TOKEN="your_api_token"

curl "https://${SUBDOMAIN}.zendesk.com/api/v2/requests.json" \
  -u "${EMAIL}/token:${TOKEN}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "request": {
      "subject": "Anfrage zum Bestellstatus",
      "comment": {
        "body": "Ich habe letzte Woche eine Bestellung aufgegeben und möchte den Status überprüfen. Meine Bestellnummer ist #12345."
      },
      "collaborators": ["spouse@example.com"]
    }
  }'

Eine Anfrage mit Python erstellen

import requests
import json

subdomain = "your-subdomain"
email = "admin@example.com"
api_token = "your_api_token"

url = f"https://{subdomain}.zendesk.com/api/v2/requests.json"

payload = {
    "request": {
        "subject": "Technische Unterstützung benötigt",
        "comment": {
            "body": "Ich habe Probleme, mich in mein Konto einzuloggen. Können Sie helfen?"
        }
    }
}

auth = (f"{email}/token", api_token)
headers = {"Content-Type": "application/json"}

try:
    response = requests.post(url, json=payload, auth=auth, headers=headers)
    response.raise_for_status()

    data = response.json()
    print(f"Anfrage erfolgreich erstellt!")
    print(f"Ticket-ID: {data['request']['id']}")
    print(f"Status: {data['request']['status']}")

except requests.exceptions.HTTPError as err:
    print(f"HTTP-Fehler: {err}")
    print(f"Antwort: {response.text}")
except Exception as err:
    print(f"Fehler: {err}")

Eine Anfrage mit Node.js erstellen

const axios = require('axios');

const config = {
  subdomain: 'your-subdomain',
  email: 'admin@example.com',
  apiToken: 'your_api_token'
};

async function createRequest() {
  const url = `https://${config.subdomain}.zendesk.com/api/v2/requests.json`;

  const payload = {
    request: {
      subject: 'Frage zur Abrechnung',
      comment: {
        body: 'Mir wurde meine Abonnementgebühr diesen Monat doppelt berechnet. Bitte helfen Sie, dies zu beheben.'
      }
    }
  };

  try {
    const response = await axios.post(url, payload, {
      auth: {
        username: `${config.email}/token`,
        password: config.apiToken
      },
      headers: {
        'Content-Type': 'application/json'
      }
    });

    console.log('Anfrage erfolgreich erstellt!');
    console.log(`Ticket-ID: ${response.data.request.id}`);
    console.log(`Status: ${response.data.request.status}`);

  } catch (error) {
    console.error('Fehler beim Erstellen der Anfrage:', error.response?.data || error.message);
  }
}

createRequest();

Häufige Fehler und Fehlerbehebung

403 Verboten

Dies ist der häufigste Fehler bei der Arbeit mit der Requests API. Häufige Ursachen:

• Nicht verifizierte E-Mail: Der Endbenutzer hat nach dem 17. September 2017 eine E-Mail hinzugefügt, ohne diese zu verifizieren
• Unzureichende Berechtigungen: Versuch, auf Endpunkte zuzugreifen, die für Endbenutzer nicht zulässig sind
• Fehlender Impersonate-Scope: Versuch, Anfragen im Namen von Benutzern ohne den entsprechenden OAuth-Scope zu stellen

Lösung: Verifizieren Sie die E-Mail-Adresse des Benutzers im Zendesk-Adminbereich oder stellen Sie sicher, dass Sie die richtige Authentifizierungsmethode für Ihren Anwendungsfall verwenden.

401 Nicht autorisiert

• Ungültiges API-Token oder ungültige OAuth-Anmeldeinformationen
• Token ist abgelaufen (OAuth-Token haben eine begrenzte Lebensdauer)
• Benutzerkonto ist gesperrt oder gelöscht

Lösung: Überprüfen Sie Ihre Anmeldeinformationen und generieren Sie bei Bedarf Token neu.

429 Ratenlimit überschritten

• Standard-API: 700 Anfragen pro Minute
• Anonyme Anfragen: 5 pro Stunde (Testkonten)

Lösung: Implementieren Sie einen exponentiellen Backoff in Ihrem Code. Wenn Sie eine 429 erhalten, warten Sie vor dem erneuten Versuch:

import time

def make_request_with_retry(url, payload, auth, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, auth=auth)
            response.raise_for_status()
            return response
        except requests.exceptions.HTTPError as err:
            if response.status_code == 429:
                wait_time = (2 ** attempt)  # Exponentieller Backoff
                print(f"Ratenbegrenzung. Warte {wait_time} Sekunden...")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("Maximale Anzahl an Wiederholungen überschritten")

Agent Copilot wird nicht ausgelöst

Wenn Sie den Agent Copilot von Zendesk verwenden und er keine Antworten für Tickets vorschlägt, die über die API erstellt wurden, verwenden Sie wahrscheinlich die Tickets API anstelle der Requests API.

Lösung: Wechseln Sie zur Requests API (POST /api/v2/requests.json) anstelle der Tickets API (POST /api/v2/tickets.json).

Quelle: Internal Note - API Requests and Agent Copilot

Bewährte Verfahren

Verwenden Sie die Requests API für Endbenutzer-orientierte Integrationen

Wenn Sie ein Kundenportal, ein Self-Service-Widget oder eine andere Schnittstelle erstellen, über die Endbenutzer Tickets erstellen, verwenden Sie immer die Requests API. Dies stellt Folgendes sicher:

• Korrektes Verhalten des Agent Copilot
• Korrekte Berechnung der ersten Antwortzeit
• Konsistenter Ticketlebenszyklus mit per E-Mail erstellten Tickets

Gehen Sie mit Ratenbegrenzungen elegant um

Implementieren Sie immer eine Wiederholungslogik mit exponentiellem Backoff. Die API von Zendesk wird von allen Kunden gemeinsam genutzt, und aggressives Polling kann dazu führen, dass Ihre Integration ratenbegrenzt oder blockiert wird.

Überprüfen Sie den E-Mail-Verifizierungsstatus

Bevor Sie Benutzern erlauben, ihre Anfragen einzusehen, überprüfen Sie, ob ihre E-Mail-Adresse bestätigt ist. Sie können dies über die Users API überprüfen und sie bei Bedarf auffordern, die E-Mail-Adresse zu verifizieren.

Speichern Sie Anmeldeinformationen sicher

Codieren Sie API-Token nicht fest in Ihrem Frontend-Code oder übertragen Sie sie in die Versionskontrolle. Verwenden Sie Umgebungsvariablen oder sichere Systeme zur Verwaltung von Geheimnissen.

Erwägen Sie No-Code-Alternativen

Das Erstellen und Warten von API-Integrationen erfordert erhebliche Entwicklungsressourcen. Wenn Ihr Ziel darin besteht, Supportantworten zu automatisieren, anstatt benutzerdefinierte Portale zu erstellen, sollten Sie Tools wie eesel AI in Betracht ziehen, die sich direkt in Zendesk integrieren und KI-gestützte Automatisierung ohne Programmierung bieten. eesel AI erfordert keine komplexe Konfiguration, Sie laden es einfach in Ihr Team ein und es lernt Ihr Unternehmen in wenigen Minuten kennen.

Wir bieten:

• KI-Agent, der den Frontline-Support autonom abwickelt
• KI-Copilot, der Antworten für Agenten zum Überprüfen entwirft
• KI-Triage, die Tickets automatisch taggt, weiterleitet und priorisiert
• One-Click-Integration mit Zendesk (keine API-Entwicklung erforderlich)

Quelle: eesel AI Products

Beginnen Sie mit der Entwicklung mit der Zendesk Requests API

Die Zendesk Requests API bietet Ihnen eine sichere Möglichkeit, Endbenutzer mit Ihrem Supportsystem interagieren zu lassen. Indem Sie den Unterschied zwischen Requests- und Tickets-APIs verstehen, die richtige Authentifizierung implementieren und bewährte Verfahren befolgen, können Sie robuste Self-Service-Integrationen erstellen.

Wichtige Erkenntnisse:

• Verwenden Sie die Requests API für Endbenutzer-orientierte Integrationen
• Implementieren Sie OAuth mit Impersonate-Scope, wenn Admins im Namen von Benutzern handeln müssen
• Behandeln Sie Ratenbegrenzungen und Fehler elegant
• Testen Sie gründlich, bevor Sie in die Produktion gehen

Weitere Informationen finden Sie in der offiziellen Zendesk Requests API-Dokumentation.

Wenn Sie den Support ohne den Entwicklungsaufwand automatisieren möchten, erfahren Sie, wie eesel AI Ihnen helfen kann. Unsere KI-Agenten integrieren sich direkt in Zendesk, lernen aus Ihrer bestehenden Dokumentation und Ihren vergangenen Tickets und können bis zu 81 % des Frontline-Supports autonom abwickeln.