Gambot — Official WhatsApp Business API for AI Agents (MCP + REST API)

Gambot gives AI agents and developers the official WhatsApp Business (Cloud) API — through a Model Context Protocol server and a REST API. Gambot is a Meta Business Solution Provider.

• Official API, not WhatsApp Web automation. No QR codes, no linked personal sessions, no headless browsers. Real business accounts, approved templates, Meta-backed delivery.
• Two ways to connect. Local: npx -y gambot-mcp. Hosted: https://gambot-mcp.azurewebsites.net/mcp (Streamable HTTP, OAuth 2.0 or token).
• Built for agents. Machine-readable states and errors (error_code, can_recover, recommended_action, required_tool, template_required), one start-here tool (gambot_setup_whatsapp_integration), 24-hour-window and template guidance built in.
• No account yet? Start anyway. The agent can create a Gambot account itself (no API key needed); the only human step is the Meta WhatsApp connection in a browser.

Using an AI coding agent? Install the Agent Skill, then ask: "Add the official WhatsApp API to this app."

bashCopy

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

The skill (skills/gambot-whatsapp) teaches the agent the whole path: account → Meta onboarding → auth → first message → templates → webhooks → error recovery.

Quick start

1. Add the MCP server (works in Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, VS Code/Copilot, Windsurf):

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

No token is needed to begin. Without GAMBOT_TOKEN the server runs in onboarding mode and creates your account.

Per-client guides: https://gambot.co.il/whatsapp-mcp/.

2. Ask your agent:

"Set up WhatsApp for my app with Gambot and send a test message to my number."

The agent calls gambot_setup_whatsapp_integration, which returns the current state and one next step — and tells it whether the agent or the human must do it:

Authentication

Prefer OAuth (hosted MCP: https://gambot-mcp.azurewebsites.net/mcp — PKCE + dynamic client registration; no secret is pasted into config). Alternatively use your Gambot token (gmbt_…, Settings → General) as GAMBOT_TOKEN (local) or Authorization: Bearer gmbt_… (hosted / REST). Never paste a token into a chat. No account yet? https://gambot.co.il/OnboardingProcess/.

Minimal working example (REST, any language)

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"]}'

Runnable examples (send message, send template, receive webhook, delivery status) for Node/TypeScript, Python, Next.js and Laravel/PHP: examples/.

Official API vs WhatsApp Web automation

Use the official API for anything customer-facing. More: https://gambot.co.il/whatsapp-mcp-vs-whatsapp-web/.

It wraps the public REST API at https://api.gambot.co.il/api/v1. MCP is an AI-facing interface over Gambot — it uses the same business logic as the REST API and is not a separate backend.

Why Gambot instead of building on Meta's Cloud API directly

Both Gambot and a do-it-yourself integration run on the same official WhatsApp Business (Cloud) API from Meta — Gambot is an authorized Meta Business Solution Provider (BSP), not a WhatsApp Web/unofficial workaround, and you keep your own number/WABA. The difference is how much infrastructure you build and maintain:

Net: same official API, none of the plumbing to build or maintain, compliance enforced for you, and it's agent-ready. Full comparison: https://gambot.co.il/whatsapp-api-vs-meta-cloud-api/.

Supported AI clients

Step‑by‑step setup guides per client:

• Cursor — one‑click install or .cursor/mcp.json → https://gambot.co.il/whatsapp-mcp/cursor/
• Claude — Claude Desktop (npx) or a remote connector → https://gambot.co.il/whatsapp-mcp/claude/
• ChatGPT — hosted connector (Streamable HTTP + OAuth) → https://gambot.co.il/whatsapp-mcp/chatgpt/
• Gemini — Gemini CLI settings → https://gambot.co.il/whatsapp-mcp/gemini/

Hosted (remote) server: https://gambot-mcp.azurewebsites.net/mcp (Streamable HTTP; OAuth or bearer token) — no local install needed.

Prerequisites

• Node.js 18+
• No account yet? You need nothing — start the server without a token and it runs in token‑less onboarding mode to create your Gambot account from scratch.
• Already have an account? A Gambot Token (gmbt_…) from the Gambot admin panel → Settings → General, to unlock the full tool set.

Quick start (npx — recommended)

No clone or build is needed — MCP clients run it on demand with 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"
      }
    }
  }
}

Optional env var GAMBOT_API_BASE overrides the base URL (defaults to https://api.gambot.co.il/api/v1).

No token yet? Token‑less onboarding mode

You don't need a Gambot account to get started. The token is a result of finishing onboarding (chicken‑and‑egg: a brand‑new org has no token yet), so the server also runs without GAMBOT_TOKEN. Just omit it — leave env empty:

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

Started token‑less, it enters onboarding mode and exposes only the public self‑serve tools — create a brand‑new account (free / co‑existence / bring‑your‑own number, or buy a number after e‑mail+WhatsApp verification), open the Meta Embedded Signup link in the browser, then poll gambot_get_onboarding_status until WhatsApp is connected. Just tell the agent "create a Gambot WhatsApp account for my business" and it walks you through it. Once connected, you get your gmbt_… token in‑app (Settings → General); add GAMBOT_TOKEN to the env above to unlock the full tool set. (Remote/OAuth clients like Claude & ChatGPT authorize per‑session through the hosted consent page instead.)

Local development (from source)

npm install
npm run build

Then point your MCP client at the built entrypoint:

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

Tools

Bots & automations model

A conversational bot in Gambot is usually a package of botomations that were deployed together and share a sourceFlowId. gambot_list_bots returns role, triggerKind, sourceFlowId and linkedBotomationId on every item so an agent can reconstruct it. The full package, in order, is:

1. Main bot (role: main_bot, isBot: true) — the conversation itself. Three flavours:
   • menu — an opening template whose quick-reply buttons route to replies.
   • ai — a GambotAi step that hands the conversation to Gambot AI (the AI operator).
   • combined — a menu where some branches route to Gambot AI.
2. Activator / מפעיל (role: activator) — the trigger that starts the bot. triggerKind tells you how it fires: incoming_message (keyword/any), template_button, campaign_lead (a lead arrived from an ad/campaign), owner_assigned (a contact was assigned to an owner — e.g. Gambot AI), scheduled, or inactivity re-engagement ("no message in X days").
3. Human-intervention cancel / ביטול בוט בהתערבות אנושית (role: human_intervention_cancel) — fires when a human agent sends a message and stops the running bot so it never talks over a human. One is seeded active per org; a package can deploy its own.

Gambot AI (the AI operator) = ownership. To route a contact to Gambot AI, assign the contact's owner to Gambot AI. The Gambot-AI botomation's trigger is contactOwner == the Gambot AI user, so it then answers with a GambotAi step. An activator can therefore do "if no communication in X days → assign the contact to Gambot AI", and the AI takes over.

Building a bot in one call. gambot_deploy_bot_package assembles the whole package for you, in order — (1) main bot, (2) activator, (3) human-intervention cancel — all sharing one sourceFlowId. Pick botType: "menu" (give openingTemplateName + options, and an activator that sends the opening template: keyword / any_message / inactivity / campaign_lead) or botType: "keyword" (self-activating — its keyword IS the activator, so no separate activator is created). AI/combined bots (Gambot AI) are built in the Bot Builder app because they need a Gambot AI configuration.

Turning a bot on/off: gambot_set_bot_status toggles one botomation; pass includePackage: true to turn the whole bot (main + activator + cancel + Gambot AI) on or off together. Use gambot_get_bot_package first to see exactly what will change.

Example prompts

• "Send a WhatsApp to +972 50‑123‑4567 saying their order shipped."
• "Message everyone tagged VIP with the promo_launch template."
• "How many WhatsApp messages did we receive today, and how many are waiting for a reply?"
• "Summarize today's customer‑service conversations."
• "Schedule a campaign to the newsletter tag for tomorrow at 10:00."
• "Build a lead bot: when a lead arrives from an ad, send the welcome_lead template with buttons Sales/Support, and stop if I jump in." → gambot_deploy_bot_package(botType: "menu", openingTemplateName: "welcome_lead", options: [...], activator: { type: "campaign_lead" }).
• "Turn off my lead bot completely (the bot, its trigger and the AI answer)." → gambot_get_bot_package then gambot_set_bot_status(includePackage: true, status: "inactive").
• "Which bots are active, and what triggers each one?" → gambot_list_bots (read role + triggerKind).

Agent behavior, errors & recovery

Gambot MCP is designed so an AI agent can understand what happened and what to do next — it interprets the API's structured business state and returns actionable guidance.

• Structured errors. On an API error the tool result is JSON with stable machine-readable fields an agent can act on without parsing prose: error_code, reason, can_recover (can the agent fix it, or does a human have to?), recommended_action, required_tool (a real tool name), relevant_contact, template_required, plus the API's own data. Example:

  jsonCopy

  {
    "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 }
  }
  

  (Legacy fields code, message and recommendedAction are still returned for existing clients. Human-only problems such as a revoked token or missing billing return can_recover: false.)

• Common recoveries. CONVERSATION_WINDOW_CLOSED / TEMPLATE_REQUIRED → gambot_send_template; MISSING_TEMPLATE_VARIABLES → gambot_get_template_variables (then ask the user); CONTACT_NOT_FOUND → gambot_list_contacts (never guess a recipient); RATE_LIMITED / messaging‑limit → back off, don't loop, use a campaign for bulk.

• Safety. The agent never silently picks an ambiguous recipient, and never loops single‑send tools for bulk — it's routed to campaigns.

• Tool annotations. Read tools are marked read‑only/idempotent; delete_*, disable_user and issue_invoice are marked destructive; every tool is openWorld (it talks to the live WhatsApp/Gambot backend). Use these to gate confirmations for external‑communication and high‑impact actions.

REST API & docs

• REST reference, auth, scopes and the full error‑code vocabulary: https://gambot.co.il/developers/
• WhatsApp API for AI agents: https://gambot.co.il/whatsapp-api-for-ai-agents/

Security

The Gambot Token is a secret (like a password). Keep it out of source control (use the client's env). You can rotate it any time from Gambot Settings → General, and optionally narrow its scopes there.

Publishing (maintainers)

This package ships with a server.json manifest for the official MCP Registry (registry.modelcontextprotocol.io). The registry only stores metadata, so the npm package must be published first, and the reverse‑DNS name in server.json must match mcpName in package.json (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

If your GitHub owner is not gambot-ai, update the name in server.json, mcpName in package.json, and the repository/identifier fields to match before publishing.

Once listed in the official registry, aggregators such as Glama, PulseMCP and Smithery index the server automatically. A smithery.yaml is also included for Smithery.