Wie man Benutzer mit der Zendesk API erstellt: Eine vollständige Anleitung

Die Verwaltung von Benutzerkonten in großem Umfang ist eine dieser Aufgaben, die einfach beginnt und schnell kompliziert wird. Egal, ob Sie Kunden aus einer neuen Akquisition einarbeiten, Benutzer aus Ihrer internen Datenbank synchronisieren oder einen Self-Service-Registrierungsablauf erstellen, Sie müssen irgendwann Zendesk-Benutzer programmgesteuert erstellen.

Die Zendesk Users API bietet Ihnen die Werkzeuge, um dies zu tun. Es ist eine RESTful API, die alles von der Erstellung einzelner Benutzer bis zum Massenimport von Tausenden auf einmal abwickelt. Diese Anleitung führt Sie durch die praktischen Schritte, um sie zum Laufen zu bringen, mit funktionierenden Codebeispielen, die Sie an Ihren Stack anpassen können.

Wenn Sie mehr als nur die Benutzererstellung automatisieren möchten, können Tools wie eesel AI das gesamte Spektrum der Support-Automatisierung abdecken, vom Ticket-Routing bis hin zu KI-gestützten Antworten.

Was Sie benötigen

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

• Ein Zendesk-Konto mit Administratorzugriff - nur Administratoren können API-Token erstellen und Benutzer über die API verwalten
• Ein API-Token oder OAuth-Anmeldeinformationen - wir werden im Folgenden erläutern, wie diese generiert werden
• Grundlegende Vertrautheit mit REST APIs - Sie sollten wissen, was eine POST-Anfrage ist
• Eine Entwicklungsumgebung - cURL, Python oder Node.js funktionieren gut

Schritt 1: Richten Sie die API-Authentifizierung ein

Zendesk unterstützt zwei Hauptauthentifizierungsmethoden für den API-Zugriff: API-Token und OAuth. Für die meisten Server-zu-Server-Integrationen sind API-Token einfacher zu implementieren.

Generieren eines API-Tokens

1. Melden Sie sich als Administrator bei Ihrem Zendesk-Konto an
2. Navigieren Sie zum Admin Center (klicken Sie auf das Zahnradsymbol und dann auf "Zum Admin Center gehen")
3. Gehen Sie zu Apps und Integrationen → APIs → Zendesk API
4. Klicken Sie auf die Registerkarte Einstellungen und stellen Sie sicher, dass Token-Zugriff aktiviert ist
5. Wechseln Sie zur Registerkarte API-Token und klicken Sie auf API-Token hinzufügen
6. Geben Sie einen beschreibenden Namen wie "Benutzer-Sync-Integration" ein
7. Kopieren Sie das Token sofort - Zendesk zeigt es nur einmal an

Formatieren Ihres Authentifizierungs-Headers

Zendesk verwendet die Standardauthentifizierung (Basic Authentication) mit Ihrem API-Token. Das Format ist:

• Benutzername: Ihre Zendesk-E-Mail-Adresse mit /token angehängt (z. B. you@company.com/token)
• Passwort: Das API-Token selbst

Base64-kodieren Sie diese Anmeldeinformationen und fügen Sie sie in den Authorization-Header ein:

curl https://your-subdomain.zendesk.com/api/v2/users.json \
  -u you@company.com/token:your_api_token_here

Oder in Python:

import requests
from requests.auth import HTTPBasicAuth

subdomain = "your-subdomain"
email = "you@company.com"
token = "your_api_token_here"

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

url = f"https://{subdomain}.zendesk.com/api/v2/users.json"
response = requests.get(url, auth=auth, headers=headers)
print(response.json())

Sicherheits-Best Practices

• Speichern Sie API-Token in Umgebungsvariablen, niemals in Ihrem Code
• Rotieren Sie Token regelmäßig - löschen Sie alte und generieren Sie neue
• Verwenden Sie beschreibende Token-Namen, damit Sie wissen, wofür jedes Token ist
• Löschen Sie Token, wenn Integrationen außer Betrieb genommen werden
• Erwägen Sie, einen dedizierten Service-Benutzer mit eingeschränkten Berechtigungen zu erstellen, anstatt das Token eines Administrators zu verwenden

Schritt 2: Erstellen Sie einen einzelnen Benutzer

Der einfachste Weg, einen Benutzer zu erstellen, ist über den Endpunkt POST /api/v2/users. Mindestens müssen Sie einen Namen angeben.

Erforderliche und optionale Parameter

Benutzerrollen verstehen

Zendesk hat drei integrierte Rollen:

• end-user: Kunden, die Tickets einreichen (Standard, wenn keine Rolle angegeben ist)
• agent: Support-Mitarbeiter, die Tickets bearbeiten
• admin: Voller administrativer Zugriff

Für Enterprise-Pläne können Sie auch benutzerdefinierte Agentenrollen mithilfe des Parameters custom_role_id zuweisen. Beachten Sie, dass benutzerdefinierte Rollen zuerst im Admin Center erstellt werden müssen - Sie können sie nicht über die API erstellen.

Code Beispiele

cURL:

curl https://your-subdomain.zendesk.com/api/v2/users.json \
  -d '{"user": {"name": "Jane Smith", "email": "jane@example.com", "role": "end-user"}}' \
  -H "Content-Type: application/json" \
  -X POST \
  -u you@company.com/token:your_api_token

Python:

import requests
import json
from requests.auth import HTTPBasicAuth

subdomain = "your-subdomain"
auth = HTTPBasicAuth("you@company.com/token", "your_api_token")
headers = {"Content-Type": "application/json"}

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "role": "end-user",
        "external_id": "user_12345"
    }
}

response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/users.json",
    auth=auth,
    headers=headers,
    json=user_data
)

if response.status_code == 201:
    user = response.json()["user"]
    print(f"Created user {user['id']}: {user['name']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

JavaScript (Node.js mit axios):

const axios = require('axios');

const subdomain = 'your-subdomain';
const email = 'you@company.com';
const token = 'your_api_token';

const userData = {
  user: {
    name: 'Jane Smith',
    email: 'jane@example.com',
    role: 'end-user',
    external_id: 'user_12345'
  }
};

axios.post(
  `https://${subdomain}.zendesk.com/api/v2/users.json`,
  userData,
  {
    auth: {
      username: `${email}/token`,
      password: token
    },
    headers: {
      'Content-Type': 'application/json'
    }
  }
)
.then(response => {
  const user = response.data.user;
  console.log(`Created user ${user.id}: ${user.name}`);
})
.catch(error => {
  console.error('Error:', error.response?.data || error.message);
});

Interpretieren der Antwort

Eine erfolgreiche Erstellung gibt HTTP 201 Created mit dem Benutzerobjekt zurück:

{
  "user": {
    "id": 9873843,
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "end-user",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "active": true,
    "verified": false
  }
}

Schritt 3: Benutzer erstellen oder aktualisieren (Upsert)

Was passiert, wenn Sie versuchen, einen Benutzer zu erstellen, der bereits existiert? Der Standard-Erstellungs-Endpunkt gibt einen 422-Fehler zurück. Verwenden Sie für Synchronisierungsszenarien, in denen Sie regelmäßig Benutzer aus einem externen System importieren, stattdessen den Endpunkt create_or_update.

Wann create_or_update verwendet werden sollte

Verwenden Sie POST /api/v2/users/create_or_update, wenn:

• Sie synchronisieren Benutzer aus einer externen Datenbank
• Sie möchten idempotente Operationen (dieselbe Anfrage erzeugt dasselbe Ergebnis)
• Sie möchten nicht prüfen, ob ein Benutzer vor dem Erstellen existiert

Wie die Übereinstimmung funktioniert

Zendesk gleicht Benutzer ab nach:

1. Externe ID - falls angegeben, hat dies Vorrang
2. E-Mail-Adresse - wenn keine externe ID-Übereinstimmung gefunden wurde

Antwortcodes

Praktisches Beispiel: Synchronisieren aus einem externen System

import requests
from requests.auth import HTTPBasicAuth

auth = HTTPBasicAuth("you@company.com/token", "your_api_token")
headers = {"Content-Type": "application/json"}

external_users = [
    {"name": "Jane Smith", "email": "jane@example.com", "external_id": "usr_001"},
    {"name": "John Doe", "email": "john@example.com", "external_id": "usr_002"}
]

for external_user in external_users:
    user_data = {"user": external_user}

    response = requests.post(
        "https://your-subdomain.zendesk.com/api/v2/users/create_or_update.json",
        auth=auth,
        headers=headers,
        json=user_data
    )

    if response.status_code == 201:
        print(f"Created: {external_user['email']}")
    elif response.status_code == 200:
        print(f"Updated: {external_user['email']}")
    else:
        print(f"Failed: {external_user['email']} - {response.text}")

Schritt 4: Erstellen Sie mehrere Benutzer im Stapel

Wenn Sie Hunderte oder Tausende von Benutzern erstellen müssen, sind einzelne API-Aufrufe ineffizient. Zendesk bietet einen Stapel-Endpunkt, der bis zu 100 Benutzer pro Anfrage akzeptiert.

Endpunkt und Einschränkungen

• Endpunkt: POST /api/v2/users/create_many
• Limit: 100 Benutzer pro Anfrage
• Aktivierung: Massenimporte müssen vom Zendesk-Support aktiviert werden (wenden Sie sich an den Support, wenn Sie 403-Fehler erhalten)

Job_status-Antworten verstehen

Im Gegensatz zur Erstellung einzelner Benutzer sind Stapeloperationen asynchron. Die API gibt sofort ein job_status-Objekt zurück, und die eigentliche Erstellung erfolgt im Hintergrund:

{
  "job_status": {
    "id": "82de0b044094f0c67893ac9fe64f1a99",
    "status": "queued",
    "total": 50,
    "progress": 0,
    "url": "https://your-subdomain.zendesk.com/api/v2/job_statuses/82de0b044094f0c67893ac9fe64f1a99"
  }
}

Fragen Sie die Jobstatus-URL ab, um den Fortschritt zu verfolgen:

def check_job_status(job_url):
    response = requests.get(job_url, auth=auth)
    job = response.json()["job_status"]

    print(f"Status: {job['status']}, Progress: {job['progress']}/{job['total']}")

    if job["status"] == "completed":
        for result in job.get("results", []):
            print(f"  {result['action']}: User {result['id']} - {result['status']}")

    return job["status"]

import time
while check_job_status(job_url) != "completed":
    time.sleep(5)

Wann Bulk sinnvoll ist

Beispiel für die Massenerstellung

users_to_create = [
    {"name": "User One", "email": "user1@example.com", "role": "end-user"},
    {"name": "User Two", "email": "user2@example.com", "role": "end-user"},
    # ... bis zu 100 Benutzer
]

response = requests.post(
    "https://your-subdomain.zendesk.com/api/v2/users/create_many.json",
    auth=auth,
    headers=headers,
    json={"users": users_to_create}
)

if response.status_code == 200:
    job = response.json()["job_status"]
    print(f"Job queued: {job['id']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Häufige Fehler und Fehlerbehebung

Auch mit dem richtigen Code kann etwas schiefgehen. Hier erfahren Sie, wie Sie die häufigsten Probleme beheben:

401 Nicht autorisiert

Ihre Anmeldeinformationen sind ungültig. Überprüfen Sie:

• Ist die E-Mail-Adresse korrekt?
• Haben Sie /token an den Benutzernamen angehängt?
• Ist das API-Token noch aktiv (nicht gelöscht)?
• Verwenden Sie die richtige Subdomain?

403 Verboten

Sie haben keine Berechtigung für diese Aktion. Häufige Ursachen:

• Das API-Token gehört zu einem Agenten, nicht zu einem Administrator
• Massenimporte sind in Ihrem Konto nicht aktiviert (wenden Sie sich an den Zendesk-Support)
• Sie versuchen, einen Administratorbenutzer ohne ausreichende Berechtigungen zu erstellen

422 Unverarbeitbare Entität

Die Anfragedaten sind ungültig. Überprüfen Sie:

• Ist das Feld name vorhanden? (es ist erforderlich)
• Ist das E-Mail-Format gültig?
• Ist die Rolle eine von: end-user, agent, admin?
• Existiert die organization_id?

429 Zu viele Anfragen

Sie haben das Ratenlimit von Zendesk erreicht. Die API gibt einen Retry-After-Header zurück, der angibt, wie viele Sekunden gewartet werden muss. Implementieren Sie exponentielles Backoff in Ihrem Code:

import time

def api_call_with_retry(url, auth, headers, json_data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, auth=auth, headers=headers, json=json_data)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Waiting {retry_after} seconds...")
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Max retries exceeded")

Doppelte E-Mail-Fehler

Wenn Sie einen 422-Fehler mit der Meldung "E-Mail wurde bereits verwendet" erhalten, entweder:

• Verwenden Sie stattdessen den Endpunkt create_or_update
• Überprüfen Sie zuerst, ob der Benutzer vorhanden ist, mit GET /api/v2/users/search?query=email@example.com

Best Practices für die Automatisierung der Benutzerverwaltung

Nach der Arbeit mit der Zendesk Users API sind hier Muster, die immer gut funktionieren:

Verwenden Sie external_id für Idempotenz

Fügen Sie immer eine external_id hinzu, die Ihrer internen Benutzer-ID zugeordnet ist. Dies macht Operationen idempotent und vereinfacht die Synchronisierung:

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "external_id": f"internal_db_{internal_user_id}"
    }
}

Setzen Sie den verifizierten Status, um die E-Mail-Bestätigung zu überspringen

Wenn Sie Benutzer aus einer vertrauenswürdigen Quelle erstellen (z. B. Ihrer eigenen Datenbank), setzen Sie verified: true, um zu verhindern, dass Zendesk Bestätigungs-E-Mails sendet:

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "verified": True  # E-Mail-Bestätigung überspringen
    }
}

Behandeln Sie benutzerdefinierte Rollen korrekt

Benutzerdefinierte Rollen sind eine Enterprise-Funktion. So weisen Sie sie zu:

1. Erstellen Sie zuerst die benutzerdefinierte Rolle im Admin Center
2. Holen Sie sich die custom_role_id aus der URL oder API der Rolle
3. Setzen Sie sowohl role: "agent" als auch custom_role_id: 12345

Implementieren Sie eine ordnungsgemäße Fehlerbehandlung

Gehen Sie nicht davon aus, dass API-Aufrufe erfolgreich sind. Schließen Sie Aufrufe in Try/Except-Blöcke ein und behandeln Sie bestimmte Fehlerfälle:

try:
    response = requests.post(url, auth=auth, headers=headers, json=data)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    if response.status_code == 422:
        errors = response.json().get("details", {})
        print(f"Validation error: {errors}")
    else:
        raise

Speichern Sie Anmeldeinformationen sicher

Hardcodieren Sie niemals API-Token. Verwenden Sie Umgebungsvariablen:

import os

ZENDESK_SUBDOMAIN = os.environ.get("ZENDESK_SUBDOMAIN")
ZENDESK_EMAIL = os.environ.get("ZENDESK_EMAIL")
ZENDESK_TOKEN = os.environ.get("ZENDESK_TOKEN")

Berücksichtigen Sie umfassendere Automatisierungsanforderungen

Wenn Sie die Benutzererstellung automatisieren, verwalten Sie wahrscheinlich einen wachsenden Support-Betrieb. Während die Zendesk API die Benutzerverwaltung übernimmt, müssen Sie möglicherweise auch die Ticketbearbeitung, das Routing und die Antworten automatisieren. eesel AI integriert sich in Zendesk, um diese Workflows automatisch zu verarbeiten, von der Klassifizierung und Kennzeichnung von Tickets bis hin zum Entwurf von KI-gestützten Antworten.

Beginnen Sie mit der Automatisierung Ihrer Zendesk-Workflows

Sie haben jetzt die Grundlage, um Zendesk-Benutzer programmgesteuert zu erstellen. Egal, ob Sie eine Benutzer-Sync-Integration erstellen, das Onboarding automatisieren oder eine große Kundenbasis verwalten, die Users API gibt Ihnen die Kontrolle, die Sie benötigen.

Die Muster in dieser Anleitung - Authentifizierung, einzelne Erstellung, Upserts und Stapeloperationen - decken die meisten realen Szenarien ab. Beginnen Sie mit dem einzelnen Benutzer-Endpunkt, um Ihre Einrichtung zu validieren, und wechseln Sie dann zu Stapeloperationen, wenn Ihre Skalierung zunimmt.

Wenn Sie über die Benutzererstellung hinaus automatisieren möchten, überlegen Sie, wie KI Ihren gesamten Support-Workflow optimieren kann. eesel AI integriert sich in Zendesk, um die Ticket-Triage, den Antwortentwurf und das intelligente Routing zu übernehmen - wodurch die manuelle Arbeit reduziert und gleichzeitig die Reaktionszeiten verbessert werden. Sie können unseren KI-Agenten für den Kundenservice erkunden, um zu sehen, wie die Automatisierung auf Ihren gesamten Support-Stack ausgedehnt werden kann.