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

# Meta Business Agent echo message created

> 存储通过 Public REST API 接入的 Meta Business Agent 发出的出站文本和媒体回显消息。

## 功能简介

订阅 `whatsapp.echo_message.created`。

当 YCloud 记录到通过 Public REST API 接入的 Meta Business Agent 的出站回显时，您将收到此事件。从 `whatsappMessage` 读取标准消息格式的内容；请勿将此事件用于客户入站消息。

当前约定在将回显作为标准 WhatsApp 消息公开的同时保持事件名称不变。Agent、交接（handover）以及收件箱路由字段不属于此载荷的一部分。

## 准备工作

1. 通过 [Public REST API](https://docs.ycloud.com/zh/api-reference/meta-business-agents/onboard) 接入 Agent。
2. 在同一账户中将一个处于活跃状态的 Webhook 终端节点订阅到 `whatsapp.echo_message.created`。
3. 针对原始请求体验证 `YCloud-Signature`，持久接收每个事件，并对其进行幂等处理。

> [!WARNING]
>
> 在控制台创建的 Agent 不会发送此客户 Webhook。它们的收件箱同步属于单独的流程。

有关终端节点设置，请参阅 [配置 Webhook](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md#subscribe-to-echo-and-handover-events)。

## 工作原理

所有示例均使用占位符标识符。请根据外层 `type` 进行路由并读取 `whatsappMessage`，而不是 `whatsappMetaBusinessAgent`、`whatsappEchoMessage` 或 `data`。

使用外层 `id` 对重复推送进行去重。外层 `createTime` 为 Webhook 事件时间；嵌套的消息时间字段为 RFC 3339 源时间。

* 使用 `id` 或 `wamid` 关联后续状态事件。
* 从 `text.body` 读取文本。对于媒体，请检查 `type` 和相应的内容对象。媒体 ID 不是公开下载 URL。
* 客户电话号码和 BSUID 彼此独立。当源回调同时提供两者时，事件会包含 `to` 以及 `recipientUserId` 或 `parentRecipientUserId`。缺失的身份标识将被省略，且不会相互推断。
* 当源回调提供有效的电话号码时，`from` 为商业显示电话号码。它并非派生自 `phoneNumberId`。
* 回复上下文会规范化为标准消息约定。例如，源 `context.id` 会显示为 `context.message_id`。
* 不包含 Agent、交接、路由、定价和对话字段。
* `status` 是处理回显时存储的状态；并不保证一定是 `sent`。
* 客户入站消息使用 [`whatsapp.inbound_message.received`](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples)。Business App 回显使用 [`whatsapp.smb.message.echoes`](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/whatsapp-business-app-sent-message-sync-webhook-examples)。

## 请求

YCloud 会在发送到您配置的 Webhook URL 的 HTTP `POST` 请求中发送这些 JSON 请求体。

## 响应

在持久接收每个事件后返回 `2xx` 响应。耗时任务请异步处理。

## 出站文本回显

### 请求

存储来自 whatsappMessage.text.body 的文本。id 和 wamid 用于关联后续状态事件。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_echo_text",
  "type": "whatsapp.echo_message.created",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "type": "text",
    "text": {
      "body": "Hello! How can I help you?"
    },
    "status": "sent",
    "createTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}
```

### 响应

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

### 说明

从 `whatsappMessage.text.body` 读取回显文本。使用 `id` 或 `wamid` 关联后续状态事件。

## 出站图片回显

### 请求

消息内容因类型而异。请将媒体 ID 视为服务商引用，而非公开下载 URL。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_echo_image",
  "type": "whatsapp.echo_message.created",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:00.000Z",
  "whatsappMessage": {
    "id": "IMAGE_MESSAGE_ID",
    "wamid": "wamid.IMAGE_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "type": "image",
    "image": {
      "id": "MEDIA_ID",
      "mime_type": "image/jpeg"
    },
    "status": "sent",
    "createTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}
```

### 响应

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

### 说明

使用 `type` 选择匹配的内容对象。将媒体 `id` 视为服务商引用。

### 相关示例

* [WhatsApp 回显消息已更新](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-updated)
* [WhatsApp Agent 交接已更新](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/whatsapp-meta-business-agent-handover-updated)
* [回显与 Agent 交接示例](https://docs.ycloud.com/zh/api-reference/webhook-reference/overview.md#echo-and-agent-handover-events)
* [完整载荷目录](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)


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