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

# WhatsApp 渠道

> 消息如何在所有者和智能体之间传递，以及 WhatsApp 设定的限制。

zapbip 通过官方 WhatsApp Cloud API 与所有者对话，所有账号共用一个号码。

## 入站消息

所有者给号码发消息。zapbip 会校验每条通知的签名，即使 WhatsApp 投递了两次，每条消息也只保存一次，并按[路由规则](https://docs.zapbip.com/zh/concepts/routing.md)发给一个智能体。

| 所有者发送 | 智能体收到 |
| - | - |
| 文本、图片、视频、音频、语音消息、文档、贴纸 | 消息本身，媒体由 zapbip 保存 |
| 位置、联系人名片 | 消息本身 |
| 按钮或列表行的回复 | 选择，它会回答对应的问题 |
| 表情回应 | 该回应，路由给发出被回应消息的智能体；取消回应时到达的内容不带表情 |
| 其他类型的消息 | 什么也不发；会告诉所有者暂不支持这种类型 |

所有者发出的消息会打开 [24 小时窗口](https://docs.zapbip.com/zh/concepts/24-hour-window.md)。表情回应不会。

如果文件无法下载，智能体收到的消息会带有 `media_id: null` 和 `media_status: "unavailable"`，并请所有者重新发送。

## 出站消息

窗口内，所有类型都会立即发出。窗口外，消息进入队列，所有者会收到一条[通知](https://docs.zapbip.com/zh/concepts/owner-notices.md)。

| 类型 | 限制 |
| - | - |
| 文本 | 4,096 个字符 |
| 按钮 | 最多 3 个按钮，问题最多 1,024 个字符，标题最多 20 个字符 |
| 列表 | 最多 10 行，问题最多 1,024 个字符，按钮最多 20 个字符，行标题最多 24 个字符，行说明最多 72 个字符 |
| 表情回应 | 被回应的消息必须不超过 30 天、在同一对话中且未被删除 |
| 图片 | JPEG、PNG 或 WebP，最大 5 MB |
| 视频 | 3GP 或 MP4，最大 16 MB |
| 音频 | AAC、AMR、MP3、M4A 或 OGG，最大 16 MB |
| 文档 | PDF、Word、Excel、PowerPoint 或纯文本，最大 100 MB |
| 贴纸 | 静态 WebP，最大 100 KB |

zapbip 会拒绝违反限制的发送，工具会返回一个指明字段的错误。

## 投递状态

消息的 `delivery` 只会向前推进：`sent`、`delivered`、`read`。被 WhatsApp 拒绝的发送会变为 `failed`。已经是 `delivered` 或 `read` 的消息不会再变成 `failed`。

## 受限号码

当 WhatsApp 报告号码受限或账号被停用时，zapbip 会停止发送 24 小时，并向运维人员告警。这期间发送的消息会返回 `delivery: "failed"`。


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