Comment récupérer les notifications dans Zoho

La récupération des notifications dans Zoho CRM via l'API nécessite les bons scopes OAuth et un jeton d'accès valide et actualisé — maîtrisez ces deux points et le reste suivra naturellement.

Pourquoi c'est important

Lorsque vous devez lire, créer, mettre à jour ou supprimer des notifications CRM par programmation — par exemple pour créer un tableau de bord d'alertes personnalisé ou synchroniser des données de notifications avec un outil tiers — vous devez vous assurer que votre client OAuth est autorisé avec les bons scopes de permission et que votre pipeline de jetons gère l'expiration de manière appropriée. Sans cette base, chaque requête de notification renverra une erreur 401 ou une erreur de permissions avant même d'atteindre les données.

> Beam Help est un support expert indépendant pour Zoho — nous ne sommes pas le support officiel de Zoho.

---

Étape par étape

Étape 1. Confirmez que votre client OAuth inclut les scopes spécifiques aux notifications avant de générer ou d'actualiser un jeton. Les quatre scopes dont vous avez besoin sont ZohoCRM.notifications.READ, ZohoCRM.notifications.CREATE, ZohoCRM.notifications.UPDATE et ZohoCRM.notifications.DELETE. Si vous souhaitez uniquement récupérer (lire) les notifications, ZohoCRM.notifications.READ est le scope minimum requis. ^[1]

Étape 2. Assurez-vous que votre ensemble de scopes CRM plus large est également présent. Les scopes de notifications coexistent avec d'autres scopes CRM tels que ZohoCRM.modules.ALL, ZohoCRM.org.ALL et ZohoCRM.coql.READ. Tous ces scopes doivent être déclarés ensemble lors de l'enregistrement ou de la mise à jour de votre client OAuth, afin qu'un seul jeton couvre toutes les opérations dont votre intégration a besoin. ^[1]

Étape 3. Établissez une connexion valide pour l'utilisateur avant d'effectuer tout appel de notification. Votre backend doit rechercher l'enregistrement de connexion stocké (jeton d'accès, jeton de rafraîchissement, horodatage d'expiration) pour l'utilisateur concerné. Si aucun enregistrement n'existe, l'utilisateur doit se ré-authentifier via le flux OAuth avant qu'un appel API puisse être effectué. ^[3]

Étape 4. Mettez en place un rafraîchissement proactif du jeton afin que votre jeton d'accès soit toujours valide au moment de la requête. Un modèle fiable consiste à vérifier si l'heure actuelle se situe dans les 120 secondes précédant l'horodatage d'expiration du jeton — si c'est le cas, appelez immédiatement l'endpoint de rafraîchissement, enregistrez le nouvel accesstoken et le tokenexpires_at mis à jour dans votre base de données, puis procédez à la requête de notification avec le jeton actualisé. ^[3]

Étape 5. Si un rafraîchissement en cours de requête est nécessaire (par exemple, un processus de longue durée où le jeton expire en cours d'exécution), votre logique de rafraîchissement doit récupérer le dernier refreshtoken depuis la base de données, appeler ZohoOAuth.refreshtokens(), vérifier que accesstoken est présent dans la réponse, et persister les valeurs mises à jour avant de retourner le nouveau jeton à l'appelant. Si accesstoken est absent de la réponse de rafraîchissement, considérez le rafraîchissement comme échoué et signalez une erreur plutôt que de continuer avec un jeton périmé. ^[2]

Étape 6. Instanciez votre client API Zoho CRM en utilisant le jeton d'accès résolu et le domaine API correct stocké dans l'enregistrement de connexion. Transmettez le callback de rafraîchissement du jeton au client afin qu'il puisse gérer l'expiration automatiquement lors des opérations de récupération de notifications paginées ou en plusieurs étapes. ^[2]

Étape 7. Une fois le client valide en main, appelez l'outil ou l'endpoint de notification approprié. Dans un contexte de chat/agent, la couche d'exécution des outils encapsule cela sous forme d'appel d'outil nommé (par exemple, un outil de type get_notifications), transmet les paramètres pertinents et diffuse les mises à jour de statut à l'appelant pendant que la requête est en cours. ^[6]

Étape 8. Gérez le cas où l'objet API n'a pas pu être initialisé — par exemple, si le compte Zoho de l'utilisateur n'est pas connecté ou si le rafraîchissement a échoué. Dans ce cas, affichez un message clair tel que "Zoho is not connected for this app. Please reconnect." plutôt que d'échouer silencieusement ou de retourner des données vides. ^[4]

---

Erreurs courantes

• Scopes de notifications manquants lors de l'enregistrement. Si vous ajoutez ZohoCRM.notifications.READ à votre configuration mais que le client OAuth a été enregistré à l'origine sans ce scope, les jetons de rafraîchissement existants ne porteront pas le nouveau scope. Vous devez ré-autoriser (relancer le flux de consentement OAuth) pour obtenir un jeton incluant l'ensemble de scopes mis à jour. ^[1]

• Jetons périmés provoquant des erreurs 401 silencieuses. Si votre logique de rafraîchissement ne se déclenche qu'*après* une requête échouée plutôt qu'*avant*, vous verrez des erreurs 401 intermittentes lors du premier appel d'une session. La fenêtre de rafraîchissement préventif de 120 secondes est spécifiquement conçue pour éviter cette situation de compétition. ^[3]

• Jeton de rafraîchissement non mis à jour dans la base de données. Après un rafraîchissement de jeton réussi, accesstoken et tokenexpiresat doivent tous deux être réécrits dans la table zohoconnections. Ne pas persister ces valeurs signifie que la prochaine requête tentera à nouveau un rafraîchissement avec le même jeton de rafraîchissement (potentiellement déjà consommé), ce qui peut invalider entièrement la session. [^2, ^3]

• Utilisation d'un apptype incorrect. La fonction getzohoapi accepte un paramètre apptype ("crm" ou "desk"). La récupération des notifications pour Zoho CRM nécessite app_type="crm". Passer "desk" acheminera la requête vers le client Zoho Desk, qui utilise un ensemble de scopes et un chemin de résolution d'ID d'organisation entièrement différents. ^[2]

---

Ce qu'il faut vérifier

• Les scopes sont présents et actifs : Vérifiez que ZohoCRM.notifications.READ (et tous les scopes d'écriture dont vous avez besoin) apparaissent dans votre client OAuth enregistré *et* dans le jeton actuellement utilisé par votre application — pas seulement dans votre fichier de configuration. ^[1]
• Le rafraîchissement du jeton est correctement persisté : Après tout événement de rafraîchissement, interrogez votre table zohoconnections et confirmez que accesstoken et tokenexpiresat reflètent les valeurs nouvellement émises, et non les précédentes. ^[3]
• L'enregistrement de connexion existe pour l'utilisateur : Avant d'exécuter toute récupération de notifications, confirmez qu'une ligne existe dans zohoconnections pour le userid cible ; si elle est absente, le client API sera None et tous les appels en aval échoueront silencieusement. [^2, ^4]