Tutorial zur Chat-API: Generieren eines OAuth-Tokens (integrierte Chat-Konten)

Um die Chat-API in Support+Chat-Konten und Phase 4 Chat-Konten zu verwenden, müssen Sie ein OAuth-Zugriffstoken für die Authentifizierung von API-Anfragen generieren. Die Standardauthentifizierung wird nicht unterstützt. Das Generieren eines Tokens kann beim ersten Mal etwas verwirrend sein. Deshalb finden Sie in diesem Tutorial Beispiele, in denen Schritt für Schritt erklärt wird, wie Sie ein Token manuell erstellen. Nachdem Sie diese Schritte ausgeführt haben, verfügen Sie über ein Token, das Sie in Chat-API-Anforderungen zum Lesen und Schreiben von Daten verwenden können.

Wenn Sie eine Anwendung erstellen, sollten Sie die Funktion zum Generieren des Tokens in Ihre App einbinden, um den Vorgang zu automatisieren.

Es gibt zwei Möglichkeiten, ein Zugriffstoken für die Chat-API zu erstellen – eine schnellere, bequemere Möglichkeit für Testumgebungen (mit „impliziter“ Berechtigung) und eine langsamere, formellere Möglichkeit für Produktionsumgebungen (mit Berechtigung per „Autorisierungscode“). In diesem Tutorial werden beide Möglichkeiten beschrieben.

Voraussetzungen

Dieses Tutorial ist für integrierte Chat-Konten vorgesehen, auf die alle oben genannten Änderungen angewendet wurden. Diese werden derzeit eingeführt und bei manchen Konten früher benötigt als bei anderen. Wenn Sie nicht sicher sind, ob auf Ihr Konto bereits alle Änderungen angewendet wurden, fragen Sie bitte bei unserem Supportteam nach.

Hinweis: Infolge der Änderungen an den Konten müssen unter anderem die OAuth-Token neu erstellt werden. Wenn Sie die in diesem Tutorial beschriebenen Schritte ausführen, bevor die Änderungen auf Ihr Konto angewendet wurden, müssen Sie sie anschließend noch einmal wiederholen.

Vorgehensweise

Das „implizite“ OAuth-Berechtigungsverfahren umfasst die folgenden Schritte:

1. OAuth API-Client erstellen
2. Implizites OAuth-Berechtigungsverfahren mit den Informationen aus Schritt 1 durchführen, um das Token abzurufen

OAuth API-Client erstellen

Als Erstes brauchen wir einen API-Client. Gehen Sie zu Zendesk Chat > Konto > API und SDKs und klicken Sie auf API-Client hinzufügen. Geben Sie einen Namen für den Client, ein Unternehmen Ihrer Wahl und die Weiterleitungs-URL (http://localhost:8080) ein. Es sieht ähnlich aus wie das folgende Beispiel:

Klicken Sie auf API-Client erstellen, um die Einrichtung abzuschließen. Ein Fenster mit der Client-ID und dem Geheimnis wird eingeblendet. Wichtig: Das Client-Geheimnis wird nur einmal angezeigt. Notieren Sie es sich deshalb und bewahren Sie es sorgfältig auf. Es sieht folgendermaßen aus:

Damit ist Ihr API-Client einsatzbereit. Vergessen Sie nicht, Ihre Client-ID und das Client-Geheimnis zu notieren, bevor Sie auf OK klicken. Nun sind wir bereit, das OAuth-Berechtigungsverfahren durchzuführen.

Implizites OAuth-Berechtigungsverfahren durchführen, um das Token abzurufen

Bei dieser Methode wird das „implizite“ OAuth-Berechtigungsverfahren verwendet. Sie können auch eine alternative Methode verwenden, bei der die OAuth-Berechtigung per „Autorisierungscode“ zum Einsatz kommt. Diese wird im nächsten Abschnitt beschrieben. Die hier beschriebene Methode umfasst weniger manuelle Schritte und ist komfortabler als die Methode mit dem Autorisierungcode.

1. Führen Sie die oben unter „OAuth API-Client erstellen“ beschriebenen Schritte aus.

2. Notieren Sie die folgenden Informationen aus dem OAuth-Client:

• Client-ID CLIENT_ID
• Ihre Zendesk-Subdomäne

3. Ersetzen Sie die Platzhalter CLIENT_ID und SUBDOMAIN in der folgenden URL durch Ihre Client-ID und Subdomäne, kopieren Sie die URL in eine neue Browser-Registerkarte und drücken Sie die Eingabetaste.

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=token&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

HINWEISE:

• Wenn der Chat OAuth-Client nur einen Weiterleitungs-URL-Wert aufweist, wird der redirect_uri-Wert nicht benötigt. In diesem Fall verwendet das System standardmäßig die vorhandene Weiterleitungs-URL des OAuth-Clients.
• Wenn der OAuth-Client mehrere Weiterleitungs-URL-Werte aufweist, muss ein redirect_uri-Wert übergeben werden. In diesem Fall muss der redirect_uri-Wert in URL-Codierung angegeben werden. Im obigen Beispiel lautet der optionale Weiterleitungsparameter redirect_uri=http%3A%2F%2Flocalhost%3A8080.

4. Die URL wird aufgerufen. Hierbei werden Sie möglicherweise aufgefordert, sich anzumelden und auf „Zulassen“ zu klicken, um das Token zu generieren.

Wenn der Aufruf erfolgreich war, enthält das Adressfeld Ihres Browsers das neue OAuth-Token (im Wert ‚access_token‘).

Obwohl im Hauptfenster des Browsers eine Fehlermeldung angezeigt wird, wenn im Adressfeld der „access_token“-Wert erscheint, hat es funktioniert!

Hier sehen Sie eine Demonstration des Workflows:

 

Eine längere, alternative Methode zum Generieren des Tokens

Mit diesen Schritten wird wie im obigen Abschnitt ein Token erstellt, aber das OAuth-Berechtigungsverfahren per „Autorisierungscode“ verwendet. Notieren Sie sich die Daten ihres OAuth-Clients, die Sie weiter unten eingeben müssen.

Anstelle der tatsächlichen Daten werden Platzhalter angezeigt. Bewahren Sie das Geheimnis Ihres OAuth-Clients vor unbefugtem Zugriff geschützt auf, da es im Grunde als Kennwort den Zugriff auf Ihr Chat-Konto ermöglicht.

• Client-ID: CLIENT_ID
• Client-Geheimnis: CLIENT_SECRET
• Weiterleitungs-URI:http://localhost:8080
• Subdomäne: Ihre Zendesk-Subdomäne. Wenn Ihre Kontodomäne beispielsweise niall.zendesk.com lautet, ist dieser Wert niall
• Autorisierungscode: noch nicht vorhanden

1. Erste URL vorbereiten

Hier werden wir eine URL für die Anforderung eines Autorisierungscodes erstellen. Zur Übergabe der oben aufgeführten Informationen müssen Sie einige Query-Parameter an https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new anhängen. Dieses Mal brauchen wir:

• response_type: ist immer code
• redirect_uri: die Adresse, an die wir weitergeleitet werden, nachdem wir Zugriff erhalten haben – in unserem Tutorial lautet sie http://localhost:8080
• client_id: wird Ihnen wie oben beschrieben individuell zugewiesen
• scope: die mit dem Token verbundenen Zugriffsberechtigungen, in unserem Fall read und write
  • Wenn das Token für die Chat Conversations API verwendet wird, muss auch „chat“ angegeben werden.
• subdomain: Ihre Zendesk-Subdomäne

Zusammengesetzt und in URL-Codierung sieht die fertige URL so aus:

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

Ihre eigene URL unterscheidet sich von diesem Beispiel lediglich durch die Werte für CLIENT_ID und SUBDOMAIN.

2. cURL-Aufruf vorbereiten

Bevor wir diese URL tatsächlich besuchen, wollen wir noch den anschließenden cURL-Aufruf erstellen. Dieses Mal brauchen wir:

• grant_type: ist immer authorization_code
• code: wird zugeteilt, nachdem wir den Zugriff über die URL erteilt haben
• client_id: Ihre Client-ID
• client_secret: Ihr Client-Geheimnis
• redirect_uri: wie im vorherigen Schritt http://localhost:8080
• scope: wie im vorherigen Schritt read und write

Zusammengesetzt erhalten wir einen Befehl, der etwa folgendermaßen aussieht:

curl https://{subdomain}.zendesk.com/oauth2/chat/ \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

Beachten Sie, dass Sie CLIENT_ID und CLIENT_SECRET bereits haben, AUTH_CODE allerdings noch nicht.

3. Autorisierungscode abrufen

Rufen wir nun die in Schritt 1 generierte URL auf. Es wird eine Seite angezeigt, die ungefähr so aussieht:

Klicken Sie auf Zulassen, um Zugriff zu gewähren. Sie werden zur Weiterleitungs-URL weitergeleitet. Was angezeigt wird, sieht auf den ersten Blick wie eine nicht erreichbare Seite aus, doch der URL-Zeile können Sie den Autorisierungscode entnehmen (die gesamte Zeichenfolge nach ?code=).

Kopieren Sie diesen Code und machen Sie sich für den letzten Schritt bereit! Der Autorisierungscode ist nur für kurze Zeit gültig. Wenn Sie länger als ein paar Minuten warten, müssen Sie den vorigen Schritt möglicherweise wiederholen und einen neuen Code abrufen.

4. cURL-Aufruf für den Abruf des Tokens ausführen

Nehmen wir uns den cURL-Aufruf vor, den wir in Schritt 2 erstellt haben. Er sieht folgendermaßen aus:

curl https://{subdomain}.zendesk.com/oauth2/chat/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

Ersetzen Sie AUTH_CODE durch den Code aus Schritt 3 und führen Sie den Befehl in einer Terminal-Anwendung aus. Als Antwort erhalten Sie ein JSON-Objekt wie dieses:

{
 "access_token": "TOKEN",
 "token_type": "Bearer",
 "refresh_token": "REFRESH_TOKEN",
 "scope": "read write"
}

5. Neues Token testen

Neue Einstellungen sollten immer getestet werden, deshalb wollen wir zum Schluss ausprobieren, ob die Autorisierung wie erwartet funktioniert. Dazu rufen Sie am besten mit einem einfachen GET-Befehl an /api/v2/chats Ihre Kontodaten ab:

curl https://{subdomain}.zendesk.com/api/v2/chat/chats -H "Authorization: Bearer TOKEN"

Geben Sie dabei für TOKEN das in Schritt 4 abgerufene Token ein. 

Weitere Informationen

Vertraulicher client_type

In den oben stehenden Abschnitten wurden das „implizite“ Berechtigungsverfahren und das Berechtigungsverfahren per „Autorisierungscode“ vorgestellt. Die Chat-API unterstützt auch den vertraulichen Berechtigungstyp unter Verwendung von Client-Anmeldedaten. Dies ist in der Referenzdokumentation unter Confidential grant types (Englisch) ausführlicher beschrieben.

Zum Abruf von Reporting-Metriken per API könnten Administratoren und Agenten zum Beispiel sinnvollerweise auch den vertraulichen Berechtigungstyp verwenden. Hierfür müssen Sie den client_type auf „confidential“ setzen. Standardmäßig ist dieser Wert auf „public“ eingestellt. Dies ist nur wie im Folgenden beschrieben per API möglich:

1. Client-ID abrufen

Als Erstes brauchen wir die ID Ihres neuen Clients. Diese können Sie mit Ihrem neuen Token wie folgt abrufen:

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients -H "Authorization: Bearer TOKEN"

Eine Liste aller Ihrer Clients wird angezeigt. Falls Sie mehr als einen Client haben, wählen Sie den gewünschten Client aus und notieren Sie sich seine ID.

2. client_type aktualisieren

Nachdem Sie die ID des Clients abgerufen haben, können Sie die Eigenschaft client_type mit dem folgenden cURL-Aufruf aktualisieren:

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients/{client_ID} -d '{"client_type": "confidential"}' \
 -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN"

Danach kann Ihr Token für beschränkte Endpunkte verwendet werden.