Comment lister les articles Zendesk Guide en utilisant l'API : un guide complet

Si vous cherchez à accéder par programmation au contenu de votre centre d'aide Zendesk, que ce soit pour créer un index de recherche personnalisé, créer des sauvegardes ou synchroniser des articles vers une autre plateforme, l'API Zendesk Guide est votre outil de prédilection. Mais comme beaucoup d'API REST (REST APIs), il peut être intimidant de se lancer. Il y a l'authentification à comprendre, la pagination à gérer et une variété de points de terminaison (endpoints) à choisir.

Ce guide vous explique tout ce que vous devez savoir pour lister et récupérer des articles depuis Zendesk Guide en utilisant l'API. Nous aborderons l'authentification, la réalisation de vos premières requêtes, la gestion de la pagination pour les grandes bibliothèques de contenu et des exemples de code concrets que vous pourrez adapter à vos besoins.

Ce dont vous aurez besoin pour commencer

Avant de plonger dans les appels d'API, assurez-vous d'avoir ces prérequis en place :

• Un compte Zendesk avec un accès administrateur ou agent : vous aurez besoin des autorisations appropriées pour générer des jetons API (API tokens) et accéder au contenu du centre d'aide.
• Un jeton API (API token) : généré depuis votre Centre d'administration Zendesk (nous aborderons cela à l'étape 1).
• Une connaissance de base des API REST (REST APIs) : compréhension des méthodes HTTP (GET, POST), du format JSON et des en-têtes de requête (request headers).
• Un outil pour effectuer des requêtes API : cela pourrait être cURL, Postman ou un environnement de programmation comme Python ou Node.js.
• Connaissance des limites de débit de votre plan : Zendesk applique différentes limites de requêtes en fonction de votre niveau d'abonnement.

En parlant de limites de débit, voici ce avec quoi vous travaillez en fonction de votre plan :

Si vous dépassez ces limites, vous recevrez une erreur 429. L'API suit les limites de requêtes par minute de l'API Support, et les requêtes dans une API ne sont pas comptabilisées dans la limite de débit de l'autre.

Comprendre la structure de l'API Zendesk Guide

L'API Zendesk Help Center est une API REST (REST API) qui vous permet d'interagir avec le contenu de votre base de connaissances par programmation. Avant d'effectuer des requêtes, il est utile de comprendre comment le contenu est organisé.

Zendesk Guide suit une structure hiérarchique :

• Les Catégories sont les conteneurs de niveau supérieur pour organiser le contenu.
• Les Sections se trouvent dans les catégories et regroupent les articles connexes.
• Les Articles sont les éléments de contenu réels (rubriques d'aide, FAQ, guides).

Lorsque vous listez des articles via l'API, vous pouvez récupérer tous les articles de votre centre d'aide ou filtrer par catégories ou sections spécifiques. L'API renvoie des réponses JSON contenant des métadonnées d'article telles que le titre, le contenu du corps, les informations sur l'auteur, le statut de brouillon, etc.

L'authentification utilise l'authentification de base (Basic Auth) avec votre adresse e-mail et un jeton API (API token). Le format est {adresse_email}/token:{api_token}, qui est encodé en Base64 pour l'en-tête d'autorisation (Authorization header).

Une remarque importante : les réponses sont toujours filtrées en fonction des autorisations de l'utilisateur effectuant la requête. Donc, si vous vous authentifiez en tant qu'utilisateur final plutôt qu'en tant qu'agent ou administrateur, vous ne verrez que les articles que cet utilisateur est autorisé à consulter.

Étape 1 : configurer l'authentification API

Pour commencer à utiliser l'API, vous avez besoin d'un jeton API (API token). Voici comment en générer un :

1. Connectez-vous à votre compte Zendesk en tant qu'administrateur.
2. Accédez à Centre d'administration → Canaux → API.
3. Cliquez sur l'onglet Paramètres.
4. Activez Accès par jeton si ce n'est pas déjà fait.
5. Cliquez sur le bouton + pour ajouter un nouveau jeton.
6. Donnez à votre jeton un nom descriptif (comme « Script d'exportation d'articles »).
7. Copiez le jeton immédiatement : Zendesk ne l'affiche qu'une seule fois.

Une fois que vous avez votre jeton, vous pouvez tester l'authentification avec une simple requête cURL :

curl https://{votre_sous_domaine}.zendesk.com/api/v2/help_center/articles \
  -v -u {votre_email}/token:{votre_api_token}

Remplacez {votre_sous_domaine} par votre sous-domaine Zendesk, {votre_email} par l'e-mail de votre compte et {votre_api_token} par le jeton que vous venez de générer.

Si l'authentification réussit, vous verrez un code d'état 200 et une réponse JSON avec vos articles. Si vous obtenez une erreur 401, vérifiez que votre jeton est actif et que votre combinaison e-mail/jeton est correcte.

Problèmes d'authentification courants :

• 401 Non autorisé : le jeton est inactif ou le format e-mail/jeton est incorrect.
• 403 Interdit : l'utilisateur n'a pas l'autorisation d'accéder à la ressource.
• 404 Introuvable : l'URL du point de terminaison (endpoint URL) est incorrecte.

Étape 2 : lister tous les articles avec un appel API de base

Maintenant que vous êtes authentifié, récupérons les articles. Le point de terminaison principal (primary endpoint) pour lister les articles est :

GET /api/v2/help_center/articles

Voici un exemple Python complet utilisant la bibliothèque requests :

import requests
from requests.auth import HTTPBasicAuth

subdomain = 'votre_sous_domaine'
email = 'votre_email@exemple.com'
api_token = 'votre_api_token'

url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles'

response = requests.get(
    url,
    auth=HTTPBasicAuth(f'{email}/token', api_token),
    headers={'Content-Type': 'application/json'}
)

data = response.json()
articles = data['articles']

for article in articles:
    if not article['draft']:  # Ignorer les brouillons
        print(f"{article['id']}: {article['title']}")

La réponse comprend un tableau articles où chaque objet article contient des champs tels que :

Par défaut, ce point de terminaison renvoie 30 articles par page. Si vous avez plus d'articles, vous devrez gérer la pagination (abordée à l'étape 3).

Étape 3 : gérer la pagination pour les grandes listes d'articles

La pagination est l'endroit où de nombreux développeurs restent bloqués. L'API Zendesk Guide prend en charge deux méthodes de pagination : la pagination par curseur (recommandée) et la pagination par offset.

La pagination par curseur est l'approche moderne et fonctionne en suivant les liens « next » dans la réponse de l'API. Elle est plus efficace pour les grands ensembles de données et n'a pas les restrictions de limite de pages de la pagination par offset.

Pour utiliser la pagination par curseur, ajoutez ?page[size]=100 à votre requête (100 est le maximum). Voici une implémentation Python complète qui récupère TOUS les articles sur toutes les pages :

import requests
from requests.auth import HTTPBasicAuth

def get_all_articles(subdomain, email, api_token):
    articles = []
    url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles?page[size]=100'

    while url:
        response = requests.get(
            url,
            auth=HTTPBasicAuth(f'{email}/token', api_token),
            headers={'Content-Type': 'application/json'}
        )

        if response.status_code != 200:
            print(f"Erreur : {response.status_code}")
            break

        data = response.json()
        articles.extend(data['articles'])

        # Obtenir l'URL de la page suivante à partir de l'objet links
        url = data.get('links', {}).get('next')

        print(f"Récupéré {len(articles)} articles jusqu'à présent...")

    return articles

all_articles = get_all_articles('votre_sous_domaine', 'votre_email', 'votre_jeton')
print(f"Nombre total d'articles : {len(all_articles)}")

La clé est de vérifier data['links']['next']. Lorsque vous atteignez la dernière page, cette valeur sera null et votre boucle se terminera.

La pagination par offset est l'ancienne méthode et est limitée à 100 pages maximum. Elle utilise les paramètres per_page et page. Zendesk recommande la pagination par curseur pour les nouvelles implémentations.

Lors de la pagination dans de grands ensembles de données, soyez attentif aux limites de débit. Si vous avez des milliers d'articles, envisagez d'ajouter un petit délai entre les requêtes :

import time

time.sleep(0.5)  # Délai de 500 ms

Étape 4 : filtrer et trier les articles

L'API offre plusieurs façons de filtrer et de trier vos listes d'articles.

Filtrage par étiquettes : Si vous utilisez des étiquettes d'article (disponibles sur les plans Professional et Enterprise), vous pouvez filtrer par celles-ci :

GET /api/v2/help_center/articles?label_names=photos,camera

Cela ne renvoie que les articles qui ont TOUTES les étiquettes spécifiées. La correspondance des étiquettes est sensible à la casse.

Tri : Utilisez les paramètres sort_by et sort_order pour contrôler l'ordre :

Exemple : /api/v2/help_center/articles?sort_by=updated_at&sort_order=desc

Exportations incrémentielles : Pour synchroniser les articles avec des systèmes externes, utilisez le point de terminaison incrémentiel avec un paramètre start_time :

GET /api/v2/help_center/incremental/articles?start_time=1704067200

Le start_time est un horodatage Unix epoch. Cela ne renvoie que les articles créés ou mis à jour depuis cette heure.

Liste par catégorie ou section : Pour obtenir les articles d'une catégorie spécifique :

GET /api/v2/help_center/categories/{category_id}/articles

Ou d'une section spécifique :

GET /api/v2/help_center/sections/{section_id}/articles

Chargement latéral des données associées : Pour réduire les appels API, vous pouvez charger latéralement les ressources associées :

GET /api/v2/help_center/articles?include=users,sections,categories

Cela inclut les objets utilisateur, section et catégorie complets dans la réponse, vous n'avez donc pas besoin d'effectuer des appels API distincts pour ces informations.

Cas d'utilisation courants et exemples de code

Voici quelques implémentations pratiques pour des scénarios courants :

Exporter tous les articles pour l'indexation de recherche : Ce script exporte tous les articles publiés vers un fichier JSON, en filtrant les brouillons et en incluant uniquement les champs essentiels :

import json
import requests
from requests.auth import HTTPBasicAuth

def export_articles_for_search(subdomain, email, api_token, output_file):
    articles = []
    url = f'https://{subdomain}.zendesk.com/api/v2/help_center/articles?page[size]=100'

    while url:
        response = requests.get(url, auth=HTTPBasicAuth(f'{email}/token', api_token))
        data = response.json()

        for article in data['articles']:
            if not article['draft']:
                articles.append({
                    'id': article['id'],
                    'title': article['title'],
                    'body': article['body'],
                    'url': article['html_url'],
                    'updated_at': article['updated_at']
                })

        url = data.get('links', {}).get('next')

    with open(output_file, 'w') as f:
        json.dump(articles, f, indent=2)

    print(f"Exporté {len(articles)} articles vers {output_file}")

Meilleures pratiques de gestion des erreurs : Gérez toujours les erreurs potentielles dans vos appels API :

response = requests.get(url, auth=auth)

if response.status_code == 429:
    # Limite de débit atteinte : attendre et réessayer
    time.sleep(60)
    response = requests.get(url, auth=auth)
elif response.status_code == 401:
    print("L'authentification a échoué : vérifiez votre jeton API")
    sys.exit(1)
elif response.status_code != 200:
    print(f"Erreur API : {response.status_code}")
    print(response.text)

Gérer le contenu de Zendesk Guide avec eesel AI

Bien que l'API Zendesk Guide vous donne un accès programmatique au contenu de votre centre d'aide, c'est dans la gestion et l'exploitation efficace de ce contenu qu'eesel AI entre en jeu.

Au lieu de créer des scripts personnalisés pour synchroniser les articles, notre agent IA se connecte directement à votre Zendesk Guide et apprend automatiquement à partir du contenu de votre centre d'aide. Cela signifie :

• Configuration sans code : connectez votre compte Zendesk et eesel AI importe automatiquement vos articles.
• Toujours à jour : lorsque vous mettez à jour des articles dans Zendesk, eesel AI apprend les modifications.
• Prise en charge multilingue : fonctionne avec les articles dans n'importe laquelle des plus de 80 langues prises en charge par Zendesk.
• Réponses intelligentes : notre IA répond aux questions des clients en utilisant le contenu de votre centre d'aide comme source de vérité.

Pour les équipes qui cherchent à créer un support basé sur l'IA sans les frais généraux d'ingénierie, eesel AI gère la complexité de la synchronisation, de l'indexation et de la récupération du contenu d'article approprié au bon moment. Vous pouvez commencer avec AI Copilot pour rédiger des réponses pour vos agents, puis passer à l'automatisation complète de AI Agent à mesure que vous gagnez en confiance.

Commencez à créer avec l'API Zendesk Guide dès aujourd'hui

Vous avez maintenant tout ce dont vous avez besoin pour commencer à travailler avec l'API Zendesk Guide. Voici un récapitulatif rapide :

1. Générez un jeton API (API token) depuis votre Centre d'administration Zendesk.
2. Effectuez des requêtes authentifiées en utilisant l'authentification de base (Basic Auth) avec votre e-mail et votre jeton.
3. Gérez la pagination en utilisant la pagination par curseur pour les grandes bibliothèques d'articles.
4. Filtrez et triez en utilisant les paramètres de requête pour obtenir exactement les données dont vous avez besoin.

Pour des fonctionnalités plus avancées telles que la création ou la mise à jour d'articles, la gestion des traductions ou l'utilisation des pièces jointes d'articles, consultez la documentation officielle de l'API Zendesk.

Et si vous cherchez à faire plus avec le contenu de votre centre d'aide : comme alimenter les réponses de l'IA, créer une recherche personnalisée ou créer des flux de travail automatisés : réfléchissez à la façon dont eesel AI peut vous aider à y parvenir plus rapidement sans écrire de code d'intégration personnalisé.