Gambot

Gambot — 面向 AI Agent 的官方 WhatsApp Business API（MCP + REST API）

Gambot 通过 Model Context Protocol 服务和 REST API，为 AI Agent 和开发者提供 官方 WhatsApp Business（Cloud）API。 Gambot 是 Meta Business Solution Provider。

• 官方 API，而非 WhatsApp Web 自动化。 无需二维码、个人关联会话或无头浏览器。使用真实的企业账号、经批准的模板，以及由 Meta 提供支持的消息送达。
• 两种连接方式。 本地连接：npx -y gambot-mcp。托管连接：https://gambot-mcp.azurewebsites.net/mcp（Streamable HTTP，OAuth 2.0 或令牌）。
• 专为 Agent 打造。 提供机器可读的状态和错误（error_code、can_recover、recommended_action、required_tool、template_required），一个入门工具（gambot_setup_whatsapp_integration），并内置 24 小时窗口和模板指引。
• 还没有账号？现在就能开始。 Agent 可以自行创建 Gambot 账号（无需 API 密钥）；唯一需要人工完成的步骤是在浏览器中连接 Meta WhatsApp。

正在使用 AI 编码 Agent？ 安装 Agent Skill，然后提出请求：“为这个应用添加官方 WhatsApp API。”

npx skills add gambot-ai/gambot-mcp --skill gambot-whatsapp

该技能（skills/gambot-whatsapp）会引导 Agent 完成整个流程：账号 → Meta 入驻 → 身份验证 → 发送首条消息 → 模板 → Webhook → 错误恢复。

快速开始

1. 添加 MCP 服务（适用于 Claude Code、Claude Desktop、Cursor、Codex、Gemini CLI、VS Code/Copilot、Windsurf）：

{
  "mcpServers": {
    "gambot": { "command": "npx", "args": ["-y", "gambot-mcp"] }
  }
}

开始使用无需令牌。如果没有设置 GAMBOT_TOKEN，服务会在入驻模式下运行并创建账号。

客户端	命令 / 配置
Claude Code	claude mcp add gambot -- npx -y gambot-mcp 或托管连接：claude mcp add --transport http gambot https://gambot-mcp.azurewebsites.net/mcp
Cursor	一键安装 或 .cursor/mcp.json
Claude Desktop	claude_desktop_config.json（上方的 JSON）
OpenAI Codex	~/.codex/config.toml → [mcp_servers.gambot] command = "npx" args = ["-y", "gambot-mcp"]
Gemini CLI	~/.gemini/settings.json（上方的 JSON）
VS Code / Copilot	.vscode/mcp.json → {"servers":{"gambot":{"type":"http","url":"https://gambot-mcp.azurewebsites.net/mcp"}}}
Windsurf	~/.codeium/windsurf/mcp_config.json（上方的 JSON）
ChatGPT	自定义连接器 → https://gambot-mcp.azurewebsites.net/mcp（OAuth）

各客户端指南：https://gambot.co.il/whatsapp-mcp/.

2. 向 Agent 提出请求：

“使用 Gambot 为我的应用设置 WhatsApp，并向我的号码发送一条测试消息。”

Agent 会调用 gambot_setup_whatsapp_integration，该工具会返回当前状态和一个下一步操作，并告知应由 Agent 还是 人工 执行：

状态	后续操作
no_account_known / account_missing	Agent 创建账号（gambot_create_trial_account，无需 API 密钥）
awaiting_whatsapp_connection	人工在浏览器中打开 Meta Embedded Signup 链接（无法在 Agent 内执行）
whatsapp_connected_needs_token	人工使用 OAuth 登录（托管 MCP），或从 Settings → General 复制令牌并填入 GAMBOT_TOKEN
ready_needs_template	Agent 创建模板（需经 Meta 批准）
ready_to_send_first_message / ready	Agent 发送测试消息并确认送达

身份验证

优先使用 OAuth（托管 MCP：https://gambot-mcp.azurewebsites.net/mcp — PKCE + 动态客户端注册；无需在配置中粘贴密钥）。也可以使用你的 Gambot 令牌（gmbt_…，Settings → General）作为 GAMBOT_TOKEN（本地），或使用 Authorization: Bearer gmbt_…（托管 / REST）。切勿在聊天中粘贴令牌。还没有账号？https://gambot.co.il/OnboardingProcess/.

最简可运行示例（REST，任意语言）

export GAMBOT_TOKEN=gmbt_...        # from Settings → General; keep it secret

# Is free text allowed? (the 24-hour customer-service window)
curl -s https://api.gambot.co.il/api/v1/conversations/12025550123/window -H "Authorization: Bearer $GAMBOT_TOKEN"

# Window open → send text
curl -s -X POST https://api.gambot.co.il/api/v1/messages/send-text \
  -H "Authorization: Bearer $GAMBOT_TOKEN" -H "Content-Type: application/json" \
  -d '{"to":"12025550123","text":"Hello from Gambot"}'

# Window closed → send an approved template
curl -s -X POST https://api.gambot.co.il/api/v1/messages/send-template \
  -H "Authorization: Bearer $GAMBOT_TOKEN" -H "Content-Type: application/json" \
  -d '{"to":"12025550123","templateId":"hello_world_0626","variables":["there"]}'

Node/TypeScript、Python、Next.js 和 Laravel/PHP 的可运行示例（发送消息、发送模板、接收 webhook、查询送达状态）：examples/。

官方 API 与 WhatsApp Web 自动化

	Gambot（官方 WhatsApp Business API）	WhatsApp Web / QR 会话自动化
架构	通过商业解决方案提供商使用 Meta Cloud API	由脚本驱动的浏览器或关联设备会话
身份验证	API 令牌 / OAuth，按组织授权	使用手机扫描 QR 码；会话可能过期
与 Meta 的关系	经授权的提供商，已通过企业验证的 WABA	无
生产环境使用	专为此设计	不稳定；会话可能中断，账号可能被封禁
商业规则	24 小时窗口、已批准的模板、选择加入、质量评级	不会强制执行，因此很容易违规
Webhook	代为管理入站事件和送达回执	取决于所用的库
扩展能力	消息层级、多个号码、营销活动	一部关联手机

面向客户的用途请使用官方 API。了解更多：https://gambot.co.il/whatsapp-mcp-vs-whatsapp-web/.

它封装了公开 REST API：https://api.gambot.co.il/api/v1。MCP 是面向 AI 的 Gambot 接口——它使用与 REST API 相同的业务逻辑，并非独立的后端。

为什么选择 Gambot，而不是直接基于 Meta 的 Cloud API 构建

Gambot 和自行构建的集成都运行在 Meta 提供的同一官方 WhatsApp Business（Cloud）API 上——Gambot 是经授权的 Meta Business Solution Provider（BSP），不是 WhatsApp Web 或非官方变通方案，而且你可以保留自己的号码 / WABA。两者的区别在于你需要构建和维护多少基础设施：

你的需求	自行基于 Meta Cloud API 构建	Gambot（此服务）
入驻	Meta 应用审核 + 企业验证、WABA 设置	引导式入驻，约 24–48 小时即可上线
电话号码	通过 API 注册 / 迁移并管理	在控制面板中连接 / 迁移（支持 Coexistence）
模板	通过 API 提交、跟踪审批、管理版本	可视化编辑器 + 审批状态；gambot_list_templates
Webhook	托管公开 HTTPS 端点（重试、去重、扩展）	代为管理入站事件；可选转发
媒体	上传 / 托管媒体、管理 ID / 过期时间	在消息、模板和营销活动中处理
24 小时窗口	跟踪每段对话；选择发送自由文本还是模板	强制执行；API 返回 CONVERSATION_WINDOW_CLOSED + canSendTemplate
层级与限额	跟踪层级、限制速率、处理 131xxx 错误	自动处理；返回结构化限额错误
营销活动	构建队列、细分、退订和报告功能	内置营销活动，支持同意管理和每位收件人的结果
自动化 / CRM	构建机器人引擎和联系人存储	内置机器人、CRM、同意管理 / 退订和垃圾信息处理
AI Agent	解析原始 Graph API 错误（脆弱）	机器可读状态 + MCP 推荐的后续操作
API 维护	随 Meta 升级 Graph 版本进行迁移	Gambot 负责适应 Meta API 的变更

**总而言之：**使用同一官方 API，无需构建或维护任何基础设施，由系统为你强制执行合规要求，并且可供 Agent 使用。完整对比：https://gambot.co.il/whatsapp-api-vs-meta-cloud-api/。

支持的 AI 客户端

各客户端的分步设置指南：

• Cursor — 一键安装或 .cursor/mcp.json → https://gambot.co.il/whatsapp-mcp/cursor/
• Claude — Claude Desktop（npx）或远程连接器 → https://gambot.co.il/whatsapp-mcp/claude/
• ChatGPT — 托管连接器（Streamable HTTP + OAuth）→ https://gambot.co.il/whatsapp-mcp/chatgpt/
• Gemini — Gemini CLI 设置 → https://gambot.co.il/whatsapp-mcp/gemini/

托管（远程）服务： https://gambot-mcp.azurewebsites.net/mcp（Streamable HTTP；OAuth 或 bearer token）——无需本地安装。

前置条件

• Node.js 18+
• 还没有账户？ 什么都不需要——不带 token 启动服务，即可进入无 token 引导模式，从头创建 Gambot 账户。
• 已有账户？ 需要从 Gambot 管理面板 → Settings → General 获取 Gambot Token（gmbt_…），以解锁完整工具集。

快速开始（npx — 推荐）

无需克隆或构建——MCP 客户端会通过 npx 按需运行它。

Cursor（.cursor/mcp.json）/ Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "gambot": {
      "command": "npx",
      "args": ["-y", "gambot-mcp"],
      "env": {
        "GAMBOT_TOKEN": "gmbt_your_token_here"
      }
    }
  }
}

可选的环境变量 GAMBOT_API_BASE 可覆盖基础 URL（默认为 https://api.gambot.co.il/api/v1）。

还没有 token？无 token 引导模式

你无需 Gambot 账户即可开始使用。 Token 是完成引导流程后的结果（先有鸡还是先有蛋：全新的组织还没有 token），因此服务也可以在不设置 GAMBOT_TOKEN 的情况下运行。只需省略它——让 env 保持为空：

{
  "mcpServers": {
    "gambot": {
      "command": "npx",
      "args": ["-y", "gambot-mcp"]
    }
  }
}

以无 token 模式启动后，服务会进入引导模式，并且只开放公开的自助服务工具——创建全新账户（免费 / 共存 / 使用自己的号码，或在通过电子邮件和 WhatsApp 验证后购买号码），在浏览器中打开 Meta Embedded Signup 链接，然后轮询 gambot_get_onboarding_status，直到 WhatsApp 连接成功。只需告诉 Agent “为我的企业创建一个 Gambot WhatsApp 账户”，它就会引导你完成整个流程。连接成功后，你会在应用内的 Settings → General 中获得 gmbt_… token；将 GAMBOT_TOKEN 添加到上面的 env 中，即可解锁完整工具集。（Claude 和 ChatGPT 等远程 / OAuth 客户端会通过托管的授权页面按会话进行授权。）

本地开发（从源代码构建）

npm install
npm run build

然后将 MCP 客户端指向构建后的入口文件：

{
  "mcpServers": {
    "gambot": {
      "command": "node",
      "args": ["C:/Users/you/source/repos/gambot/gmbt_mcp/dist/index.js"],
      "env": {
        "GAMBOT_TOKEN": "gmbt_your_token_here"
      }
    }
  }
}

工具

分组	工具
从这里开始	gambot_setup_whatsapp_integration（状态 + 唯一的下一步；有无令牌均可使用）
消息	gambot_send_text、gambot_send_template、gambot_get_message_status（按 messageId 查询送达状态）
对话	gambot_list_conversations（对话/联系人列表——仅显示对象及最后一条消息的元数据）、gambot_get_conversation_messages（某个对话的完整消息历史）、gambot_analytics_transcript（一段时间内所有对话的消息内容——例如“我的团队今天是怎么回复的／哪些客户不满”）、gambot_check_window（24 小时窗口是否开放？→ 自由文本还是模板）、gambot_list_numbers（适用于多号码组织的发件号码）
模板	gambot_list_templates、gambot_get_template、gambot_get_template_variables、gambot_create_template（文本/媒体页眉、正文变量、页脚、按钮）、gambot_upload_template_media
联系人	gambot_get_contact_fields、gambot_create_contact、gambot_list_contacts（列出/搜索整个联系人目录——按姓名/电话/电子邮件、标签、对话状态/类别或负责人）、gambot_get_contact、gambot_update_contact（基本字段 + customFields）、gambot_list_ctwa_contacts（通过 Click-to-WhatsApp 广告创建的联系人，包含来源广告信息）、gambot_bulk_update_contacts（按筛选条件/电话号码一次更新多个联系人——标签、负责人、类别、同意状态、自定义字段；先预览 → 确认并添加审计备注）
潜在客户	gambot_get_lead_fields、gambot_create_lead、gambot_list_leads、gambot_get_lead、gambot_update_lead（所有基本字段 + customFields）、gambot_bulk_update_leads（按筛选条件/ID一次更新多个潜在客户——状态/阶段/负责人/自定义字段；先预览 → 确认并记录审计信息）
案例	gambot_get_case_fields、gambot_create_case、gambot_list_cases、gambot_get_case、gambot_update_case（基本字段 + customFields）
任务	gambot_create_task、gambot_list_tasks、gambot_get_task、gambot_update_task
备注	gambot_list_notes（读取/搜索联系人、潜在客户和案例中的备注——应用内的“备注中心”；按来源/日期/作者/文本筛选）、gambot_get_entity_notes（某个联系人/潜在客户/案例的备注——遵循组织的“实体间同步备注”设置，因此查询联系人时也会返回其潜在客户/案例的备注）、gambot_add_note（在联系人/潜在客户/案例的时间线上添加备注）、gambot_update_note（编辑现有备注）
分析 / 报告	gambot_analytics_summary（一次性 KPI 快照：消息、联系人、潜在客户、工单、任务、机器人）、gambot_analytics_messages、gambot_analytics_overview（全周期数据 + 6 个月趋势）、gambot_analytics_daily_conversations（每日时间序列）、gambot_analytics_contacts、gambot_analytics_leads、gambot_analytics_cases、gambot_analytics_tasks、gambot_analytics_ctwa、gambot_analytics_bots（机器人/自动化运行表现 + 按机器人细分）
报价单	gambot_create_quote、gambot_list_quotes、gambot_get_quote、gambot_update_quote
发票	gambot_create_invoice、gambot_list_invoices、gambot_get_invoice、gambot_update_invoice、gambot_issue_invoice
订单	gambot_create_order、gambot_list_orders、gambot_get_order、gambot_update_order
付款 / 交易	gambot_list_transactions（付款/结算交易——“这位客户付了什么/欠了什么”，按电话/状态/实体筛选）、gambot_get_transaction（单笔交易的完整明细，包括增值税 + 商品）
签名	gambot_list_signatures、gambot_get_signature、gambot_get_signature_link（供分发的签署链接）
Web 表单	gambot_list_forms、gambot_get_form、gambot_get_form_link（供分发的公开链接）、gambot_get_form_submissions
文档模板	gambot_list_documents、gambot_get_document、gambot_create_document_link（可供分发的填写链接）、gambot_get_document_submissions
用户	gambot_create_user、gambot_list_users、gambot_get_user、gambot_update_user、gambot_enable_user、gambot_disable_user
营销活动	gambot_list_campaigns、gambot_list_scheduled_campaigns、gambot_get_campaign、gambot_get_campaign_results、gambot_create_campaign（已保存的营销活动——用于任何定时发送（单次/周期性发送始终属于营销活动），或可重复使用的 CRM 细分群发）、gambot_send_campaign_from_excel（根据用户提供的工作表进行邮件合并式群发——传入行 + phoneColumn + 列到变量的映射；Excel 群发始终保存为营销活动——立即发送 = 保存并立即运行，定时发送 = 保存并由调度器运行）、gambot_update_campaign、gambot_delete_campaign、gambot_run_campaign、gambot_send_campaign（立即“向群组发送”：临时、不保存，发送给标签/细分群组/电话号码列表）、gambot_test_campaign（单个收件人）。决策规则：群组发送 = 立即且不保存（gambot_send_campaign）；定时发送（单次/周期性）= 始终使用营销活动（gambot_create_campaign）；一次性 Excel 群发 = 始终使用营销活动（gambot_send_campaign_from_excel）。群发时优先使用模板——regular 自由文本群发仅会触达 24 小时窗口开放的收件人。**内置合规机制：**每个组织都有一个已启用的退订流程（收件人回复 הסר/stop/unsubscribe 后，将被排除在未来的群发之外）；发送/运行响应会在 optOut 下返回该流程信息（默认启用），并在 consent 下返回你的同意状态。
机器人和自动化	gambot_deploy_bot_package（一次调用即可构建完整机器人——主机器人 + 激活器 + 人工介入时的取消流程，作为一个套件关联）、gambot_list_bots、gambot_get_bot、gambot_get_bot_package（完整机器人：主机器人 + 激活器 + 人工介入时的取消流程 + Gambot AI）、gambot_create_keyword_autoreply、gambot_create_template_button_autoreply、gambot_create_menu_bot、gambot_create_bot（高级用法，完整步骤架构）、gambot_create_facebook_lead_bot（自动回复新收到的 Facebook/Meta 潜在客户表单线索）、gambot_set_bot_status（开启/关闭；includePackage 可切换整个机器人套件）、gambot_delete_bot
Gambot AI（大脑）	gambot_list_ai（组织的 Gambot AI“大脑”——用途、语气、语言、问答数量）、gambot_get_ai（某个大脑的完整配置）、gambot_update_ai（PATCH——升级现有大脑；仅更改传入的字段）、gambot_create_ai（仅在组织尚无大脑时使用——先检查 gambot_list_ai）
入门设置	gambot_check_organization、gambot_generate_organization_name、gambot_search_available_numbers（按国家/地区购买号码）、gambot_send_onboarding_verification（向客户的电子邮件 + WhatsApp 发送 6 位验证码——仅在创建需要购买号码的账户前必须执行）、gambot_verify_onboarding_code（验证该验证码）、gambot_create_trial_account（免费试用；免费/共存/BYO/购买 SIM 卡——购买号码需要已验证的 verificationId）、gambot_create_paid_account（无试用，必须提供银行卡）、gambot_add_payment_method（保存银行卡）、gambot_create_payment_link（由 Tranzila 托管）、gambot_get_waba_connect_link、gambot_exchange_waba_token（完成 Meta Embedded Signup）、gambot_get_onboarding_status（轮询直至 WhatsApp 连接成功）
Webhook	gambot_register_webhook（注册/更新 Gambot POST 事件的 URL——入站消息、状态、模板更新；可选 authHeader + 按事件设置开关）、gambot_get_webhook（读取当前注册信息）、gambot_test_webhook（触发示例事件并获取投递结果——验证你的端点是否收到请求）、gambot_delete_webhook（禁用转发）。适用于需要实时接收消息/更新的系统开发者。
连接	gambot_list_connections（组织已连接的集成——电子邮件和日历 OAuth、Facebook 潜在客户广告主页、商店/CRM 链接、WhatsApp 号码；可在其他位置使用的 ID）
电子邮件	gambot_send_email（通过已连接的 Google/Microsoft 邮箱发送单封电子邮件）、gambot_list_email_campaigns、gambot_get_email_campaign、gambot_create_email_campaign（使用模板或内嵌内容；CRM 细分群组或指定收件人；设置 run:true 立即发送）、gambot_run_email_campaign（持久且可恢复——适用于大型列表，避免重复发送）
日历	gambot_list_calendar_events（获取已连接的 Google/Microsoft 日历中指定日期范围内的事件）
Facebook 潜在客户广告	gambot_list_facebook_lead_connections、gambot_list_facebook_lead_forms（已连接主页的潜在客户表单）、gambot_create_facebook_lead_bot（新潜在客户到达时立即自动回复）

机器人与自动化的模型

Gambot 中的对话机器人通常是一个包，由一组同时部署并共享同一个 sourceFlowId 的机器人自动化组成。gambot_list_bots 会在每个条目中返回 role、triggerKind、sourceFlowId 和 linkedBotomationId，以便 Agent 还原这些信息。完整的包按顺序包含：

1. 主机器人（role: main_bot、isBot: true）——对话本身。分为三种类型：
   • 菜单——开场模板，其快速回复按钮会跳转到相应回复。
   • AI——一个将对话交给 Gambot AI（AI 操作员）的 GambotAi 步骤。
   • 组合——菜单，其中部分分支会跳转到 Gambot AI。
2. 激活器 / מפעיל（role: activator）——启动机器人的触发器。triggerKind 会告诉你它的触发方式：incoming_message（关键词／任意消息）、template_button、campaign_lead（有潜在客户通过广告／营销活动到达）、owner_assigned（联系人被分配给某个所有者，例如 Gambot AI）、scheduled，或不活跃后的重新互动（“X 天内没有消息”）。
3. 人工介入取消器 / ביטול בוט בהתערבות אנושית（role: human_intervention_cancel）——在人工客服发送消息时触发，并停止正在运行的机器人，避免机器人与人工客服同时回复。每个组织默认会有一个已启用的实例；包也可以部署自己的实例。

Gambot AI（AI 操作员）= 所有权。 要将联系人转给 Gambot AI，请将联系人的所有者设为 Gambot AI。Gambot AI 机器人的触发条件是 contactOwner == the Gambot AI user，因此随后会通过 GambotAi 步骤回复。因此，激活器可以执行“如果 X 天内没有沟通 → 将联系人分配给 Gambot AI”，然后由 AI 接手。

一次调用构建机器人。 gambot_deploy_bot_package 会按顺序为你组装整个包——（1）主机器人、（2）激活器、（3）人工介入取消器——它们都共享同一个 sourceFlowId。选择 botType: "menu"（提供 openingTemplateName + options，以及一个会发送开场模板的 activator：keyword / any_message / inactivity / campaign_lead），或选择 botType: "keyword"（自行激活——其关键词本身就是激活器，因此不会单独创建激活器）。AI／组合机器人（Gambot AI）需在 Bot Builder 应用中构建，因为它们需要 Gambot AI 配置。

开启／关闭机器人：gambot_set_bot_status 可切换单个机器人自动化的状态；传入 includePackage: true，即可同时开启或关闭整个机器人（主机器人 + 激活器 + 取消器 + Gambot AI）。请先使用 gambot_get_bot_package 查看具体会有哪些变更。

示例提示词

• “向 +972 50‑123‑4567 发送一条 WhatsApp 消息，告知他们订单已发货。”
• “使用 promo_launch 模板，向所有带有 VIP 标签的人发送消息。”
• “我们今天收到了多少条 WhatsApp 消息？有多少条还在等待回复？”
• “总结今天的客户服务对话。”
• “安排明天 10:00 向 newsletter 标签发送营销活动。”
• “构建一个潜在客户机器人：当有潜在客户通过广告到达时，发送带有 Sales/Support 按钮的 welcome_lead 模板；如果我介入，则停止。” → gambot_deploy_bot_package(botType: "menu", openingTemplateName: "welcome_lead", options: [...], activator: { type: "campaign_lead" })。
• “彻底关闭我的潜在客户机器人（机器人、触发器和 AI 回复）。” → gambot_get_bot_package，然后执行 gambot_set_bot_status(includePackage: true, status: "inactive")。
• “哪些机器人处于启用状态？它们各自由什么触发？” → gambot_list_bots（读取 role + triggerKind）。

Agent 行为、错误与恢复

Gambot MCP 的设计目标是让 AI Agent 了解发生了什么以及接下来该做什么——它会解读 API 的结构化业务状态，并提供可执行的指导。

• **结构化错误。**发生 API 错误时，工具结果会以 JSON 形式返回，其中包含稳定、机器可读的字段，供 Agent 直接采取行动，无需解析散文：error_code、reason、can_recover（Agent 能否修复，还是必须由人工处理？）、recommended_action、required_tool（一个真实的工具名称）、relevant_contact、template_required，以及 API 自身的 data。示例：

  {
    "status": "action_required",
    "error_code": "CONVERSATION_WINDOW_CLOSED",
    "reason": "The 24-hour customer-service window is closed, so free text cannot be delivered. Send an approved template…",
    "can_recover": true,
    "recommended_action": "Call gambot_send_template. …",
    "required_tool": "gambot_send_template",
    "relevant_contact": "12025550123",
    "template_required": true,
    "data": { "canSendFreeText": false, "canSendTemplate": true }
  }
  

  （为兼容现有客户端，仍会返回旧字段 code、message 和 recommendedAction。对于仅限人工处理的问题，例如令牌已撤销或缺少账单，can_recover: false。）

• 常见恢复方式。CONVERSATION_WINDOW_CLOSED / TEMPLATE_REQUIRED → gambot_send_template；MISSING_TEMPLATE_VARIABLES → gambot_get_template_variables（然后询问用户）；CONTACT_NOT_FOUND → gambot_list_contacts（绝不猜测收件人）；RATE_LIMITED / 消息限额 → 等待后重试，不要循环调用；批量操作请使用营销活动。

• **安全性。**Agent 不会擅自选择有歧义的收件人，也不会为批量操作循环调用单条发送工具——这类操作会转由营销活动处理。

• **工具注解。**读取工具标记为只读/幂等；delete_*、disable_user 和 issue_invoice 标记为具有破坏性；每个工具都标记为 openWorld（会与实时 WhatsApp/Gambot 后端通信）。利用这些注解，可为对外通信和高影响操作设置确认门槛。

REST API 与文档

• REST 参考、身份验证、作用域和完整错误代码说明：https://gambot.co.il/developers/
• 面向 AI Agent 的 WhatsApp API：https://gambot.co.il/whatsapp-api-for-ai-agents/

安全性

Gambot Token 是机密信息（如同密码）。请勿将其提交到源代码管理中（使用客户端的 env）。你可以随时在 Gambot Settings → General 中轮换令牌，也可以选择在那里缩小其作用域。

发布（维护者）

此软件包附带 server.json 清单，用于官方 MCP Registry（registry.modelcontextprotocol.io）。Registry 仅存储元数据，因此必须先发布 npm 软件包；并且 server.json 中的反向 DNS name 必须与 package.json 中的 mcpName（io.github.gambot-ai/gambot-mcp）一致。

# 1) Publish the npm package (public)
npm publish --access public

# 2) Install the registry publisher CLI
#    (see https://modelcontextprotocol.io/registry/quickstart)
brew install mcp-publisher            # or download from the registry releases

# 3) Authenticate under the io.github.gambot-ai/* namespace and publish
mcp-publisher login github
mcp-publisher publish

如果你的 GitHub 所有者不是 gambot-ai，请在发布前更新 server.json 中的 name、package.json 中的 mcpName，以及 repository/identifier 字段，使其保持一致。

列入官方 Registry 后，Glama、PulseMCP 和 Smithery 等聚合平台会自动收录该服务。此外还附带 smithery.yaml，供 Smithery 使用。