WhatsApp 消息 API

开始登录你的 WhatsApp 账号并获取后续所有接口都要用到的 sessionId。共有两种登录方式，任选其一、发送对应的 JSON 请求体，然后轮询“获取会话状态”直到 status 为 CONNECTED。 二维码登录（推荐）。请求体：{"mode":"qr","deviceName":"My Bot"}。状态响应会返回可扫描的 qrImage（base64 data-URI）和可实时查看进度的 qrPageUrl。在手机上：WhatsApp → 设置 → 已链接的设备 → 链接设备，然后扫码。 配对码登录。请求体：{"mode":"pairing","phoneNumber":"8613800138000","deviceName":"My Bot"}。phoneNumber 为完整国际号码，仅数字，不含 + 号和空格。状态响应随后会返回一个 8 位 pairingCode。在手机上：WhatsApp → 设置 → 已链接的设备 → 链接设备 → 改用电话号码关联，然后输入该配对码。 连接成功后，sessionId 会变成由设备生成的稳定 ID，可在重启后复用。deviceName 用于设置在 WhatsApp“已链接设备”中显示的名称。

返回会话当前状态：status（CREATED、WAITING_FOR_SCAN、CONNECTING、CONNECTED、DISCONNECTED、LOGGED_OUT 或 FAILED）、登录方式、已绑定手机号，以及在等待登录期间的 qrImage（base64 data-URI）或 pairingCode 和 qrPageUrl。如果账号保存了凭证但当前离线，本调用会惰性加载并触发重连。创建会话后轮询本接口，直到 status 为 CONNECTED。

显式重连一个保存了凭证但当前离线的会话，并返回其最新状态。用于按需恢复掉线连接，而不必等待其他接口自动触发的惰性重连。无需请求体。

断开并移除会话。默认仅断开会话连接但保留已存凭证，之后仍可恢复账号。传 logout=true 则完全登出 WhatsApp、删除本地凭证并解绑代理——此后账号需重新扫码或配对才能连接。

从已连接会话向任意接收方发送 WhatsApp 文本消息。请求体中传接收方完整国际号码（纯数字，不带 +）作为 to、消息内容作为 text；可选传 quoteMessageId（来自收件箱或聊天记录的消息 id）实现引用回复。to 必须是 JSON 数字而非字符串。返回上游消息 id 与时间戳。会话需已完成登录。

从已连接会话发送媒体消息。请求体中传接收方号码 to、媒体类型 type（image、video、audio、voice、document 或 sticker——voice 表示 PTT 语音条）以及 base64 编码的文件内容 data。document 必须传 fileName；caption 添加说明文字；mimeType 可覆盖推断类型；seconds 设置音/视频时长。to 必须是 JSON 数字。返回上游消息 id。

返回会话在线期间实时收到的消息，按时间倒序（最新在前）。每条包含消息 id、chatJid、发送者、类型、文本与时间戳。收件箱是内存缓存，每会话最多保存最近 500 条，重启后清空。可用 limit 控制返回条数。适合轮询新收到的消息以驱动自动回复。

对一条消息添加 emoji 回应。请求体中传目标消息的 chatJid 与 messageId，以及要使用的 emoji。传空字符串 emoji 可移除你的回应。群聊中可传 senderJid 指定原发送者；省略时会从内存缓存推断。返回上游结果。

编辑你之前发送的消息文本。请求体中传 chatJid、已发消息的 messageId 以及新的 text。群聊中可传 senderJid；省略时会从内存缓存推断。只能编辑你自己发送的消息。返回上游结果。

撤回一条消息，使其对所有参与者删除。请求体中传 chatJid 与 messageId。不传 senderJid 时撤回你自己发送的消息；传 senderJid 可撤回群内其他成员的消息（需要你在该群拥有管理员权限）。返回上游结果。

为会话中的一条或多条消息发送已读回执。请求体中传 chatJid，以及单个 messageId 或用于批量标记的 messageIds 数组；群聊中必要时需传 senderJid。标记已读后发送者会看到蓝色双勾。返回上游结果。

在单聊或群聊中发起 WhatsApp 投票。请求体中传 question 与 options 数组（至少两项）。可通过 to（完整国际号码，JSON 数字）或 chatJid（优先，可发到群）指定目标。maxSelections 为 1 表示单选，更大则为多选。返回上游消息 id。

返回会话已知的所有聊天摘要，来源于登录历史同步与实时消息。用于构建会话列表，并发现读取单聊历史、发送正在输入状态或设置阅后即焚所需的 chatJid。

按时间倒序返回某个聊天最近缓存的消息。需提供 sessionId 与 chatJid（单聊如 8613800138000@s.whatsapp.net，群聊如 120363...@g.us）。消息来自内存缓存（登录历史同步加实时流量）。用 limit 控制返回条数。

下载并解密消息附带的媒体（图片、视频、音频或文档），以 base64 返回。需提供 sessionId、chatJid 与 messageId（来自聊天记录或收件箱）。所引用的消息必须在内存缓存中且包含媒体，否则请求失败。

在聊天中显示“正在输入…”或“正在录音…”状态。请求体中传 state（composing 开始，paused 停止）以及可选 media（text 表示正在输入，audio 表示正在录音）。用于让机器人在回复前表现出更拟人的活动状态。

为某个聊天开启或修改阅后即焚计时器。请求体中传 durationSeconds：0 表示关闭，86400 表示 24 小时，604800 表示 7 天，7776000 表示 90 天。仅接受这四个值。作用于该聊天之后的新消息。

返回会话本地存储中当前保存的联系人，登录后同步。每个联系人包含其标识与姓名。用于枚举已知联系人，做资料增强、接收方选择或受众构建。

使用已连接会话校验给定手机号是否有在用 WhatsApp 账号。路径中传完整国际号码（纯数字，不带 +）。返回该号码是否存在及其 JID。用于发送前校验接收方，提升送达率、减少无效发送。

返回联系人的公开 About（状态）文本；若被隐私设置隐藏或未设置则返回空。路径中传完整国际号码（纯数字，不带 +）。使用已连接会话实时查询该值。

返回联系人头像的 URL；被隐私设置隐藏或未设置时 exists=false。路径中传完整国际号码（纯数字，不带 +）。使用已连接会话实时解析当前头像 URL。

返回某个号码的 WhatsApp Business 资料：isBusiness，以及企业账号的地址、邮箱、类目与简介等信息。路径中传完整国际号码（纯数字，不带 +）。个人号码返回 isBusiness=false。使用已连接会话实时查询。

返回本会话所登录账号的信息：其 JID、手机号、LID 与昵称。用于确认会话究竟连接的是哪个账号，并在发送前展示你自己的身份。

更新已连接账号的公开资料。请求体中传 name 设置新昵称、about 设置新状态签名，至少提供一项。修改会体现在他人可见的 WhatsApp 资料上。返回上游结果。

返回已连接账号的 wa.me 联系二维码链接（https://wa.me/qr/...），他人扫码或打开即可与你发起聊天。传 revoke=true 可使旧链接失效并生成新链接。适合分享客服或销售入口。

用名称和一组初始成员创建 WhatsApp 群组。请求体中传 name（字符串）与 participants（完整国际号码的 JSON 数字数组，纯数字），例如 {"name":"Support Group","participants":[8613800138000,4915256515060]}。返回新群组的 JID 与元数据，便于立即进行后续操作。

返回已连接账号加入的所有群组。用于枚举社群、发现群管理操作所需的 groupJid，或将账号的群组名单同步进你自己的系统。

使用邀请链接或邀请码加入 WhatsApp 群组。请求体中传 code，可以是完整链接（https://chat.whatsapp.com/xxx）或仅最后一段码。返回所加入群组的 JID。适合程序化进入你管理或监控的社群。

返回群组详情：名称（subject）、公告/简介、群主与成员列表。需提供 sessionId 与 groupJid（以 @g.us 结尾）。用于在群发或管理前检查成员与设置。

更新群组设置。请求体中可任意组合传：name（群名称）、topic（公告/简介）、announce（仅管理员可发言）、locked（仅管理员可编辑群信息）、joinApproval（加入需审批）。至少提供一项，仅更新所提供字段。需要你在该群拥有管理员权限。

向群组添加一名或多名成员。请求体是完整国际号码的 JSON 数字数组（纯数字），例如 [8613800138000,4915256515060]。响应包含逐成员结果，非零 error 标记失败的号码。需要你在该群拥有管理员权限。

从群组移除一名或多名成员。请求体是完整国际号码的 JSON 数字数组（纯数字），例如 [8613800138000]。响应包含逐成员结果，非零 error 标记失败的号码。需要你在该群拥有管理员权限。

将成员提升为管理员或取消现有管理员。请求体中传 phones（完整国际号码的 JSON 数字数组）与 action（promote 或 demote），例如 {"phones":[8613800138000],"action":"promote"}。响应包含逐成员结果。需要你在该群拥有管理员权限。

返回群组的邀请链接（https://chat.whatsapp.com/...）。传 reset=true 可使旧链接失效并生成新链接——链接泄露时很有用。需提供 sessionId 与 groupJid。需要你在该群拥有管理员权限。

设置群组头像。请求体中传 data，内容为 base64 编码的 JPEG 图片。返回新的图片 id。需要你在该群拥有管理员权限。适合程序化为社群或客服群做品牌化。

让已连接账号退出某个群组。需提供 sessionId 与 groupJid，无需请求体。返回所退出群组的 JID。用于程序化退出账号不再需要加入的社群。

设置已连接账号的全局在线状态。请求体中传 state，取 available（在线）或 unavailable（离线）。用于控制他人是否看到该账号在线。可让机器人在工作时段保持在线、空闲时离线。

订阅某个联系人的在线/离线状态更新。请求体中传 phone，为完整国际号码（JSON 数字，纯数字）。订阅后，在其隐私设置允许的前提下，账号会收到该联系人的在线状态更新。

返回已连接账号的黑名单：被拉黑的 JID 列表及总数。用于审计拉黑了谁、将黑名单同步进你自己的管理系统，或确认某号码已成功拉黑。

拉黑或取消拉黑某个手机号。请求体中传 phone（完整国际号码，JSON 数字，纯数字）与 action（block 或 unblock）。返回更新后的黑名单。用于自动屏蔽垃圾号码或恢复某联系人。

返回已连接账号当前的隐私设置：谁可以看你的最后上线时间、头像、About 与状态，以及已读回执、谁可以拉你进群、在线可见性与通话权限。用于在修改任何设置前审计账号的隐私状况。

更新账号的某项隐私设置。请求体中传 setting（groupadd、last、status、profile、readreceipts、online 或 calladd）与 value（all、contacts、contact_blacklist、none、match_last_seen 或 known）。不同设置支持的取值范围不同，由 WhatsApp 服务器校验。返回更新后的完整设置。