> ## 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.

# messenger.inbound_message.received

> 当收到来自客户的普通 Messenger 文本消息时触发。

在您的 Webhook 端点处使用 `messenger.inbound_message.received` 来处理此事件。

## 触发条件

当收到来自客户的普通 Messenger 文本消息时触发。

[配置 Webhook 端点](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)时，请订阅 `messenger.inbound_message.received`。

`from` 是客户的 Page-scoped ID (PSID)，`to` 是 Facebook Page ID。这些标识符不是电话号码。请保留 `text.body` 中的前导和尾随空白字符。

## 语法

YCloud 会向您配置的 Webhook URL 发送 HTTP `POST` 请求。以下结构展示了一种有效负载变体。尖括号中的值为占位符；其类型列在 **参数** 下。可选字段和其他变体详见下文。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "<ID>",
  "type": "messenger.inbound_message.received",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "messengerInboundMessage": {
    "id": "<ID>",
    "metaMessageId": "<META_MESSAGE_ID>",
    "from": "<FROM>",
    "to": "<TO>",
    "type": "<TYPE>",
    "text": {
      "body": "<BODY>"
    },
    "sendTime": "<SEND_TIME>",
    "createTime": "<CREATE_TIME>"
  }
}
```

## 参数

在处理 JSON 请求体之前，请验证 `YCloud-Signature` HTTP 请求头。请参阅[签名验证](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)。

### 事件外层结构

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `id` | string | 是 | 事件的唯一 ID。最小长度：`6`。最大长度：`128`。 |
| `type` | string | 是 | 固定为 `messenger.inbound_message.received`。 |
| `apiVersion` | string | 是 | 用于呈现此事件的 API 版本。 |
| `createTime` | string (date-time) | 是 | 创建此事件的时间，按 [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) 格式化。例如 `2022-06-01T12:00:00.000Z`。 |

### 事件有效负载

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `messengerInboundMessage` | object | 否 | 特定事件的 `messengerInboundMessage` 有效负载。 |

四个通用外层字段为必填项。有效负载字段取决于具体的事件变体。在每个对象表格中，当其父对象存在时， **必填** 规则适用。可选字段可以省略；示例中出现并不代表该字段是必填的。

#### messengerInboundMessage

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `id` | string | 是 | 十进制字符串形式的 YCloud 入站消息 ID。 |
| `metaMessageId` | string | 是 | Meta 消息 ID。 |
| `from` | string | 是 | 针对 Facebook Page 范围的客户 PSID。 |
| `to` | string | 是 | Facebook Page ID。 |
| `type` | string | 是 | 取值：`text`。 |
| `text` | object | 是 | 对象字段列在下方。 |
| `sendTime` | string (date-time) | 是 | 保存的源事件时间，采用 UTC RFC 3339 格式，精确到毫秒。 |
| `createTime` | string (date-time) | 是 | 本地持久化时间，采用 UTC RFC 3339 格式，精确到毫秒。 |
| `editCount` | integer | 否 | 由 Meta 提供的累计编辑次数。首次编辑前省略。 |
| `editTime` | string (date-time) | 否 | 保存的平台编辑时间，采用 UTC RFC 3339 格式，精确到毫秒。首次编辑前省略。 |

> [accordion] messengerInboundMessage.text
>
> | 参数 | 类型 | 必填 | 说明 |
> | - | - | - | - |
> | `body` | string | 是 | 非空文本。前导和尾随空格会被保留，并在比对重复请求时包含在内。最小长度：`1`。 |

## 示例

以下 JSON 是传递给您的接收器的请求体。ID、电话号码和其他账户值仅用于说明。

使用 messengerInboundMessage.id 关联重复的客户消息；保留文本空白字符。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_0123456789abcdef01234567",
  "type": "messenger.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:00.000Z",
  "messengerInboundMessage": {
    "id": "1308528868252065793",
    "metaMessageId": "m_EXAMPLE_IN_001",
    "from": "100800000000000",
    "to": "422500000000000",
    "type": "text",
    "text": {
      "body": "  Hello  "
    },
    "sendTime": "2026-10-20T02:00:00.000Z",
    "createTime": "2026-10-20T02:00:00.100Z"
  }
}
```

在验证签名并持久接收该事件后，返回 `2xx` 响应。耗时工作请异步处理。

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


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