如何用 API 发送 WhatsApp 消息(绑定、文本、媒体)

发布于 2026年8月23日 · 更新于2026年10月16日

很多人第一次接「发 WhatsApp」接口,会把它当成查号的升级版:号码已经有了,文案也写好了,一次 POST 就该发出去。这个假设会让集成卡在第一步。查号只回答「这个号码在不在 WhatsApp 上」,不需要任何人的账号。发消息是以某个账号的身份说话。账号没绑上,再完整的 text 也没有发件人。

正确顺序是一条流水线:先把会话绑上,再发——媒体发出去之前,还要先确认对方真的在 WhatsApp 上。到控制台复制已授权的平台 Key(需先登录),放进查询参数 key,只放在服务端。打开本页或复制示例不会发起数据请求;把 YOUR_API_KEY 换成真实 Key 再执行才会扣点数。只在你本人拥有或已获授权的账号上使用,并遵守 WhatsApp 服务条款。

发消息不是查号

查号是无状态的:一个号码、一个答案、没有收件箱。发消息挂在已关联的设备上。WhatsApp 消息里的每个接口都要带 sessionId,它代表那台设备。会话不是 CONNECTED,send-message 就没有可代表的身份。把查号项目里的 userHash 拿来发消息也走不通——那是资料查询的通行证,不是发件人。

请求形态也和查号的 GET 不一样。key 和 sessionId 走查询参数;GET、DELETE 的其余字段也在查询串里;POST 要把操作本身的 JSON 当成字符串塞进 body。响应包两层:{"code": 200, "message": "success", "data": {"code": 200, "data": {...}}}。外层是平台,内层是消息服务——它即使拒绝请求也常回 HTTP 200,真正结果在内层的 code、title、detail。平台层 401 是 Key 缺失或无效,403 是点数不足或账户未启用。只看 HTTP 状态行,会把一次被拒绝的发送当成成功。

下面这个封装会剥开两层信封。环境变量用 OPENDATA_API_KEY。

import json
import os
import time
import requests

BASE = "https://api.opendata-api.com/api/project/whatsapp-messaging"
SUCCESS_CODES = {200, 201, 202, 204}


def call(method, operation, payload=None, **params):
    """Call one operation and return the innermost payload (dict, list or None)."""
    params["key"] = os.environ["OPENDATA_API_KEY"]
    kwargs = {"params": params, "timeout": 60}
    if payload is not None:
        kwargs["json"] = {"body": json.dumps(payload)}
    resp = requests.request(method, f"{BASE}/{operation}", **kwargs)
    if not resp.ok:
        raise RuntimeError(f"{operation} failed: HTTP {resp.status_code}")
    body = resp.json()
    # Peel both envelopes; inner HTTP 200 is not a business success
    while isinstance(body, dict) and "code" in body:
        if body["code"] not in SUCCESS_CODES:
            raise RuntimeError(f"{operation} failed: inspect redacted diagnostics")
        body = body.get("data")
    return body

如果只想确认号码在不在,别为这件事开会话。用不依赖会话的检测更合适:如何检测号码是否在用 WhatsApp、WhatsApp 号码查询指南、批量验证 WhatsApp 号码。

先把账号绑上再发第一句

create-session 发起登录。日常用二维码:

curl -X POST "https://api.opendata-api.com/api/project/whatsapp-messaging/create-session?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"{\"mode\":\"qr\",\"deviceName\":\"My Bot\"}"}'

拿到会话 ID 后轮询 get-session。等待扫码时,载荷里会有可扫描的 qrImage(base64 数据 URI)和浏览器里可打开的 qrPageUrl。手机上打开 WhatsApp,进入「设置」→「已关联设备」→「关联设备」,扫码即可。

不方便扫码时改配对码:发送 {"mode":"pairing","phoneNumber":"8613800138000","deviceName":"My Bot"}。phoneNumber 是完整国际号码,只含数字,不带 + 和空格。状态载荷会给出 8 位 pairingCode。手机上选「关联设备」,再选「改为使用手机号码关联」,输入配对码。deviceName 会显示在「已关联设备」列表里。

create-session 把会话放在 data.data,内层 code 为 201。真正的标识是 id 字段,之后每次调用都把它当作查询参数 sessionId 传入——sessionId 只是参数名。

session = call("POST", "create-session", {"mode": "qr", "deviceName": "My Bot"})
session_id = (session or {}).get("id")
if not session_id:
    raise RuntimeError("no session id in the response")

deadline = time.time() + 180
while time.time() < deadline:
    state = call("GET", "get-session", sessionId=session_id)
    if state.get("status") == "CONNECTED":
        break
    if state.get("status") in ("FAILED", "LOGGED_OUT"):
        raise RuntimeError("login did not complete")
    time.sleep(3)
else:
    raise TimeoutError("account was not linked in time")

状态包括 CREATED、WAITING_FOR_SCAN、CONNECTING、CONNECTED、DISCONNECTED、LOGGED_OUT、FAILED。第一次绑定成功后,id 会变成由设备派生的稳定值,不必每次扫码,除非你主动登出。已保存但离线的账号,调用 get-session 会懒加载并尝试重连。轮询时请设超时:二维码会过期,配对码也会失效,死循环只会把登录卡在过期画面上。

文本、媒体、再读收件箱

不要先发出去再校验。check-contact-exists 借已连接的会话判断号码有没有可用的 WhatsApp 账号,返回 exists、联系人 jid 和你传入的 query。号码放在 phoneNumber,同样只含数字。

info = call("GET", "check-contact-exists", sessionId=session_id, phoneNumber="8613800138000")
if not info.get("exists"):
    raise RuntimeError("recipient is not on WhatsApp; skip the send")

整份名单的清洗,用上面那些不依赖会话的查询。会话上的存在性检查会占用已绑定账号的额度与风控空间,只留给「马上就要发」的那几个号码。

会话已是 CONNECTED、对方也确认在网上之后,再调 send-message:to 是收件人,text 是正文。几乎人人会踩的坑:to 必须是完整国际号码、只含数字、不带 +,而且必须是 JSON 数字而不是字符串。写 8613800138000,不要写 "+86 138 0013 8000"。

curl -X POST "https://api.opendata-api.com/api/project/whatsapp-messaging/send-message?key=YOUR_API_KEY&sessionId=SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"body":"{\"to\":8613800138000,\"text\":\"Hello from the API!\"}"}'
sent = call(
    "POST",
    "send-message",
    {"to": 8613800138000, "text": "Hello from the API!"},
    sessionId=session_id,
)
# sent may include id, timestamp, and to — treat it as a receipt, not a delivery guarantee

引用回复时加上 quoteMessageId,值取自收件箱或聊天记录。发送没有幂等键。超时之后先看聊天记录,再决定要不要重发同一段文字。

send-media 同样用数字型 to,type 取 image、video、audio、voice、document、sticker,文件内容 base64 后放进 data。voice 是按住说话的语音条。发 document 必须带 fileName。caption 是说明文字,mimeType 可覆盖推断类型,seconds 设音视频时长。媒体比纯文本更扎眼,所以更要先校验收件人。

import base64

with open("receipt.pdf", "rb") as fh:
    data = base64.b64encode(fh.read()).decode("ascii")

call("POST", "send-media", {
    "to": 8613800138000,
    "type": "document",
    "data": data,
    "fileName": "receipt.pdf",
    "caption": "Your receipt",
}, sessionId=session_id)

list-inbox 返回会话在线期间实时收到的消息,最新的在前。每条有消息 ID、chatJid、发送者、类型、文本和时间戳。每个会话最多留最近 500 条,重启会清空,所以要轮询并自己落库。limit 限制页大小。mark-read 用 chatJid 和 messageIds 发已读回执。

const key = process.env.OPENDATA_API_KEY;
const sessionId = process.env.WHATSAPP_SESSION_ID;
const url = new URL(
  "https://api.opendata-api.com/api/project/whatsapp-messaging/list-inbox"
);
url.searchParams.set("key", key);
url.searchParams.set("sessionId", sessionId);
url.searchParams.set("limit", "50");

const resp = await fetch(url);
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
let body = await resp.json();
while (body && typeof body === "object" && "code" in body) {
  if (![200, 201, 202, 204].includes(body.code)) {
    throw new Error("business failure; inspect redacted diagnostics");
  }
  body = body.data;
}
for (const msg of body || []) {
  console.log(msg.id, msg.chatJid, msg.text);
}

仍然不该自动做的事

这条流水线服务的是对方已经预期会收到的对话:已授权用户、客户、交易通知。它不是冷名单工具,也不是把查号结果批量转成触达的开关。未经请求或内容完全相同的群发会把绑定账号置于风险之中,REST 封装改变不了 WhatsApp 的条款。

不要把 HTTP 200 当成已送达。不要在超时后循环重试 send-message。不要给没校验过的号码塞媒体。不要把 list-inbox 当持久日志——它只是最近 500 条的窗口,重启即空。不要随手带 logout=true 去断开:默认断开只拆实时连接、保留登录;logout=true 会清掉凭据,之后必须重新绑定。

控制节奏,文案不要千篇一律,Key 不要下发到浏览器。发送开始失败时,先调 get-session,再决定要不要重试。投票、表情、编辑、群组和隐私是后续阶段,不是绕过「绑定 → 校验 → 一条一条发」的捷径。