Skip to main content

功能简介

自定义事件代表来自您的应用程序、网站、商店或后端系统的活动。只需定义一次事件架构,即可发送可供 YCloud 客户工作流使用的事件触发记录。

准备工作

  • 选择一个稳定的事件名称,避免因展示文案变更而修改。
  • 确定与每个事件关联的联系人。
  • 定义事件属性及其数据类型。
  • 确定哪个系统时间戳代表活动发生的时间。

运作方式

  1. 创建事件定义。
  2. 随着架构的演进添加或更新属性定义。
  3. 使用完全相同的定义名称发送事件记录。
  4. 将每条记录与联系人 ID、电话号码或 Meta 用户名关联。
  5. 监控被拒绝的事件和架构不匹配情况。
事件定义属于契约规范。更改标签或描述比更改现有名称或属性的含义更安全。

请求

创建事件定义

POST /event/definitions

选择联系人标识符

对于使用 objectType: CONTACT 定义的事件,请提供以下标识符之一: 每个事件仅使用一个标识符。如果您提供了多个标识符,数字类型的 objectId 优先级最高,其次是非空的 contactPhoneNumber,然后是 contactUsername。如果未找到数字联系人 ID,YCloud 将直接拒绝该请求,而不会尝试匹配电话号码或用户名。 使用保存在联系人上的 Meta 用户名,不带前导 @。contactUsername 是一个顶层请求字段,与 properties 分开。您无需将其添加到事件的属性定义中。

按电话号码发送事件

POST /event/events

按用户名发送事件

如果您知道联系人的 Meta 用户名,可以在不提供电话号码或联系人 ID 的情况下发送相同的事件。在此示例中,customer_demo 必须已保存为您账户中的联系人。

响应

创建定义会返回已保存的定义。
成功接收的事件记录将返回 HTTP 200 以及一个空 JSON 对象。

架构演进

  • 尽可能添加新的可选属性。
  • 不要将现有的属性名称重复用于不同的含义。
  • 在发送事件之前验证类型。
  • 在不同环境中保持事件名称和属性名称的一致与稳定。
  • 当不可避免地出现破坏性语义变更时,请对事件名称进行版本控制。

限制与问题排查

  • 在发送事件记录之前,必须先存在对应的事件定义。
  • 属性名称和值必须与定义相匹配。
  • 对于 occurTime,请使用 RFC 3339 格式。
  • 确保联系人标识符能够解析为您账户中的目标客户。
  • 对于 contactUsername,请检查联系人是否已存在,以及 用户名是否与保存的值一致(不带前导 @)。
  • 省略您不希望 YCloud 使用的标识符。提供的电话号码优先级 高于用户名。
  • 200 响应仅确认已接收,并不代表下游自动化 已执行完成。

创建事件定义

查看定义和属性架构。

发送事件

查看事件记录请求契约。