Enable Notifications
Purpose
To enable instant notifications of actions performed on a module.
Endpoints
Request Details
Request URL
{api-domain}/crm/v2/actions/watch
Header
Authorization: Zoho-oauthtoken 100xx.d92d4xxxxxxxxxxxxx15f52
Scope
scope=ZohoCRM.notifications.{operation_type}
Possible operation types
ALL - Full access to notification data
WRITE - Edit instant notification details
CREATE - Enable instant notifications
Sample Request
Copiedcurl "https://zylkercorp.zohoplatform.com/crm/v2/actions/watch"
-X POST
-H "Authorization: Zoho-oauthtoken 100xxx.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@inputData.json"
Copied//Get instance of NotificationOperations Class
let notificationOperations = new ZCRM.Notification.Operations();
//Get instance of BodyWrapper Class that will contain the request body
let bodyWrapper = new ZCRM.Notification.Model.BodyWrapper();
//Array of Notification instances
let notificationsArray = [];
//Get instance of Notification Class
let notification1 = new ZCRM.Notification.Model.Notification();
//Set channel Id of the Notification
notification1.setChannelId(16800211n);
let events = ["Deals.all"];
//To subscribe based on particular operations on given modules.
notification1.setEvents(events);
//To set the expiry time for instant notifications.
notification1.setChannelExpiry(new Date(2020,10,10,10,20,0));
//To ensure that the notification is sent from Vertical Solutions, by sending back the given value in notification URL body.
//By using this value, user can validate the notifications.
notification1.setToken("TOKEN_FOR_VERIFICATION_OF_168002");
//URL to be notified (POST request)
notification1.setNotifyUrl("https://zylkercorp.zohoplatform.com");
//Add Notification instance to the array
notificationsArray.push(notification1);
//Get instance of Notification Class
let notification2 = new ZCRM.Notification.Model.Notification();
//Set channel Id of the Notification
notification2.setChannelId(106800211n);
let events2 = ["Accounts.all"];
//To subscribe based on particular operations on given modules.
notification2.setEvents(events2);
//To set the expiry time for instant notifications.
notification2.setChannelExpiry(new Date(2020,11,10,10,0,0));
//To ensure that the notification is sent from Vertical Solutions, by sending back the given value in notification URL body.
//By using this value, user can validate the notifications.
notification2.setToken("TOKEN_FOR_VERIFICATION_OF_16800211");
//URL to be notified (POST request)
notification2.setNotifyUrl("https://zylkercorp.zohoplatform.com");
//Add Notification instance to the array
notificationsArray.push(notification2);
//Set the array to notifications in BodyWrapper instance
bodyWrapper.setWatch(notificationsArray);
//Call enableNotifications method that takes BodyWrapper instance as parameter
let response = await notificationOperations.enableNotifications(bodyWrapper);
Copiedvar listener = 0;
class EnableNotifications {
async enableNotification() {
var url = "https://zylkercorp.zohoplatform.com/crm/v2/actions/watch"
var parameters = new Map()
var headers = new Map()
var token = {
clientId:"1000.NPY9M1V0XXXXXXXXXXXXXXXXXXXF7H",
redirectUrl:"http://127.0.0.1:5500/redirect.html",
scope:"ZohoCRM.notifications.ALL,ZohoCRM.users.ALL,ZohoCRM.bulk.read,ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,Aaaserver.profile.Read,ZohoCRM.org.ALL,profile.userphoto.READ,ZohoFiles.files.ALL,ZohoCRM.bulk.ALL,ZohoCRM.settings.variable_groups.ALL"
}
var accesstoken = await new EnableNotifications().getToken(token)
headers.set("Authorization", "Zoho-oauthtoken " + accesstoken)
var requestMethod = "POST"
var reqBody ={
"watch": [
{
"channel_id": "1068001",
"events": [
"Solutions.create",
"Price_Books.create",
"Contacts.create",
"Solutions.edit"
],
"channel_expiry": "2021-02-02T10:30:00+05:30",
"token": "TOKEN_FOR_VERIFICATION_OF_1068001",
"notify_url": "https://www.zoho.com/callback?authorization=Zoho-oauthtoken 1000.23dXXXXXXXXX5jnn&key1=val1&key2=val2"
}
]
}
var params = "";
parameters.forEach(function(value, key) {
if (parameters.has(key)) {
if (params) {
params = params + key + '=' + value + '&';
}
else {
params = key + '=' + value + '&';
}
}
});
var apiHeaders = {};
if(headers) {
headers.forEach(function(value, key) {
apiHeaders[key] = value;
});
}
if (params.length > 0){
url = url + '?' + params.substring(0, params.length - 1);
}
var requestObj = {
uri : url,
method : requestMethod,
headers : apiHeaders,
body : JSON.stringify(reqBody),
encoding: "utf8",
allowGetBody : true,
throwHttpErrors : false
};
var result = await new EnableNotifications().makeAPICall(requestObj);
console.log(result.status)
console.log(result.response)
}
async getToken(token) {
if(listener == 0) {
window.addEventListener("storage", function(reponse) {
if(reponse.key === "access_token" && (reponse.oldValue != reponse.newValue || reponse.oldValue == null)){
location.reload();
}
if(reponse.key === "access_token"){
sessionStorage.removeItem("__auth_process");
}
}, false);
listener = 1;
if(sessionStorage.getItem("__auth_process")) {
sessionStorage.removeItem("__auth_process");
}
}
["granted_for_session", "access_token","expires_in","expires_in_sec","location","api_domain","state","__token_init","__auth_process"].forEach(function (k) {
var isKeyExists = localStorage.hasOwnProperty(k);
if(isKeyExists) {
sessionStorage.setItem(k, localStorage[k]);
}
localStorage.removeItem(k);
});
var valueInStore = sessionStorage.getItem("access_token");
var tokenInit = sessionStorage.getItem("__token_init");
if(tokenInit != null && valueInStore != null && Date.now() >= parseInt(tokenInit) + 59 * 60 * 1000){ // check after 59th minute
valueInStore = null;
sessionStorage.removeItem("access_token");
}
var auth_process = sessionStorage.getItem("__auth_process");
if ((valueInStore == null && auth_process == null) || (valueInStore == 'undefined' && (auth_process == null || auth_process == "true"))) {
var accountsUrl = "https://zylkercorp.zohoplatform.com/oauth/v2/auth"
var clientId;
var scope;
var redirectUrl;
if(token != null) {
clientId = token.clientId;
scope = token.scope;
redirectUrl = token.redirectUrl;
}
var fullGrant = sessionStorage.getItem("full_grant");
var grantedForSession = sessionStorage.getItem("granted_for_session");
if(sessionStorage.getItem("__token_init") != null && ((fullGrant != null && "true" == full_grant) || (grantedForSession != null && "true" == grantedForSession))) {
accountsUrl += '/refresh';
}
if (clientId && scope) {
sessionStorage.setItem("__token_init", Date.now());
sessionStorage.removeItem("access_token");
sessionStorage.setItem("__auth_process", "true");
window.open(accountsUrl + "?" + "scope" + "=" + scope + "&"+ "client_id" +"=" + clientId + "&response_type=token&state=zohocrmclient&redirect_uri=" + redirectUrl);
["granted_for_session", "access_token","expires_in","expires_in_sec","location","api_domain","state","__token_init","__auth_process"].forEach(function (k) {
var isKeyExists = localStorage.hasOwnProperty(k);
if(isKeyExists){
sessionStorage.setItem(k, localStorage[k]);
}
localStorage.removeItem(k);
});
valueInStore = sessionStorage.getItem("access_token");
}
}
if(token != null && valueInStore != 'undefined'){
token.accessToken = valueInStore;
}
return token.accessToken;
}
async makeAPICall(requestDetails) {
return new Promise(function (resolve, reject) {
var body, xhr, i;
body = requestDetails.body || null;
xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.open(requestDetails.method, requestDetails.uri, true);
for (i in requestDetails.headers) {
xhr.setRequestHeader(i, requestDetails.headers[i]);
}
xhr.send(body);
xhr.onreadystatechange = function() {
if(xhr.readyState == 4) {
resolve(xhr);
}
}
})
}
}
Input JSON Keys
- tokenString, optional
To ensure that the notification is sent from Zoho CRM, by sending back the given value in notification URL body. By using this value, user can validate the notifications. Maximum length of characters is 50.
Possible values: Example: TOKEN_FOR_VERIFICATION_OF_1000000068001 - notify_urlString, mandatory
URL to be notified (POST request). Whenever any action gets triggered, the notification will be sent through this notify url.
Possible values: String values. Example: https://www.zoho.com/callback?authorization=Zoho-oauthtoken 1000.23dnsbbbh455jnn&key1=val1&key2=val2 - channel_idlong, mandatory
The given value is sent back in notification URL body to make sure that the notification is for a particular channel.
Possible values: Channel ID. Example: 1000000068001 - channel_expiryString (ISO Date time), optional
To set the expiry time for instant notifications. Maximum of only one day from the time they were enabled. If it is not specified or set for more than a day, the default expiry time is for one hour.
Possible values: ISO Date time. Example: 2018-02-02T10:30:00+05:30 - events JSONArray["{module_api_name}.{operation}", "{module_api_name}.{operation}"], mandatory
To subscribe based on particular operations on selected modules.
Possible values: JSON Array of the provided format. Example: ["Leads.create","Sales_Orders.edit","Contacts.delete"]. Possible operation types - create, delete, edit, all - notify_on_related_actionboolean, optional
To enable notification when there is any action on any associated records. The default value is FALSE.
On trigger of any notification-enabled event in a module, Zoho CRM sends a notification to the user through the notify URL.
Sample Input
Copied{
"watch": [
{
"channel_id": "1000000068001",
"events": [
"Solutions.create",
"Price_Books.create",
"Contacts.create",
"Solutions.edit"
],
"channel_expiry": "2018-02-02T10:30:00+05:30",
"token": "TOKEN_FOR_VERIFICATION_OF_1000000068001",
"notify_url": "https://www.zoho.com/callback?authorization=Zoho-oauthtoken 1000.23dnsbbbh455jnn&key1=val1&key2=val2"
},
{
"channel_id": "1000000068002",
"events": [
"Deals.all"
],
"channel_expiry": "2018-02-02T10:30:00+05:30",
"token": "TOKEN_FOR_VERIFICATION_OF_1000000068002",
"notify_url": "https://www.zoho.com/callback?authorization=Zoho-oauthtoken 1000.23dnsbbbh455jnn&key1=val1&key2=val2&key3=val1"
},
{
"channel_id": "1000000068003",
"events": [
"Cases.all"
],
"channel_expiry": "2018-02-02T10:30:00+05:30",
"token": "TOKEN_FOR_VERIFICATION_OF_1000000068003",
"notify_url": "https://www.zoho.com/callback?authorization=Zoho-oauthtoken 1000.23dnsbbbh455jnn&key1=val1"
}
]
}
Possible Errors
- MANDATORY_NOT_FOUND HTTP 202
One of the mandatory fields (events, channel_id, notify_url) is not found. Refer to the "details" key in the response to know which mandatory field is missing.
Resolution:Ensure that all the mandatory fields are given in the input. - INVALID_DATA HTTP 202
The length of the token is greater than 50 characters.
Resolution: Ensure that the token passed is less than 50 characters in length.
Sample Response
Copied{
"watch": [
{
"code": "SUCCESS",
"details": {
"events": [
{
"channel_expiry": "2018-02-02T10:30:00+05:30",
"resource_uri": "https://zylkercorp.zohoplatform.com/crm/v2/Solutions",
"resource_id": "1000000000091",
"resource_name": "Solutions",
"channel_id": "1000000068001"
},
{
"channel_expiry": "2018-02-02T10:30:00+05:30",
"resource_uri": "https://zylkercorp.zohoplatform.com/crm/v2/Contacts",
"resource_id": "1000000000045",
"resource_name": "Contacts",
"channel_id": "1000000068001"
},
{
"channel_expiry": "2018-02-02T10:30:00+05:30",
"resource_uri": "https://zylkercorp.zohoplatform.com/crm/v2/Price_Books",
"resource_id": "1000000000097",
"resource_name": "Price_Books",
"channel_id": "1000000068001"
}
]
},
"message": "Successfully subscribed for actions-watch of the given module",
"status": "success"
},
{
"code": "SUCCESS",
"details": {
"events": [
{
"channel_expiry": "2018-02-02T10:30:00+05:30",
"resource_uri": "https://zylkercorp.zohoplatform.com/crm/v2/Deals",
"resource_id": "1000000000047",
"resource_name": "Deals",
"channel_id": "1000000068002"
}
]
},
"message": "Successfully subscribed for actions-watch of the given module",
"status": "success"
},
{
"code": "SUCCESS",
"details": {
"events": [
{
"channel_expiry": "2018-02-02T10:30:00+05:30",
"resource_uri": "https://zylkercorp.zohoplatform.com/crm/v2/Cases",
"resource_id": "1000000000089",
"resource_name": "Cases",
"channel_id": "1000000068003"
}
]
},
"message": "Successfully subscribed for actions-watch of the given module",
"status": "success"
}
]
}