Gambot MCP agent

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."

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.

Client	Command / config
Claude Code	claude mcp add gambot -- npx -y gambot-mcp or hosted: claude mcp add --transport http gambot https://gambot-mcp.azurewebsites.net/mcp
Cursor	One-click install or .cursor/mcp.json
Claude Desktop	claude_desktop_config.json (JSON above)
OpenAI Codex	~/.codex/config.toml → [mcp_servers.gambot] command = "npx" args = ["-y", "gambot-mcp"]
Gemini CLI	~/.gemini/settings.json (JSON above)
VS Code / Copilot	.vscode/mcp.json → {"servers":{"gambot":{"type":"http","url":"https://gambot-mcp.azurewebsites.net/mcp"}}}
Windsurf	~/.codeium/windsurf/mcp_config.json (JSON above)
ChatGPT	custom connector → https://gambot-mcp.azurewebsites.net/mcp (OAuth)

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:

State	What happens
no_account_known / account_missing	Agent creates the account (gambot_create_trial_account, no API key)
awaiting_whatsapp_connection	Human opens the Meta Embedded Signup link in a browser (cannot run inside an agent)
whatsapp_connected_needs_token	Human signs in with OAuth (hosted MCP) or copies the token from Settings → General into GAMBOT_TOKEN
ready_needs_template	Agent creates a template (Meta approval)
ready_to_send_first_message / ready	Agent sends a test message and confirms delivery

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

	Gambot (official WhatsApp Business API)	WhatsApp Web / QR-session automation
Architecture	Meta Cloud API via a Business Solution Provider	A browser or linked-device session driven by a script
Authentication	API token / OAuth, scoped per organization	A QR code scanned from a phone; session can expire
Meta relationship	Authorized provider, business-verified WABA	None
Production use	Designed for it	Fragile; sessions drop, accounts can be blocked
Business rules	24-hour window, approved templates, opt-in, quality ratings	Not enforced, so easy to violate
Webhooks	Managed inbound events, delivery receipts	Depends on the library
Scaling	Messaging tiers, multiple numbers, campaigns	One linked phone

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:

What you need	Build on Meta Cloud API yourself	Gambot (this server)
Onboarding	Meta app review + Business verification, WABA setup	Guided onboarding, live in ~24–48h
Phone number	Register/migrate & manage via API	Connect/migrate from the dashboard (Coexistence supported)
Templates	Submit via API, track approval, version	Visual editor + approval status; gambot_list_templates
Webhooks	Host a public HTTPS endpoint (retries, dedupe, scale)	Managed inbound events; optional forwarding
Media	Upload/host media, manage ids/expiry	Handled in messages, templates & campaigns
24h window	Track each conversation; choose free-text vs template	Enforced; API returns CONVERSATION_WINDOW_CLOSED + canSendTemplate
Tiers & limits	Track tiers, throttle, handle 131xxx errors	Handled; structured limit errors
Campaigns	Build queueing, segmentation, opt-out, reporting	Native campaigns with consent & per-recipient results
Automation / CRM	Build a bot engine & contact store	Bots, CRM, consent/opt-out & spam handling built in
AI agents	Parse raw Graph API errors (brittle)	Machine-readable states + MCP recommended next actions
API upkeep	Migrate as Meta bumps Graph versions	Gambot absorbs Meta API changes

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

Group	Tools
Start here	gambot_setup_whatsapp_integration (state + the single next step; works with or without a token)
Messages	gambot_send_text, gambot_send_template, gambot_get_message_status (delivery status by messageId)
Conversations	gambot_list_conversations (the conversation/contact LIST — who, with last-message metadata only), gambot_get_conversation_messages (full message history of ONE conversation), gambot_analytics_transcript (message CONTENT across ALL conversations for a period — for "how did my team reply today / which customers were upset"), gambot_check_window (is the 24h window open? → free text vs template), gambot_list_numbers (sender numbers for multi-number orgs)
Templates	gambot_list_templates, gambot_get_template, gambot_get_template_variables, gambot_create_template (text/media header, body variables, footer, buttons), gambot_upload_template_media
Contacts	gambot_get_contact_fields, gambot_create_contact, gambot_list_contacts (list/search the whole contacts directory — by name/phone/email, tag, conversation status/category or owner), gambot_get_contact, gambot_update_contact (base + customFields), gambot_list_ctwa_contacts (contacts created from a Click-to-WhatsApp ad, with the originating ad info), gambot_bulk_update_contacts (update MANY at once by filter/phones — tags, owner, category, consent, custom fields; preview → confirm and stamps an audit note)
Leads	gambot_get_lead_fields, gambot_create_lead, gambot_list_leads, gambot_get_lead, gambot_update_lead (all base fields + customFields), gambot_bulk_update_leads (update MANY at once by filter/ids — status/stage/owner/custom fields; preview → confirm and audited)
Cases	gambot_get_case_fields, gambot_create_case, gambot_list_cases, gambot_get_case, gambot_update_case (base + customFields)
Tasks	gambot_create_task, gambot_list_tasks, gambot_get_task, gambot_update_task
Notes	gambot_list_notes (read/search the notes across contacts, leads & cases — the in-app "Notes Hub"; filter by source/date/author/text), gambot_get_entity_notes (notes for one contact/lead/case — follows the org's "Sync Notes Between Entities" setting, so a contact also returns its leads'/cases' notes), gambot_add_note (write a timeline note on a contact/lead/case), gambot_update_note (edit an existing note)
Analytics / reports	gambot_analytics_summary (one-shot KPI snapshot: messages, contacts, leads, tickets, tasks, bots), gambot_analytics_messages, gambot_analytics_overview (lifetime + 6-month trend), gambot_analytics_daily_conversations (daily time series), gambot_analytics_contacts, gambot_analytics_leads, gambot_analytics_cases, gambot_analytics_tasks, gambot_analytics_ctwa, gambot_analytics_bots (bot/automation run performance + per-bot breakdown)
Quotes	gambot_create_quote, gambot_list_quotes, gambot_get_quote, gambot_update_quote
Invoices	gambot_create_invoice, gambot_list_invoices, gambot_get_invoice, gambot_update_invoice, gambot_issue_invoice
Orders	gambot_create_order, gambot_list_orders, gambot_get_order, gambot_update_order
Payments / transactions	gambot_list_transactions (payment/clearing transactions — "what did this customer pay/owe", filter by phone/status/entity), gambot_get_transaction (one transaction's full breakdown incl. VAT + items)
Signatures	gambot_list_signatures, gambot_get_signature, gambot_get_signature_link (signing link to distribute)
Web forms	gambot_list_forms, gambot_get_form, gambot_get_form_link (public link to distribute), gambot_get_form_submissions
Document templates	gambot_list_documents, gambot_get_document, gambot_create_document_link (distributable fill link), gambot_get_document_submissions
Users	gambot_create_user, gambot_list_users, gambot_get_user, gambot_update_user, gambot_enable_user, gambot_disable_user
Campaigns	gambot_list_campaigns, gambot_list_scheduled_campaigns, gambot_get_campaign, gambot_get_campaign_results, gambot_create_campaign (SAVED campaign — use for ANY scheduled send (once/recurring is always a campaign) or a reusable CRM-segment broadcast), gambot_send_campaign_from_excel (mail-merge blast from a sheet the user gave you — pass rows + phoneColumn + column→variable mapping; an Excel broadcast is always saved as a campaign — immediate = save + run now, scheduled = save + scheduler runs it), gambot_update_campaign, gambot_delete_campaign, gambot_run_campaign, gambot_send_campaign (immediate "run to a group": ad-hoc, unsaved send to a tag/segment/phone list), gambot_test_campaign (single recipient). Decision rule: group-run = immediate & unsaved (gambot_send_campaign); scheduled (once/recurring) = always a campaign (gambot_create_campaign); one-time Excel = always a campaign (gambot_send_campaign_from_excel). Prefer a template for broadcasts — a regular free-text broadcast only reaches recipients whose 24h window is open. Compliance is built in: every org has an ACTIVE opt-out flow (recipients reply הסר/stop/unsubscribe → excluded from future broadcasts); send/run responses echo it under optOut (enabled by default) and your consent under consent.
Bots & automations	gambot_deploy_bot_package (build a WHOLE bot in one call — main bot + activator + human-intervention cancel, linked as one package), gambot_list_bots, gambot_get_bot, gambot_get_bot_package (the whole bot: main + activator + human-intervention cancel + Gambot AI), gambot_create_keyword_autoreply, gambot_create_template_button_autoreply, gambot_create_menu_bot, gambot_create_bot (advanced, full step schema), gambot_create_facebook_lead_bot (auto-reply to new Facebook/Meta lead-form leads), gambot_set_bot_status (on/off; includePackage toggles the whole bot), gambot_delete_bot
Gambot AI (brain)	gambot_list_ai (the org's Gambot AI "brains" — purpose, tone, language, Q&A count), gambot_get_ai (one brain's full config), gambot_update_ai (PATCH — upgrade an existing brain; only the fields you pass change), gambot_create_ai (only if the org has none — check gambot_list_ai first)
Onboarding	gambot_check_organization, gambot_generate_organization_name, gambot_search_available_numbers (buy a number by country), gambot_send_onboarding_verification (6‑digit code to the customer's email + WhatsApp — required ONLY before creating an account that BUYS a number), gambot_verify_onboarding_code (verify that code), gambot_create_trial_account (free trial; free/coexistence/BYO/buy-a-SIM — buying a number needs a verified verificationId), gambot_create_paid_account (no trial, card required), gambot_add_payment_method (card on file), gambot_create_payment_link (Tranzila hosted), gambot_get_waba_connect_link, gambot_exchange_waba_token (complete Meta Embedded Signup), gambot_get_onboarding_status (poll until WhatsApp is connected)
Webhooks	gambot_register_webhook (register/update the URL Gambot POSTs events to — inbound messages, statuses, template updates; optional authHeader + per-event toggles), gambot_get_webhook (read current registration), gambot_test_webhook (fire a sample event and get the delivery result — verify your endpoint receives calls), gambot_delete_webhook (disable forwarding). For developers building a system that needs to receive messages/updates back in real time.
Connections	gambot_list_connections (the org's connected integrations — email & calendar OAuth, Facebook lead-ads pages, shop/CRM links, WhatsApp numbers; ids to use elsewhere)
Email	gambot_send_email (single email over a connected Google/Microsoft mailbox), gambot_list_email_campaigns, gambot_get_email_campaign, gambot_create_email_campaign (template or inline content; CRM segment or explicit recipients; run:true to send now), gambot_run_email_campaign (durable, resumable — safe for large lists, no duplicates)
Calendar	gambot_list_calendar_events (events in a date range from a connected Google/Microsoft calendar)
Facebook Lead Ads	gambot_list_facebook_lead_connections, gambot_list_facebook_lead_forms (leadgen forms of a connected page), gambot_create_facebook_lead_bot (auto-reply the moment a new lead arrives)

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:

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