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

# WhatsApp 出站回显消息已创建

> 存储出站文本与媒体回显消息，并关联其后续的状态更新。

## 什么是 WhatsApp 出站回显消息已创建

订阅 `whatsapp.echo_message.created`。

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

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

## 准备工作

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

<Warning>
  通过控制台创建的 Agent 不会发出此客户 Webhook。它们的收件箱同步属于单独的流程。
</Warning>

有关端点配置，请参见[配置 Webhook](/zh/api-reference/guides/api-fundamentals/configure-webhooks#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`](/zh/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples)。Business App 回显消息使用 [`whatsapp.smb.message.echoes`](/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 回显消息已更新](/zh/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-updated)
* [WhatsApp Agent 交接已更新](/zh/api-reference/guides/examples/webhook-examples/whatsapp-meta-business-agent-handover-updated)
* [回显与 Agent 交接示例](/zh/api-reference/guides/examples/webhook-examples/overview#echo-and-agent-handover-events)
* [完整负载目录](/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.