Dot WhatsApp Bridge

A self-hosted, single-owner bridge between Meta's WhatsApp Agent Platform and a ChatGPT client that supports MCP Events. Receive messages and attachments in your existing chat, then reply through creator-bound MCP tools. The bridge does not run an AI model or require an OpenAI API key.

The current MCP server release is 0.5.0. This repository provides software to deploy in your own account; it does not provide a hosted public endpoint. WhatsApp Agent Platform access, custom MCP connections, and MCP Events must be available to your accounts. A client that supports ordinary MCP tool calls may still lack event subscriptions. This is an independent integration, not an official Meta, OpenAI, or Vercel product.

How it works

A Vercel Daemon long-polls WhatsApp, verifies the agent's creator, prepares attachments, and delivers signed events to the subscribed client. Next.js Functions serve OAuth, MCP, and the private owner setup page. Private Vercel Blob stores configuration, the poll cursor, subscriptions, a recovery inbox, and durable send records. State updates use conditional writes; a lease coordinates worker handover.

Replies require an exact received message ID and go only to the verified creator. There is no free-form recipient or unsolicited-send tool. The bridge supports one owner, text, and attachments; it does not support groups or outgoing reactions.

Related MCP server: WAB bot

Install in your own Vercel project

Prerequisites: Node.js 24, npm, a Vercel account with Daemons and private Blob available, a dedicated WhatsApp agent API key, and a compatible ChatGPT MCP Events client. Hosting and storage may incur charges.

1. Create your own copy of this source and install dependencies:

   npm ci
   npm test
   npm run typecheck
   npm run build

2. Create a Vercel project for this source, use the Next.js preset, and select Node.js 24 for Functions. The checked-in vercel.json defines one daemon instance in iad1; its Dockerfile uses Node.js 24 and installs FFmpeg and Poppler for incoming attachment previews. Choose a compatible private Blob region for your deployment.

3. Connect a private Blob store to this project and configure production environment variables for both Functions and the daemon:

   Variable	Value
   BRIDGE_ORIGIN	Your stable HTTPS origin, such as https://your-bridge.example, without a trailing slash or path
   BRIDGE_SECRET	A cryptographically random secret with at least 32 characters; this is also the owner password
   BLOB_STORE_ID	Your connected private Blob store ID, using the project's Vercel OIDC identity

   Generate a secret with a password manager or openssl rand -hex 32, save it privately, and enter it as a sensitive environment variable. Never commit it. BLOB_READ_WRITE_TOKEN is a supported credential fallback when OIDC is unavailable; prefer OIDC and do not set a fallback unnecessarily. Vercel supplies VERCEL_ENV=production. See .env.example for variable names.

4. Deploy to your own project. Confirm the selected Vercel project and account before deploying; do not use another installation's store, credentials, or project link. Once ready, check /health on your origin. The optional public smoke check requires an explicit origin:

   BRIDGE_ORIGIN=https://your-bridge.example node scripts/smoke.mjs

   This script performs unauthenticated read-only checks. It does not configure the bridge, authenticate as the owner, or send WhatsApp messages.

5. Create a dedicated agent in WhatsApp and obtain its API key. Use only one poller per key. Do not share a key with another gateway or local worker. Open your origin's /setup, sign in with BRIDGE_SECRET, configure the WhatsApp key, and enable the bridge. The key is encrypted before persistence.

6. Add your origin's /mcp endpoint as a custom MCP connection in the compatible client. Select OAuth and authorize with your owner password. If a predefined client ID is requested, use dot-whatsapp, without a client secret. Dynamic registration is also supported. OAuth redirects are intentionally restricted to the ChatGPT callbacks allowed by the source; arbitrary MCP clients are not currently supported.

7. In the intended chat, request a WhatsApp event subscription and authorize the conversational replies you want. Event subscriptions use MCP protocol 2026-07-28. Check /setup for an active subscription, then send a new message yourself and verify the reply arrives. Refresh the client's tool catalog after upgrading so it can see the current tool arguments.

Client scheduling and authorization remain outside the bridge. Event acceptance does not prove that the client ran a task or sent a reply. See operations and recovery for listener guidance and diagnosis.

Tools and multiple replies

Use a stable operationId for each intentional reply to the same incoming messageId. Retrying the same operation with the same content deduplicates; another intentional reply needs another operation ID. Never change IDs to bypass a pending or uncertain send.

whatsapp_reply({
  messageId: exactIncomingId,
  operationId: "progress",
  complete: false,
  text: "I’m working on it."
});

whatsapp_reply({
  messageId: exactIncomingId,
  operationId: "result",
  complete: true,
  text: "Here is the result."
});

complete defaults to true; false requires an explicit operation ID. Progress keeps the request recoverable. Successful completion removes its retained incoming body, while a later explicit follow-up remains possible within the retained authorization window. Calls without an operation ID retain the legacy single-reply slot. Text and file replies share an operation namespace and a rolling limit of 12 reserved send attempts per minute.

Incoming bodies are retained for up to 24 hours. Body-free reply authorization contexts last 30 days from verified receipt; this is a local policy, not a guarantee of provider acceptance. Pending and uncertain records remain guarded against resend. Version 0.5.0 writes state format v2: after upgrading, rollback requires a v2-compatible build. Do not restore an old binary or stale state to clear a send record.

Development and licensing

Automated tests use mocked transports. The Docker build also generates synthetic media fixtures for native preview checks. Never use a production WhatsApp key or production Blob store for development. Local worker execution is intentionally gated; see CONTRIBUTING.md.

Read SECURITY.md before reporting private data or vulnerabilities, and THIRD_PARTY_NOTICES.md before distributing dependencies or container images.

Project-owned code is licensed under the MIT License. Dependencies and other third-party materials retain their own terms; see third-party notices.

References

• WhatsApp Agent Platform developer manual

• OpenAI MCP Events

• OpenAI MCP authentication

• Vercel Daemons

• Hermes WhatsApp integration