功能简介
自定义事件代表来自您的应用程序、网站、商店或后端系统的活动。只需定义一次事件架构,即可发送可供 YCloud 客户工作流使用的事件触发记录。准备工作
- 选择一个稳定的事件名称,避免因展示文案变更而修改。
- 确定与每个事件关联的联系人。
- 定义事件属性及其数据类型。
- 确定哪个系统时间戳代表活动发生的时间。
运作方式
- 创建事件定义。
- 随着架构的演进添加或更新属性定义。
- 使用完全相同的定义名称发送事件记录。
- 将每条记录与联系人 ID、电话号码或 Meta 用户名关联。
- 监控被拒绝的事件和架构不匹配情况。
请求
创建事件定义
POST /event/definitions
选择联系人标识符
对于使用objectType: CONTACT 定义的事件,请提供以下标识符之一:
每个事件仅使用一个标识符。如果您提供了多个标识符,数字类型的
objectId 优先级最高,其次是非空的 contactPhoneNumber,然后是 contactUsername。如果未找到数字联系人 ID,YCloud 将直接拒绝该请求,而不会尝试匹配电话号码或用户名。
使用保存在联系人上的 Meta 用户名,不带前导 @。contactUsername 是一个顶层请求字段,与 properties 分开。您无需将其添加到事件的属性定义中。
按电话号码发送事件
POST /event/events
按用户名发送事件
如果您知道联系人的 Meta 用户名,可以在不提供电话号码或联系人 ID 的情况下发送相同的事件。在此示例中,customer_demo 必须已保存为您账户中的联系人。
响应
创建定义会返回已保存的定义。200 以及一个空 JSON 对象。
架构演进
- 尽可能添加新的可选属性。
- 不要将现有的属性名称重复用于不同的含义。
- 在发送事件之前验证类型。
- 在不同环境中保持事件名称和属性名称的一致与稳定。
- 当不可避免地出现破坏性语义变更时,请对事件名称进行版本控制。
限制与问题排查
- 在发送事件记录之前,必须先存在对应的事件定义。
- 属性名称和值必须与定义相匹配。
- 对于
occurTime,请使用 RFC 3339 格式。 - 确保联系人标识符能够解析为您账户中的目标客户。
- 对于
contactUsername,请检查联系人是否已存在,以及 用户名是否与保存的值一致(不带前导@)。 - 省略您不希望 YCloud 使用的标识符。提供的电话号码优先级 高于用户名。
200响应仅确认已接收,并不代表下游自动化 已执行完成。
创建事件定义
查看定义和属性架构。
发送事件
查看事件记录请求契约。

