Kaizen #14 - Notification API

Kaizen #14 - Notification API

Hello everyone!

Welcome back to another week in the Kaizen series!
This week, we will discuss the Notification API in detail.

What is a Notification API?
Notification API allows you to get instant notifications whenever an action is performed on the records of a module. The system notifies you of the event on the URL you provide. You can also enable notifications based on a specific operation like create, update, or delete.

Channels for notification

You can create individual channels to 'watch' set of activities performed on certain CRM modules like Leads/Contacts/Accounts etc.

Let us assume that you have an application with two code modules—Code module 1 processes data from the Sales Force Automation modules, and code module 2 processes data from the inventory modules. Therefore, it makes sense to create one channel for each code module and notify the user about a change in that code module from the respective channel.




Through the Notification APIs, you can also set the expiry time for instant notifications for every channel, and disable notifications, anytime.

Notification APIs allow you to


Enable Notifications
This API allows you to enable instant notifications for a channel.

Request URL: {{api-domain}}/crm/v2/actions/watch
Request Method: POST
Scope: ZohoCRM.notifications.ALL/CREATE

Here is a sample request that sends out notifications to the notify URL when a contact or a deal is created, or when an account is updated.

{
    "watch": [
        {
            "channel_id": "10000007828",
            "events": [
                "Contacts.create",
                "Accounts.edit",
                "Deals.create"
            ],
            "channel_expiry": "2020-02-02T10:30:00+05:30",
            "token": "contacts_and_deals7828",
        }
    ]
}

While enabling instant notifications, you can specify the following in the input:

Key and Data type
Description
notify_url (mandatory)
String
A valid URL that accepts data from the Notification API. Whenever any action gets triggered, the notification will be sent to this notify URL.
channel_id (mandatory)
String
The unique identification of that particular channel. The given value is sent back in the notification when an action happens in that channel.
events (mandatory)
JSON array
A JSON array of the module API name and the operation type (action on the records) that you want to be notified upon.
token
String, max of 50 characters
The given value is sent back in the notification URL body to ensure that the notification is sent from Zoho CRM.
By using this value, users can validate the notifications.
channel_expiry
DateTime
The expiry time of the channel in the ISO8601 format. After this time, notifications for the channel are not sent. 
The expiry can be a maximum of one day after the notifications were enabled for that channel. If you do not specify this value or set an expiry time beyond one day, the system considers the default expiration time of one hour.

Note
You can create a maximum of 100 channels (100 JSON objects, one for each channel) per API call.

Here is the response to the above POST request.

{
    "watch": [
        {
            "code": "SUCCESS",
            "details": {
                "events": [
                    {
                        "channel_expiry": "2020-01-10T19:20:23+05:30",
                        "resource_uri": "{{api-domain}}/crm/v2/Contacts",
                        "resource_id": "3652397000000002179",
                        "resource_name": "Contacts",
                        "channel_id": "10000007828"
                    },
                    {
                        "channel_expiry": "2020-01-10T19:20:23+05:30",
                        "resource_uri": "{{api-domain}}/crm/v2/Deals",
                        "resource_id": "3652397000000002181",
                        "resource_name": "Deals",
                        "channel_id": "10000007828"
                    },
                    {
                        "channel_expiry": "2020-01-10T19:20:23+05:30",
                        "resource_uri": "{{api-domain}}/crm/v2/Accounts",
                        "resource_id": "3652397000000002177",
                        "resource_name": "Accounts",
                        "channel_id": "10000007828"
                    }
                ]
            },
            "message": "Successfully subscribed for actions-watch of the given module",
            "status": "success"
        }
    ]
}

Where,
resource_uri is the request URL to access the module.
resource_id is the ID of the module (obtained from "{api-domain}/crm/v2/settings/module_api_name").

Here is the sample request body of the notification that Zoho CRM sends to the notify URL.

{
    "query_params": {},
    "module": "Contacts",
    "resource_uri": "{{api-domain}}/crm/v2/Contacts",
    "ids": [
        "3652397000001565035"
    ],
    "operation": "insert",
    "channel_id": "10000007828",
    "token": "contacts_deals_accounts_7828"
}

Get Notification Details
Use this API to get the list of all notifications a user has enabled.
You can also specify the channel_id to get the details of the notifications for that particular channel.

Request URL: {{api-domain}}/crm/v2/actions/watch
Request Method: GET
Scope: ZohoCRM.notifications.ALL/READ

Note
You can fetch a maximum of 200 channels per API call using this method.

Key and Data Type
Description
per_page
Integer
The number of channels you want to fetch per API call. The maximum is 200.
page
Integer
To get the list of records from the respective pages. The default value is 1.
module
String
The API name of the module to fetch notifications enabled for that module.
channel_id
String
The unique ID of the notification channel.

Example: 
{{api-domain}}/crm/v2/actions/watch?module=Leads&page=1&per_page=150&channel_id=10000007828

Update Notification Details
This API allows you to update the details of an existing notification like the token, the event which triggers the notification.

Request URL: {{api-domain}}/crm/v2/actions/watch
Request Method: PUT
Scope: ZohoCRM.notifications.ALL/WRITE/UPDATE
Mandatory parameter: channel_id

Below is an example of an input to update the details of the notification we enabled in the previous example.

{
    "watch": [
        {
            "channel_id": "10000007828",
            "events": [
                "Contacts.create",
                "Contacts.edit",
                "Deals.create"
            ],
            "channel_expiry": "2020-01-12T15:35:05+05:30",
            "token": "contacts_deals_7828",
        }
    ]
}

As you can see, we have updated the event in which a notification is triggered, and the token.

Note
  • Only the details you specify in the input will be updated. All other details you specified while enabling the notification will be removed. In this case, the notification for "Accounts.edit" will be disabled.
  • You can update a maximum of 100 channels per API call.

Update Specific Information of a Notification
Use this API when you want to update specific information of a notification by retaining the existing details.

Request URL: {{api-domain}}/crm/v2/actions/watch
Request Method: PATCH
Scope: ZohoCRM.notifications.ALL/WRITE/UPDATE
Mandatory parameter: channel_id

All other information like the input structure, limits are similar to the previous example.

Disable Notifications
Use this API to disable all (DELETE) or specific details (PATCH) of the notifications that you have enabled for a channel.

Request URL: {{api-domain}}/crm/v2/actions/watch
Request Method: DELETE/PATCH
Scope: ZohoCRM.notifications.ALL/WRITE/DELETE
Mandatory parameter: channel_ids (comma-separated channel IDs)

Example:
{{api-domain}}/crm/v2/actions/watch?channel_ids=10000007828,10000007000

Here is a sample input to disable specific notifications in a channel (PATCH). 

{
    "watch": [
        {
            "events": [
                "Contacts.create"
            ],
            "_delete_events": true
        }
    ]
}

The following table gives you the details of every key in the input.

Key and Data Type
Description
channel_id (mandatory)
Integer
The unique ID of the channel that you want to update or delete.
events (mandatory)
JSON array
The module API name (from the module metadata API) and the operation type (all, create, edit, and delete) that you want to disable notifications for.
_delete_events (mandatory for PATCH)
Boolean
Indicates whether you want to delete the events mentioned in the input. true deletes all the notifications for the events; false or not specifying this key in the input does not disable notifications.

Note
  • The DELETE request deletes the channel and the notifications enabled for that channel.
  • The PATCH request deletes only the events you specify in the events array, provided you have set the value for the _delete_events key as true.

We hope you found this post useful. Let us know your thoughts in the comment section or write to us at support@zohocrm.com.

Cheers!















    Access your files securely from anywhere

        Zoho Developer Community

            Bootcamp
            Community
            Pricing
            Webinars
            What's New
            Integrations
            Contact Support
            Contact Sales

              Zoho Survey Resources
                Features
                Survey Templates
                Integrations
                Community
                iOS Mobile Surveys
                Pricing
                Android Mobile Surveys
                Insurvey Blogs
                Insight Blogs
                Tips & Tricks





                              Latest Feature Updates


                                  Zoho Desk Resources

                                  • Desk Community Learning Series


                                  • Digest


                                  • Functions


                                  • Meetups


                                  • Kbase


                                  • Resources


                                  • Glossary


                                  • Desk Marketplace


                                  • MVP Corner


                                  • Word of the Day




                                      Zoho Marketing Automation
                                        Zoho SalesIQ Resources


                                              Manage your brands on social media
                                              Access Zoho Social

                                                Zoho Pagesense Resources


                                                    Zoho TeamInbox Resources

                                                      Zoho DataPrep Resources



                                                        Zoho CRM Plus Resources

                                                          Zoho Books Resources


                                                            Zoho Subscriptions Resources

                                                              Zoho Projects Resources


                                                                Zoho Sprints Resources


                                                                  Qntrl Resources


                                                                    Zoho Creator Resources



                                                                        Zoho Campaigns Resources


                                                                          Zoho CRM Resources

                                                                          • CRM Community Learning Series

                                                                            CRM Community Learning Series


                                                                          • Kaizen

                                                                            Kaizen

                                                                          • Functions

                                                                            Functions

                                                                          • Meetups

                                                                            Meetups

                                                                          • Kbase

                                                                            Kbase

                                                                          • Resources

                                                                            Resources

                                                                          • Digest

                                                                            Digest

                                                                          • CRM Marketplace

                                                                            CRM Marketplace

                                                                          • MVP Corner

                                                                            MVP Corner





                                                                              Design. Discuss. Deliver.

                                                                              Create visually engaging stories with Zoho Show.

                                                                              Get Started Now