mcpField
W
whapi

whapi

github.com/whapi-cloud开发3170 次安装30 周前更新
代码仓库

关于 whapi

面向通过 WHAPI.cloud 构建 WhatsApp 集成的 AI Agent 的实用指南，涵盖消息、群组、频道、社区和 webhook 等规则。它还指导检查 whapi-mcp 的连接状态，并要求以 MCP 工具架构和 API 文档为准。

主要功能

  1. 01覆盖七类 API 使用规则
  2. 02指导 MCP 安装与连接状态检查
  3. 03提供消息和 webhook 使用指引
  4. 04涵盖群组、频道与社区管理
  5. 05列出避免虚构参数的规则

适用场景

  1. 01配置 Cursor 或 Claude Desktop 中的 WHAPI MCP
  2. 02构建 WhatsApp 消息或广播系统
  3. 03设置 webhook 接收消息
  4. 04排查 WHAPI API 行为异常

MCP 相关

该技能要求开始任务前检查 whapi-mcp，并根据返回状态处理连接、配对或认证问题。whapi-mcp 提供 API 方法，技能补充正确用法和参数校验规则。

安装

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

$npx skills add https://github.com/whapi-cloud/whapi-whatsapp-api-skill --skill whapi

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

包含的文件

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

AGENTS.md
CLAUDE.md
README.md
references/
_contributing.md
_sections.md
_template.md
channels-management.md
communities-management.md
core-auth.md
core-chat-id.md
core-mcp-setup.md
groups-management.md
msg-interactive.md
msg-media.md
msg-text.md
msg-type-selection.md
pattern-bot.md
pattern-broadcast.md
recv-history.md
recv-webhooks.md

详细介绍

WHAPI.cloud WhatsApp API — Agent 技能

面向通过 WHAPI.cloud 构建 WhatsApp 集成的 AI Agent 的实用指南。 涵盖 7 个类别的规则，按优先级排列，旨在避免最常见的错误， 并涵盖最常用的 API 功能。

前置条件 — MCP 设置检查

开始任何任务前，请确认 whapi-mcp MCP 服务可用：

  1. 尝试调用 checkHealth 工具。
  2. 如果调用成功响应 — 继续。
  3. 如果未找到该工具 — 表示尚未安装 MCP 服务。 引导用户完成安装：references/core-mcp-setup.md。
  4. 如果工具返回 404（“Channel not found”）— 表示令牌无效或频道 不存在。引导用户查看：references/core-mcp-setup.md 中的 “Token is Missing or Invalid”部分。
  5. 如果工具有响应，请检查响应中的 status.text：
status.text含义操作
AUTH已连接且正常运行继续
QR正在等待扫描二维码打开频道控制面板并扫描二维码以完成配对
INIT服务正在初始化等待 40-50 秒；若仍未完成，请联系 WHAPI 支持
LAUNCH正在连接 WhatsApp 账号等待几秒；若仍未完成，请联系 WHAPI 支持
STOP频道已停用在 panel.whapi.cloud/dashboard 检查订阅状态
SYNC_ERROR同步失败退出频道登录并重新连接；问题解决前，GET 请求将失败

如需通过 QR 配对：参阅 references/core-mcp-setup.md 中的 “Where to Get Your API Token”部分。

适用场景

在以下情况参考这些指南：

  • 在 Cursor、Claude Desktop 或任何兼容 MCP 的客户端中设置 WHAPI MCP
  • 发送消息（文本、媒体、交互式消息、投票）
  • 通过 Webhook 接收传入消息
  • 管理群组、频道（新闻简报）或社群
  • 构建机器人、广播系统或 CRM 集成
  • 排查意外的 API 行为

API 覆盖范围与 MCP 备用方案

本技能涵盖最常用的操作，并帮助避免最常见的错误。 它不会记录每个 WHAPI 端点。

如果任何参考文件都未描述所需操作：

  1. 检查可用的 MCP 工具 — whapi-mcp 会直接提供所有 API 方法。
  2. 无论使用哪个端点，都遵循 core-chat-id.md 中的 Chat ID 格式规则。
  3. 无论使用哪个端点，都遵循 core-auth.md 中的身份验证规则。
  4. 只能使用 MCP 工具架构中的参数名称 — 不要自行编造参数。
  5. 如有疑问，请参照 WHAPI API Reference 进行验证。

MCP 是可用方法的权威来源。本技能是正确使用模式和防止幻觉规则的权威来源。

按优先级划分的规则类别

优先级类别影响前缀
1核心概念严重core-
2消息严重msg-
3接收严重recv-
4群组高groups-
5频道高channels-
6社群中communities-
7模式高pattern-

使用方法

阅读各参考文件，了解详细说明和代码示例：

1. references/core-mcp-setup.md      ← install and configure the MCP first
2. references/core-chat-id.md        ← understand Chat ID formats (most common error)
3. references/core-auth.md           ← authenticate direct REST calls
4. references/msg-type-selection.md  ← choose the right send tool
5. references/recv-webhooks.md       ← set up receiving messages

每个参考文件都包含：

  • 为什么这很重要（1-2 句话）
  • 错误示例及说明
  • 正确示例及说明
  • 防止幻觉检查清单（不存在的参数）
  • WHAPI 专属说明

参考资料

评论

支持 Markdown