@mulmobridge/messenger

Experimental — please test and report issues.

Facebook Messenger bridge for MulmoClaude. Uses the Meta Send/Receive API (webhook).

Setup

1. Create a Meta App with Messenger

1. Go to developers.facebook.com → Create App → Business type
2. Add the Messenger product
3. In Messenger Settings, connect a Facebook Page and generate a Page Access Token
4. Note the App Secret from Settings → Basic

2. Set up ngrok

ngrok http 3004

3. Configure webhook

In Meta Dashboard → Messenger → Settings → Webhooks:

• Callback URL: https://xxxx.ngrok-free.app/webhook
• Verify token: any string (set as MESSENGER_VERIFY_TOKEN)
• Subscribe to: messages

4. Run the bridge

# Testing with mock server
npx @mulmobridge/mock-server &
MESSENGER_PAGE_ACCESS_TOKEN=... \
MESSENGER_VERIFY_TOKEN=my-verify \
MESSENGER_APP_SECRET=... \
MULMOCLAUDE_AUTH_TOKEN=mock-test-token \
npx @mulmobridge/messenger

# With real MulmoClaude
MESSENGER_PAGE_ACCESS_TOKEN=... \
MESSENGER_VERIFY_TOKEN=my-verify \
MESSENGER_APP_SECRET=... \
npx @mulmobridge/messenger

Environment Variables

| Variable | Required | Description | | ------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MESSENGER_PAGE_ACCESS_TOKEN | Yes | Page access token | | MESSENGER_VERIFY_TOKEN | Yes | Arbitrary string for webhook verification | | MESSENGER_APP_SECRET | Yes | App secret for HMAC signature verification | | MESSENGER_BRIDGE_PORT | No | Webhook port (default: 3004; 0 asks the OS for a free port) | | MULMOCLAUDE_API_URL | No | Default: auto (.server-port; waits if nothing is published) | | MULMOCLAUDE_AUTH_TOKEN | No | Bearer token | | MESSENGER_BRIDGE_DEFAULT_ROLE | No | Role id to seed new bridge sessions with (e.g. coder, general). Applied ONLY when a messenger session first appears — once the user switches role via /role <id> the session's own role wins. Unknown role ids silently fall back to the server's default with a warn log. | | BRIDGE_DEFAULT_ROLE | No | Same as above but shared across every bridge. Transport-specific MESSENGER_BRIDGE_DEFAULT_ROLE wins when both are set. |

An unusable value (a typo, a number outside 0-65535) stops the bridge with a message naming the variable, rather than silently starting on the default. A port already in use is reported the same way (#3084).

Auth token persistence across server restarts

The MulmoClaude server regenerates a fresh bearer token on every startup and writes it to <workspace>/.session-token ($MULMOCLAUDE_WORKSPACE_PATH, or ~/mulmoclaude when unset), alongside the port it bound in .server-port.

The bridge follows a restart on its own. When the connection fails it re-reads both files, and if the server came back as a different generation — new token, new port, or both — it rebuilds its socket against it (#3078). You do not have to restart the bridge.

Pinning the token is still useful when the bridge runs on a different machine from the server, where it cannot read the workspace at all: set MULMOCLAUDE_AUTH_TOKEN to the same long random value on both sides. The server then uses it verbatim instead of regenerating.

# Server (one-time setup — same value across restarts)
MULMOCLAUDE_AUTH_TOKEN=long-random-string yarn dev

# Bridge (separate process / machine — same value)
MULMOCLAUDE_AUTH_TOKEN=long-random-string \
  <bridge-specific-envs> \
  npx <this-package>@latest

Recommended: at least 32 characters of random data (the server logs a warning at startup for shorter values).

Ecosystem

Part of the @mulmobridge/* package family.

Shared libraries:

• @mulmobridge/client — socket.io client library used by every bridge below
• @mulmobridge/protocol — wire types and constants
• @mulmobridge/chat-service — server-side relay + session store
• @mulmobridge/relay — Cloudflare Workers webhook proxy
• @mulmobridge/mock-server — mock server for local bridge development

Bridges (one npm package per platform):

• @mulmobridge/bluesky — Bluesky DMs over atproto
• @mulmobridge/chatwork — Chatwork (Japanese business chat)
• @mulmobridge/cli — interactive terminal bridge
• @mulmobridge/discord — Discord bot via Gateway
• @mulmobridge/email — IMAP poll + SMTP reply, threading preserved
• @mulmobridge/google-chat — Google Chat via MulmoBridge relay
• @mulmobridge/irc — IRC (Libera, Freenode, custom)
• @mulmobridge/line — LINE Messaging API via MulmoBridge relay
• @mulmobridge/line-works — LINE Works (enterprise LINE)
• @mulmobridge/mastodon — Mastodon DMs + mentions
• @mulmobridge/matrix — Matrix / Element
• @mulmobridge/mattermost — Mattermost
• @mulmobridge/messenger — Facebook Messenger via MulmoBridge relay ← this package
• @mulmobridge/nostr — Nostr NIP-04 encrypted DMs
• @mulmobridge/rocketchat — Rocket.Chat
• @mulmobridge/signal — Signal via signal-cli-rest-api
• @mulmobridge/slack — Slack Socket Mode
• @mulmobridge/teams — Microsoft Teams via Bot Framework
• @mulmobridge/telegram — Telegram bot
• @mulmobridge/twilio-sms — SMS via Twilio Programmable Messaging
• @mulmobridge/viber — Viber Public Account bots
• @mulmobridge/webhook — generic HTTP webhook bridge
• @mulmobridge/whatsapp — WhatsApp Cloud API via MulmoBridge relay
• @mulmobridge/xmpp — XMPP / Jabber
• @mulmobridge/zulip — Zulip

Related projects

Published from the MulmoClaude monorepo by Receptron.

• MulmoClaude — an open-source AI assistant platform that runs on your own computer. Claude Code as the engine, a personal wiki for long-term memory, schema-driven collections for your data, and chat that summons the right GUI (markdown, charts, forms, spreadsheets, wikis) for each task.
• MulmoTerminal — a terminal-first cockpit for running many AI coding agents in parallel. One roster showing every session's summary and PR status, tmux-backed session persistence, git-worktree isolation, one-click PRs, and mobile push with remote reply.
• MulmoTerminal manual — setup, workflows, feature reference, configuration, mobile notifications, and alternative / local model providers. Available in English and Japanese.

License

MIT