WhatsApp worker 用于在应用中集成 WhatsApp 的消息收发、会话管理、群组操作与事件消费。它支持两条集成路径：一是通过 whatsmeow 实现的关联设备（linked-device）会话，二是复用已有的 Meta Cloud API 账号。使用者应先查看当前注册的 whatsapp::* 函数目录及其 schema，再按实际需求选择操作。
关联设备模式使用选定的 session_id。sessions::create 仅创建离线元数据；sessions::start 在创建或重启后显式建立连接。配对可通过 sessions::qr 或 sessions::pair_code 完成，配对材料只能提供给账号所有者。若需要使用事件，应在相关操作之前订阅 whatsapp::events 触发类型，指定 session_id 和精确的事件种类，并保留回调命名空间与元数据；订阅后读取一次 sessions::get 以消除竞态，后续工作可借助引擎的唤醒/事件机制。
发送类函数只能在会话已连接、且用户已授权收件人与操作时调用。应使用 worker 返回的字符串 JID，并保留 @lid 身份及其设备后缀；不得从 LID 推断电话号码。媒体函数接受有长度上限的 base64 字节，发送前需自行准备好目标编码，worker 不做转码，也不会抓取任意 URL。该 Go 版本不提供状态发布功能。应保留返回的消息 ID 与事件序列；发送响应不等于送达或已读回执，超时可能留下未知的远端结果，重试写操作前应先检查事件或状态。
事件投递为尽力而为。出现缺口时可用 whatsapp::events::poll 对账，返回 truncated 表示部分历史不可用。chats::list 与 messages::list 可读取本地保留的消息（不含已读回执），覆盖范围指保留的历史，而非手机上的完整存档。sessions::stop 保留凭据；sessions::logout 请求远端解绑并清除本地凭据（远端解绑为尽力而为）；sessions::delete 删除本地状态。这些破坏性操作只能在用户明确要求时执行，并应如实返回操作结果及各参与者的失败情况。
Meta Cloud API 模式无需原生会话，使用 whatsapp::cloud::* 函数。可先检查 cloud::status，需要连接测试时运行 cloud::check_connection。收件人应使用带前导 + 的规范电话号码或业务范围内的用户 ID，且只向选定收件人发送已授权的文本或已审核模板。Cloud 模式不支持群组、账号开通和历史回填。凭据与 webhook 设置需参考 Meta Cloud API 官方文档。
若需持续处理 Cloud webhook，应在 worker 命名空间内订阅 whatsapp::cloud::events，保留回调命名空间与绑定元数据，并在构造过滤器或消费载荷前阅读过滤说明。kinds 为空或省略时仅接收 message.received，需显式选择 message.status。可按账号、聊天、发送者、消息类型与状态过滤以限定回调范围；这些事件在 data 中携带原始单一 Meta 对象，与原生会话事件相互独立。订阅后读取 cloud::chats::list 与 cloud::messages::list 对账保留状态与注册缺口，连接中断或回调失败后应再次对账：Cloud 投递为尽力而为、去重且有界，不提供回调重试或事件轮询端点。本地发送不会产生 message.received，应通过后续 webhook 状态确认送达，并在结果不确定时先检查存档再决定是否重发。