How to retrieve notifications in Zoho

Retrieving notifications in Zoho CRM via the API requires the correct OAuth scopes and a valid, refreshed access token — get those two things right and the rest follows naturally.

Why this matters

When you need to programmatically read, create, update, or delete CRM notifications — for example, to build a custom alert dashboard or sync notification data to a third-party tool — you must ensure your OAuth client is authorised with the right permission scopes and that your token pipeline handles expiry gracefully. Without this foundation, every notification request will return a 401 or a permissions error before it even reaches the data.

> Beam Help is independent expert support for Zoho — we are not official Zoho support.

---

Step-by-step

Step 1. Confirm your OAuth client includes the notification-specific scopes before you generate or refresh any token. The four scopes you need are ZohoCRM.notifications.READ, ZohoCRM.notifications.CREATE, ZohoCRM.notifications.UPDATE, and ZohoCRM.notifications.DELETE. If you only want to retrieve (read) notifications, ZohoCRM.notifications.READ is the minimum required scope. ^[1]

Step 2. Make sure your broader CRM scope bundle is also present. Notification scopes sit alongside other CRM scopes such as ZohoCRM.modules.ALL, ZohoCRM.org.ALL, and ZohoCRM.coql.READ. All of these should be declared together when you register or update your OAuth client so a single token covers every operation your integration needs. ^[1]

Step 3. Establish a valid connection for the user before making any notification call. Your backend should look up the stored connection record (access token, refresh token, expiry timestamp) for the relevant user. If no record exists, the user must re-authenticate through the OAuth flow before any API call can proceed. ^[3]

Step 4. Implement proactive token refresh so your access token is always valid at request time. A reliable pattern is to check whether the current time is within 120 seconds of the token's expiry timestamp — if it is, call the refresh endpoint immediately, store the new accesstoken and updated tokenexpires_at back to your database, and then proceed with the notification request using the fresh token. ^[3]

Step 5. If a mid-request refresh is needed (for example, a long-running process where the token expires partway through), your refresh logic should fetch the latest refreshtoken from the database, call ZohoOAuth.refreshtokens(), verify that accesstoken is present in the response, and persist the updated values before returning the new token to the caller. If accesstoken is absent from the refresh response, treat the refresh as failed and surface an error rather than proceeding with a stale token. ^[2]

Step 6. Instantiate your Zoho CRM API client using the resolved access token and the correct API domain stored in the connection record. Pass the token-refresher callback into the client so it can handle expiry automatically during paginated or multi-step notification retrieval operations. ^[2]

Step 7. With a valid client in hand, call the appropriate notification tool or endpoint. In a chat/agent context, the tool execution layer wraps this as a named tool call (e.g. a get_notifications style tool), passes the relevant parameters, and streams status updates back to the caller while the request is in flight. ^[6]

Step 8. Handle the case where the API object could not be initialised — for instance, if the user's Zoho account is not connected or the refresh failed. In that scenario, surface a clear message such as "Zoho is not connected for this app. Please reconnect." rather than silently failing or returning empty data. ^[4]

---

Common pitfalls

• Missing notification scopes at registration time. If you add ZohoCRM.notifications.READ to your config but the OAuth client was originally registered without it, existing refresh tokens will not carry the new scope. You must re-authorise (re-run the OAuth consent flow) to get a token that includes the updated scope set. ^[1]

• Stale tokens causing silent 401s. If your refresh logic only triggers *after* a failed request rather than *before* it, you will see intermittent 401 errors on the first call of a session. The 120-second pre-emptive refresh window is specifically designed to prevent this race condition. ^[3]

• Refresh token not updated in the database. After a successful token refresh, both accesstoken and tokenexpiresat must be written back to the zohoconnections table. Failing to persist these means the next request will attempt to refresh again with the same (possibly already-consumed) refresh token, which can invalidate the session entirely. [^2, ^3]

• Using the wrong apptype. The getzohoapi function accepts an apptype parameter ("crm" or "desk"). Notification retrieval for Zoho CRM requires app_type="crm". Passing "desk" will route the request to the Zoho Desk client, which uses a completely different scope set and org-ID resolution path. ^[2]

---

What to check

• Scopes are present and active: Verify that ZohoCRM.notifications.READ (and any write scopes you need) appear in your registered OAuth client *and* in the token your application is currently using — not just in your config file. ^[1]
• Token refresh is persisting correctly: After any refresh event, query your zohoconnections table and confirm that accesstoken and tokenexpiresat reflect the newly issued values, not the previous ones. ^[3]
• Connection record exists for the user: Before running any notification retrieval, confirm that a row exists in zohoconnections for the target userid; if it is missing, the API client will be None and all downstream calls will fail silently. [^2, ^4]