mcpField
W
whatsapp

whatsapp

github.com/sanjay3290生产力44878 次安装7 周前更新
代码仓库

关于 whatsapp

whatsapp（pywhats）是通过异步 Python 和命令行操作 WhatsApp 关联设备的非官方客户端，适合自动发送消息及监听事件。它支持文本、图片和多账户会话。

主要功能

  1. 01二维码配对与会话恢复
  2. 02发送单聊文本和图片
  3. 03发送群组文本并查看群信息
  4. 04监听 JSON 事件流
  5. 05管理在线状态、已读和输入状态

适用场景

  1. 01脚本向个人聊天发送文本或图片
  2. 02向群组发送消息并读取群组信息
  3. 03监听指定聊天或事件并处理消息
  4. 04在多个 WhatsApp 账户间切换会话

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sanjay3290/ai-skills --skill whatsapp

安装后在 Claude Code 中输入/whatsapp确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
references/
api.md
scripts/
_bootstrap.sh
wa.py

详细介绍

WhatsApp（pywhats）

通过异步 Python 和 pywhats 将 WhatsApp 账号作为已关联的伴侣设备（类似 WhatsApp Web）使用（预 Alpha 阶段，仅支持文本和图片）。这是一个非官方的多设备客户端，不是官方 WhatsApp Business / Cloud API。

CLI 入口：scripts/wa.py（首次运行时会自动初始化托管的虚拟环境）。

基本概念

  • 配对 = 一次性扫描二维码。 wa.py pair 会显示 ASCII 二维码；在 WhatsApp → 已关联的设备中扫描。 凭据会保存到 $PYWHATS_HOME/<session>.session（以及 .signal.db）。
  • 恢复会话 = 静默进行。 后续命令会使用同一会话重新连接，无需扫描二维码。
  • JID 用于指定聊天。 纯电话号码 15550001234 → [email protected]； 群组使用 [email protected]。
  • 通过事件接收消息。 wa.py listen 会为每个事件打印一个 JSON 对象。

⚠️ 绝不要在处理程序中直接等待 Client 调用

事件处理程序会直接在接收循环中运行。在处理程序中等待 send_*、 mark_read、get_group_info、download_media 等调用会导致连接死锁。始终使用 asyncio.create_task(...)。listen 子命令已为 --read 执行此操作。

命令

scripts/wa.py pair                                          # one-time QR pair
scripts/wa.py send-text 15550001234 "hello"                 # 1:1 text
scripts/wa.py send-image 15550001234 photo.jpg --caption hi # 1:1 image
scripts/wa.py group-info [email protected]            # group metadata JSON
scripts/wa.py group-send [email protected] "hi all"   # group text
scripts/wa.py mark-read 15550001234 MSGID [--sender JID]    # blue ticks
scripts/wa.py presence available                            # global presence
scripts/wa.py typing 15550001234 composing [--media audio]  # typing indicator
scripts/wa.py listen --read --events message,receipt        # JSONL event stream
scripts/wa.py --session work send-text 15550001234 "hi"     # named session
命令行为
pair使用 ASCII 二维码建立新关联；若已配对则不会重复操作
send-text <to> <text>发送一对一文本；打印消息 ID
send-image <to> <path> [--caption C]发送图片（jpg/png/webp，≤16MB）；打印 ID
group-info <gid>打印群组 JSON（主题、所有者、参与者等）
group-send <gid> <text>解析成员后发送群组文本；打印 ID
mark-read <chat> <ids...>标记为已读；群组使用 --sender
presence <available|unavailable>全局在线状态
typing <to> <composing|paused>聊天在线状态；可选 --media audio
listen长时间运行并输出 JSON 行；--read、--events、--subscribe JID（接收在线状态事件时必需）

全局选项：--session NAME（默认为 default，或使用环境变量 PYWHATS_SESSION）—— 必须放在子命令之前：wa.py --session work pair。

会话 / 多账号

$PYWHATS_HOME/                 # default: ~/.pywhats
  venv/                        # managed Python + pywhats
  default.session              # --session default
  default.session.signal.db
  work.session                 # --session work

使用 PYWHATS_HOME 覆盖默认目录。未配对 / 已登出的会话会显示明确提示，要求重新运行 wa.py --session <name> pair。

如果 pair 在扫描后立即提示设备已登出，这是 WhatsApp 清理设备变更造成的，并非此技能故障——失效的会话会自动删除；请按照打印的恢复步骤操作（移除已关联的设备，等待 15–20 分钟，然后重新配对一次）。

完整参考

references/api.md — 所有 Client 方法、所有事件负载、JID 构造方式，以及 download_media 说明。

评论

支持 Markdown