Tutoriel pour l’API Chat : génération d’un token OAuth (comptes Chat intégrés)

Pour utiliser l’API Chat dans les comptes Support+Chat et les comptes Chat Phase 4, vous devez générer un token d’accès OAuth afin d’authentifier les demandes API. L’authentification élémentaire n’est pas prise en charge. Cependant, si c’est la première fois que vous générez un token, cela peut vous paraître compliqué et ce tutoriel vous fournit des exemples étape par étape, montrant comment générer un token manuellement. Quand vous aurez terminé, vous devriez avoir un token que vous pourrez utiliser dans les demandes API Chat pour lire et écrire les données.

Si vous développez une application, vous devriez intégrer la fonctionnalité de génération de token à votre application pour automatiser ce processus.

Il y a deux façons de générer un token d’accès pour l’API Chat : une méthode plus rapide et plus pratique pour les environnements de test (en utilisant un flux d’authentification « implicite »), et une méthode plus longue et plus formelle pour les environnements de production (en utilisant un flux d’authentification avec code d’autorisation). Ce tutoriel explique les deux méthodes.

Conditions

Ce tutoriel est destiné aux comptes Chat intégrés auxquels ont été appliquées toutes les modifications référencées dans l’article ci-dessus. Ce déploiement se fait progressivement et il est donc possible qu’il concerne certains comptes avant d’autres. Si vous ne savez pas si toutes les modifications ont été appliquées à votre compte, n’hésitez pas à contacter notre équipe d’assistance.

Remarque – L’une des conséquences des modifications des comptes est que les tokens OAuth doivent être recréés. Si vous finissez ce tutoriel avant que les modifications aient été appliquées à votre compte, vous devrez à nouveau suivre ces étapes.

Procédure

Le flux d’authentification OAuth « implicite » suit les étapes ci-dessous :

1. Créez le client API OAuth
2. Terminez le flux d’authentification OAuth implicite pour obtenir le token en utilisant les informations de l’étape 1.

Créez le client API OAuth

Pour commencer, il vous faut un client API. Allez à Zendesk Chat > Compte > API et SDK et cliquez sur le bouton Ajouter un client API. Saisissez un nom pour le client et l’entreprise de votre choix, et pour l’URL de redirection, saisissez http://localhost:8080. Il devrait ressembler à ce qui suit :

Cliquez sur Créer un client API pour terminer la configuration. Vous voyez l’ID et le secret client dans une fenêtre contextuelle. Très important : le secret client ne s’affiche qu’une seule fois, alors n’oubliez pas de le noter pour utilisation ultérieure. Il devrait ressembler à ce qui suit :

Maintenant que notre client API est prêt, notez votre ID et votre secret client avant de cliquer sur OK. Nous voilà à terminer le flux d’authentification OAuth.

Terminez le flux d’authentification OAuth implicite pour obtenir le token

Cette approche utilise le flux d’authentification OAuth « implicite ». Une autre approche utilise le flux d’authentification avec code d’autorisation OAuth (expliqué dans la section suivante). Si vous effectuez ce processus manuellement, l’approche implicite est plus courte et plus pratique que l’approche avec code d’autorisation.

1. Suivez l’étape Créez le client API OAuth API ci-dessus.

2. Recueillez les informations suivantes depuis le client OAuth :

• ID client : CLIENT_ID
• Votre sous-domaine Zendesk

3. Formatez l’URL ci-dessous avec vos propres valeurs CLIENT_ID et SUBDOMAIN, collez-la dans un nouvel onglet de navigateur et appuyez sur Entrée.

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

NOTES :

• Si le client OAuth Chat a une seule valeur d’URL de redirection, le transfert d’une valeur redirect_uri est facultatif. Le système utilise la valeur d’URL de redirection du client OAuth par défaut.
• Si le client OAuth Chat a plusieurs valeurs d’URL de redirection, le transfert d’une valeur redirect_uri est obligatoire. Si vous transférez une valeur redirect_uri, elle doit être codée URL. Dans l’exemple ci-dessus, le paramètre de redirection facultatif serait : redirect_uri=http%3A%2F%2Flocalhost%3A8080

4. L’appel sera fait (il est possible qu’il vous soit demandé de vous connecter et de sélectionner Autoriser pour générer le token).

Si l’appel réussit, le champ d’adresse de votre navigateur contiendra votre nouveau token OAuth (renvoyé en tant que valeur access_token).

Même si vous voyez ce qui semble être un message d’erreur dans la fenêtre de navigateur principale, si access_token est renvoyé dans le champ d’URL du navigateur, le processus a fonctionné.

Voici une démonstration du workflow :

 

Une autre méthode, plus longue, pour générer le token

Ces étapes créent un token, comme la section précédente, mais expliquent le flux d’authentification OAuth avec code d’autorisation. Notez les détails de votre client OAuth, qui seront utilisés ci-dessous.

Nous allons utiliser des balises plutôt que de vraies données. N’oubliez pas le secret de votre client OAuth doit rester absolument confidentiel, car c’est plus ou moins un mot de passe permettant d’accéder à votre compte Chat.

• ID client : CLIENT_ID
• Secret client : CLIENT_SECRET
• URI de redirection : http://localhost:8080
• Sous-domaine : votre sous-domaine Zendesk. Par exemple, si votre compte est niall.zendesk.com, votre sous-domaine est niall.
• Code d’autorisation : nous ne l’avons pas encore.

1. Préparez la première URL

Ici, nous allons créer une URL pour demander un code d’autorisation. Vous devez aller à https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new et ajouter des paramètres de requête pour transférer certaines des informations ci-dessus. Ici, nous avons besoin de :

• response_type : cela sera toujours code
• redirect_uri : l’endroit où nous serons redirigés une fois l’accès accordé, http://localhost:8080 pour notre tutoriel.
• client_id : l’ID qui vous est spécifique, que vous avez noté précédemment.
• scope : l’accès qu’aura ce token. Ici, nous allons choisir read et write.
  • Incluez également chat si vous utilisez le token avec l’API Conversations Chat.
• subdomain : votre sous-domaine Zendesk

En regroupant toutes ces valeurs et en les codant URL, vous obtiendrez une URL qui ressemble à ce qui suit :

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

où CLIENT_ID et SUBDOMAIN sont les seules différences pour votre propre URL.

2. Préparez l’appel cURL

Avant d’accéder à l’URL, créons l’appel cURL que nous exécuterons après. Ici, nous avons besoin de :

• grant_type : cela sera toujours authorization_code
• code : nous l’obtiendrons une fois que nous aurons autorisé l’accès depuis l’URL.
• client_id : votre ID client
• client_secret : votre secret client
• redirect_uri : comme à l’étape précédente, http://localhost:8080.
• scope : comme à l’étape précédente - read and write

Quand nous regroupons tout cela, nous obtenons une commande qui devrait ressembler à ce qui suit :

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

Attention : vous devriez déjà avoir CLIENT_ID et CLIENT_SECRET, mais nous n’avons pas encore AUTH_CODE.

3. Obtenez votre code d’autorisation

Allez à l’URL que nous avons générée à l’étape 1. Vous verrez une page comme celle-ci :

Cliquez sur Autoriser pour accorder l’accès et vous serez redirigé vers l’URL de redirection. Elle ressemblera à une page défectueuse, mais l’important est de chercher le code d’autorisation dans l’URL, c’est-à-dire tout ce qui se trouve après ?code=.

Copiez ce code et préparons-nous à la dernière étape. Le code d’autorisation n’est valable que brièvement. Si vous attendez plus de quelques minutes, vous risquez de devoir répéter l’étape ci-dessus pour obtenir un nouveau code.

4. Effectuez l’appel cURL pour obtenir votre token

Référez-vous à l’appel cURL que nous avons créé à l’étape 2 et qui ressemble à ce qui suit :

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

Remplacez AUTH_CODE par le code de l’étape 3 et exécutez la commande depuis une application de terminal. Vous recevrez une réponse sous la forme d’un objet JSON, comme ceci :

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

5. Testez le nouveau token

Il est toujours judicieux d’effectuer des tests pour vérifier que tout fonctionne comme prévu, alors faites-le maintenant. L’appel le plus facile est un simple appel GET à /api/v2/chats pour voir les informations de votre compte :

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

en remplaçant TOKEN par la valeur que nous avons obtenue à l’étape 4. 

Informations supplémentaires

client_type confidentiel

Les sections ci-dessus nous ont expliqué les flux d’authentification implicite et avec code d’autorisation. L’API Chat prend aussi en charge les flux d’authentification confidentielle avec les identifiants client. Ils sont décrits de façon plus détaillée dans la documentation de référence, dans la section portant sur les flux d’authentification confidentiels.

Pour les appels API utilisés par les administrateurs et les agents pour des choses comme les rapports sur les mesures, il peut être préférable d’obtenir un token OAuth par le biais d’un de ces flux d’authentification confidentiels. Vous devrez configurer la valeur client_type sur « confidential ». Par défaut, elle est configuré sur « public ». Vous pouvez le faire via l’API, comme suit :

1. Obtenez l’ID client

Avant tout, nous avons besoin de l’ID de votre nouveau client. Vous pouvez l’obtenir en utilisant votre nouveau token, avec l’appel suivant :

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

qui vous montrera tous vos clients. Vous n’en avez peut-être qu’un, mais si vous en avez plusieurs, choisissez celui que vous voulez mettre à jour et notez son ID.

2. Mettez la propriété client_type à jour

Maintenant que vous avez l’ID du client, vous pouvez effectuer l’appel cURL suivant pour mettre à jour la propriété client_type :

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"

Une fois que vous avez terminé, votre token peut être utilisé pour des points de terminaison restreints.