Enable Notifications

Purpose

To enable instant notifications of actions performed on a module.

Request Details

Request URL

https://www.zohoapis.com/bigin/v1/actions/watch

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoBigin.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://www.zohoapis.com/bigin/v1/actions/watch"
-X POST
-d "@inputData.json"

Input JSON Keys

  • tokenString, optional

    To ensure that the notification is sent from Bigin, 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

To get notification on a URL

  • On trigger of any notification-enabled event in a module, Bigin sends a notification to the user through the notify URL.

Sample Input

Copied{
    "watch": [
       {
            "channel_id": "1000000068001",
            "events": [
                "Contacts.create"
            ],
            "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"
        }
    ]
}

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://www.zohoapis.com/bigin/v1/Contacts",
                        "resource_id": "1000000000045",
                        "resource_name": "Contacts",
                        "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://www.zohoapis.com/bigin/v1/Deals",
                        "resource_id": "1000000000047",
                        "resource_name": "Deals",
                        "channel_id": "1000000068002"
                    }
                ]
            },
            "message": "Successfully subscribed for actions-watch of the given module",
            "status": "success"
        }
    ]
}