启用通知

目的

启用对模块上执行的操作的即时通知。

端点

POST /actions/watch

请求详情

请求 URL

{api-domain}/crm/{version}/actions/watch

支持的模块

潜在客户，Account，联系人，交易，活动，任务，案例，会议，电话，解决方案，产品，Vendors，价格表，报价单，Sales Orders，采购Orders，Invoices，预约，重新安排的预约历史，服务和自定义

标题

授权: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

范围

scope=ZohoCRM.notifications.{operation_type}

可能的操作类型

全部 - 完全访问通知数据
写入 - Edit即时通知详情
创建 - 启用即时通知

示例请求

Copiedcurl "https://www.zohoapis.com/crm/v6/actions/watch"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@inputData.json"

输入 JSON 键

token String, optional
此值在回调中返回，以确保通知来自Zoho CRM。最大字符长度为50。
可能的值： 示例：TOKEN_FOR_VERIFICATION_OF_1000000068001
notify_url String, mandatory
要通知的URL（POST请求）关于模块中发生的操作。
POSsible值：字符串值。示例：https://www.zoho.com/callback?authorization=Zoho-oauthtoken 1000.23dnsbbbh455jnn&key1=val1&key2=val2
channel_id long, mandatory
给定的值在回调URL主体中返回，以确保通知是针对特定频道的。
可能的值：频道ID。示例：1000000068001
channel_expiry String (ISO Date time), optional
表示即时通知的过期时间。该值最多可以设置为启用时间起一周内。如果未指定或设置超过一周，默认的过期时间为一小时。
可能的值：ISO 日期时间。示例：2023-02-02T10:30:00+05:30
return_affected_field_values boolean, optional
它将更新的字段及其对应的值返回到指定的 notify_url。
events JSONArray, mandatory
根据所选模块的特定操作进行订阅。
可能的值： JSON数组，格式为["{module_api_name}.{operation}", "{module_api_name}.{operation}"]。示例：["Leads.create","Sales_Orders.edit","Contacts.delete","users.all"]。可能的操作类型 - create, delete, edit, all
notification_condition JSONArray, optional
仅当模块的某些字段发生事件时才触发通知。
此数组包含以下键：
- type - 字符串，必填 - 表示通知是基于字段更新触发的。值为field_selection。
- module - JSON对象，必填 - 您希望接收字段事件通知的模块的API名称和ID。
- field_selection - JSON对象，必填 - 包含最多两个对象，每个对象具有以下键：
  - group_operator - 字符串，必填 - 支持的操作符有and和or。您可以使用这些操作符对字段进行分组。
  - group - JSON数组，必填 - 每个field JSON对象包含模块中字段的API名称和ID。每当这些字段上的任何操作发生时，您将根据其组操作符接收通知。
    注意：无论如何分组，group数组中最多可以有10个字段。
notify_on_related_action boolean, optional
在任何关联记录上有任何操作时启用通知。默认值为 TRUE。

要在URL上获取通知

在模块中触发任何启用通知的事件时，Zoho CRM会通过通知URL向用户发送通知。

示例输入

Copied{
    "watch": [
        {
            "channel_id": "10000",
            "events": [
                "Deals.all"
            ],
            "notification_condition": [
                {
                    "type": "field_selection",
                    "module": {
                        "api_name": "Deals",
                        "id": "554023000000000131"
                    },
                    "field_selection": {
                        "group_operator": "or",
                        "group": [
                            {
                                "field": {
                                    "api_name": "Stage",
                                    "id": "554023000000000525"
                                }
                            },
                            {
                                "group_operator": "and",
                                "group": [
                                    {
                                        "field": {
                                            "api_name": "Account_Name",
                                            "id": "554023000000000523"
                                        }
                                    },
                                    {
                                        "field": {
                                            "api_name": "Lead_Source",
                                            "id": "554023000000000535"
                                        }
                                    }
                                ]
                            }
                        ]
                    }
                }
            ],
            "channel_expiry": "2023-12-31T09:58:09+05:30",
            "token": "deals.all.notif",
            "return_affected_field_values": true,
            "notify_url": "https://webhook.site/2c9a0xxc20fa9"
        }
    ]
}

可能的错误

MANDATORY_NOT_FOUND HTTP 400
未找到一个必填字段（events, channel_id, notify_url, type, module）。请参阅响应中的“details”键以了解缺少哪个必填字段。
解决方法：确保输入中包含所有必填字段。
INVALID_DATA HTTP 400
令牌的长度超过50个字符。
解决方法：确保传递的令牌长度小于50个字符。
INVALID_DATA HTTP 400
原因：
- 您在请求体中传递了无效的数据和无效的数据类型。响应中的 "details" 键会给您提供无效数据的JSON路径。
- 您在notification_condition数组中的type键给出了一个无效的值。
- 您在notification_condition数组中提供了一个无效的模块名称。
- 您在group_operator键中提供了不支持的运算符。
- 您在notification_condition数组中提供了一个无效的字段API名称。
- field_selection 对象中有两个以上的对象。
- 您在group数组的一个或多个对象中传递了无效数据或错误的数据类型。
- group 数组有超过 10 个字段。
决议：
- 参考示例来构建请求主体。
- notification_condition 数组中 type 键的值是 field_selection。
- 请参阅支持的模块部分，了解此API可用于的模块列表。
- 支持的操作符是 and 和 or，用于 group_operator 键。
- 在notification_condition数组中指定一个有效的字段API名称。请参阅字段元数据API以获取字段API名称。
- field_selection对象最多只能包含两个对象。
- group 键必须是一个包含有效字段 API 名称和 ID 的 JSON 数组。请参阅示例输入。
- group 数组最多可以包含 10 个字段，无论它们如何分组。
EXPECTED_FIELD_MISSING HTTP 400
您未在请求正文中指定一个或多个预期字段，例如模块 API 名称或 ID。
解决方案：请参阅响应中的 "details" 键，以查找缺失键的 JSON 路径，并将其包含在请求正文中。
AMBIGUITY_DURING_PROCESSING HTTP 400
模块 API 名称及其 ID 在 notification_condition 数组中不匹配。
解决方法：请参考响应中的 "details" 键以查找模糊键。使用模块元数据 API 获取模块的 API 名称和 ID。
DEPENDENT_FIELD_MISSING HTTP 400
您在输入中指定了field_selection键，但没有指定type键。
解决方法：当您包含field_selection键时，type键在notification_condition数组中是必需的。

示例响应

Copied{
    "watch": [
        {
            "code": "SUCCESS",
            "details": {
                "events": [
                    {
                        "channel_expiry": "2023-08-02T16:59:50-11:00",
                        "resource_uri": "https://www.zohoapis.com/crm/v2/Deals",
                        "resource_id": "554023000000000131",
                        "resource_name": "Deals",
                        "channel_id": "10000"
                    }
                ]
            },
            "message": "Successfully subscribed for actions-watch of the given module",
            "status": "success"
        }
    ]
}

响应 JSON 键

server integer
表示通知发送到通知URL时的服务器时间。
query_paramsJSON object
表示在通知URL中指定的参数（如果有）。
resource_uriJSON object
表示您指定的模块的 URI，当在模块中执行某些操作时，您将收到通知。
ids JSON array
表示受影响记录的唯一ID。
affected_fields JSON array
Returns更新或修改的字段及其对应的值到指定的 notify_url。
operation string
表示在模块上执行的操作。
module string
表示您希望接收任何更改通知的模块名称。
channel_id long, mandatory
给定的值会在回调URL的主体中返回，以确保通知是针对特定频道的。
token string
表示在回调中发送回的值，以确保通知来自Zoho CRM。

在通知URL收到的示例响应

Copied{
  "server_time": 1718117126473,
  "query_params": {},
  "module": "Leads",
  "resource_uri": "https://www.zohoapis.com/crm/v2/Leads",
  "ids": [
    "5725767000003000064"
  ],
  "affected_fields": [],
  "operation": "insert",
  "channel_id": "1000000068001",
  "token": "TOKEN_FOR_VERIFICATION_OF_1000000068001"
}

启用子表单模块的通知

要在子表单中发生操作时接收通知，请在输入主体中指定子表单模块的 API 名称。虽然子表单在模块中显示为一个字段，但系统在添加子表单字段时会在内部创建一个单独的模块。使用GET Modules API来检索所有模块的列表。您可以通过搜索"generated_type": "subform"来识别您的子表单模块，这将与其对应的父模块相关联。

例如，在示例输入中，Project_Details子表单模块与Leads模块相关联。

有关更多详细信息，请参阅以下 Kaizen 文章：Kaizen #31 - 子表单 #API和Kaizen #124 - 使用Zoho CRM API 操作子表单。

示例输入

Copied{
    "watch": [
        {
            "channel_id": "10000",
            "events": [
                "Project_Details.all"  //Project_Details represents the API name of the subform module
            ],
            "notify_url": "https://webhook.site/9f5ba227-ce5a-4709-814d-b044c003d605",
            "return_affected_field_values": true  
        }
    ]
}

示例响应

Copied{
    "watch": [
        {
            "code": "SUCCESS",
            "details": {
                "events": [
                    {
                        "channel_expiry": "2025-02-16T02:11:26-08:00",
                        "resource_uri": "https://www.zohoapis.com/crm/v2/Project_Details",
                        "resource_id": "5725767000002102023",
                        "resource_name": "Project_Details",
                        "channel_id": "10000"
                    }
                ]
            },
            "message": "Successfully subscribed for actions-watch of the given module",
            "status": "success"
        }
    ]
}

启用多模块查找 (MxN) 的通知

要在 MxN 模块中发生操作时接收通知，请在输入主体中指定相应的链接模块的 API 名称。有关使用 Kaizen #125 使用 Zoho CRM API 操作多选查找字段 (MxN) 的更多详细信息，请参阅以下 Kaizen 帖子。

示例输入

Copied{
    "watch": [
        {
            "channel_id": "10000",
            "events": [
                "EmpXSkills.all" //EmpXSkills represents the API name of the linking module
            ],
            "notify_url": "https://webhook.site/9f5ba227-ce5a-4709-814d-b044csdfgre2",
            "return_affected_field_values": true
        }
    ]
}

示例响应

Copied{
    "watch": [
        {
            "code": "SUCCESS",
            "details": {
                "events": [
                    {
                        "channel_expiry": "2025-02-16T03:41:24-08:00",
                        "resource_uri": "https://www.zohoapis.com/crm/v2/EmpXSkills",
                        "resource_id": "5725767000002166520",
                        "resource_name": "EmpXSkills",
                        "channel_id": "10000"
                    }
                ]
            },
            "message": "Successfully subscribed for actions-watch of the given module",
            "status": "success"
        }
    ]
}

启用通知

目的

端点

请求详情

请求 URL

支持的模块

标题

范围

可能的操作类型

示例请求

输入 JSON 键

示例输入

可能的错误

示例响应

响应 JSON 键

在通知URL收到的示例响应

启用子表单模块的通知

示例输入

示例响应

启用多模块查找 (MxN) 的通知

示例输入

示例响应

核心功能

资源中心

关注我们

快速链接

更多资讯