> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 跟踪自定义事件

> 定义业务事件并将客户活动发送到 YCloud。

## 功能简介

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

## 准备工作

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

## 运作方式

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

事件定义属于契约规范。更改标签或描述比更改现有名称或属性的含义更安全。

## 请求

### 创建事件定义

`POST /event/definitions`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/event/definitions \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "order_completed",
    "label": "Order completed",
    "description": "A customer completed an order.",
    "objectType": "CONTACT",
    "properties": [
      {
        "name": "order_value",
        "label": "Order value",
        "type": "NUMBER"
      }
    ]
  }'
```

### 选择联系人标识符

对于使用 `objectType: CONTACT` 定义的事件，请提供以下标识符之一：

| 字段 | YCloud 如何识别联系人 |
| - | - |
| `objectId` | 使用您账户中现有联系人的数字 ID。如果联系人不存在，则请求失败。 |
| `contactPhoneNumber` | 在您的账户中查找 E.164 电话号码，如果不存在匹配项，则创建联系人。 |
| `contactUsername` | 匹配您账户中现有联系人已保存的 Meta 用户名。如果不存在匹配项，请求将失败且不会创建联系人。 |

每个事件仅使用一个标识符。如果您提供了多个标识符，数字类型的 `objectId` 优先级最高，其次是非空的 `contactPhoneNumber`，然后是 `contactUsername`。如果未找到数字联系人 ID，YCloud 将直接拒绝该请求，而不会尝试匹配电话号码或用户名。

使用保存在联系人上的 Meta 用户名，不带前导 `@`。`contactUsername` 是一个顶层请求字段，与 `properties` 分开。您无需将其添加到事件的属性定义中。

### 按电话号码发送事件

`POST /event/events`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/event/events \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "eventName": "order_completed",
    "occurTime": "2026-07-16T12:00:00.000Z",
    "contactPhoneNumber": "+16315551111",
    "properties": {
      "order_value": 99.9
    }
  }'
```

### 按用户名发送事件

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/event/events \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "eventName": "order_completed",
    "occurTime": "2026-07-16T12:00:00.000Z",
    "contactUsername": "customer_demo",
    "properties": {
      "order_value": 99.9
    }
  }'
```

## 响应

创建定义会返回已保存的定义。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "order_completed",
  "label": "Order completed",
  "objectType": "CONTACT",
  "properties": [
    {
      "name": "order_value",
      "label": "Order value",
      "type": "NUMBER"
    }
  ]
}
```

成功接收的事件记录将返回 HTTP `200` 以及一个空 JSON 对象。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
Content-Type: application/json

{}
```

## 架构演进

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

## 限制与问题排查

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

<CardGroup cols={2}>
  <Card title="创建事件定义" icon="list-check" href="/api-reference/custom-events/create-an-event-definition">
    查看定义和属性架构。
  </Card>

  <Card title="发送事件" icon="bolt" href="/api-reference/custom-events/send-an-event">
    查看事件记录请求契约。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.