> ## 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 入站消息

> 接收传入消息、将消息标记为已读并显示输入指示器。

## 功能介绍

YCloud 会将入站 WhatsApp 消息投递到您的 Webhook 端点。接收事件后，您可以将消息标记为已读，或者在应用程序准备回复时显示临时的输入指示器。

## 准备工作

* 为 `whatsapp.inbound_message.received` 配置 Webhook 端点。
* 在处理事件前验证 `YCloud-Signature` 请求头。
* 存储入站消息 `id`。
* 连接接收消息的商业电话号码。

## 工作原理

1. 接收并验证 Webhook 事件。
2. 通过事件 `id` 对事件进行去重。
3. 提取入站消息 `id` 和内容。
4. （可选）将消息标记为已读。
5. 仅在正在准备回复时显示输入指示器。
6. 使用 WhatsApp Messages API 发送回复。

将一条消息标记为已读也会将该对话中更早的消息标记为已读。输入指示器会在您回复时或 25 秒后消失（以先发生者为准）。

## 请求

### 将消息标记为已读

`POST /whatsapp/inboundMessages/{id}/markAsRead`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  https://api.ycloud.com/v2/whatsapp/inboundMessages/INBOUND_MESSAGE_ID/markAsRead \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

### 显示输入指示器

`POST /whatsapp/inboundMessages/{id}/typing`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  https://api.ycloud.com/v2/whatsapp/inboundMessages/INBOUND_MESSAGE_ID/typing \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

此操作还会将消息标记为已读。

## 响应

请求成功将返回 HTTP `200`，无响应体。

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

该响应确认该操作已被接受。它不会向 WhatsApp 用户发送回复。

## 处理指南

* 在开始耗时的 AI 或业务处理之前确认（Acknowledge）Webhook。
* 如果您的业务场景依赖消息顺序，请保持每个会话的消息顺序。
* 显式处理每种受支持的入站 `type`，并保留不受支持的
  有效负载以供排查。
* 回复特定入站消息时使用消息上下文。

## 限制与排错

* 除非随后会发送回复，否则不要显示输入指示器。
* 在操作路径中使用入站消息 ID，而不是 Webhook 事件 ID。
* 确保 Webhook 处理具有幂等性，因为消息投递可能会重试。
* 如果操作失败，记录 YCloud `requestId`，不要记录消息
  内容或凭据。

<CardGroup cols={2}>
  <Card title="入站有效负载示例" icon="inbox" href="/zh/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples">
    查看文本、媒体、交互式、商务和系统消息的有效负载。
  </Card>

  <Card title="标记为已读 API" icon="check-double" href="/api-reference/whatsapp-inbound-messages/mark-message-as-read">
    查看完整的端点约定。
  </Card>
</CardGroup>


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