#17157: feat(messenger): add Facebook Messenger channel integration

## Summary - **Problem:** OpenClaw has no Facebook Messenger channel — users running Pages can't route DMs through the gateway. - **Why it matters:** Messenger has 1B+ MAU; this is a top-requested integration alongside existing Discord/Slack/Telegram/WhatsApp channels. - **What changed:** New plugin-based Messenger channel: webhook ingest with HMAC-SHA256 verification, outbound sends via Graph API v21.0, four DM access policies (pairing/allowlist/open/disabled), multi-account support, onboarding wizard, docs, and unit tests. - **What did NOT change (scope boundary):** No modifications to existing channels, gateway core, plugin SDK contract, or CLI commands. Docker-compose changes (ollama service) are from main merge, not this branch. ## Change Type (select all) - [ ] Bug fix - [x] Feature - [ ] Refactor - [x] Docs - [ ] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [x] Gateway / orchestration - [ ] Skills / tool execution - [x] Auth / tokens - [ ] Memory / storage - [x] Integrations - [ ] API / contracts - [x] UI / DX - [ ] CI/CD / infra ## User-visible / Behavior Changes - New channel available: `Facebook Messenger (Graph API)` - New onboarding wizard step for Messenger credential setup - New DM policy config: `channels.messenger.dmPolicy` (default: `pairing`) - New env vars for default account: `MESSENGER_PAGE_ACCESS_TOKEN`, `MESSENGER_APP_SECRET`, `MESSENGER_VERIFY_TOKEN` - New webhook endpoint: `GET/POST /messenger/webhook` - New docs page: `docs/channels/messenger.md` - `openclaw channels status --deep` now includes Messenger probe output ## Security Impact (required) - New permissions/capabilities? `Yes` — webhook endpoint accepts inbound HTTP from Meta - Secrets/tokens handling changed? `Yes` — new Page Access Token + App Secret resolution chain (config → file → env) - New/changed network calls? `Yes` — outbound to `graph.facebook.com/v21.0` (send messages, fetch profiles) - Command/tool execution surface changed? `No` - Data access scope changed? `No` - **Risk + mitigation:** - Webhook spoofing → mandatory HMAC-SHA256 signature verification with `crypto.timingSafeEqual` - Token leakage → credentials never logged; file-based storage supported; env vars restricted to default account only - Unauthorized DMs → default policy is `pairing` (requires admin approval before any sender can interact) - Echo loops → outbound messages from the page are explicitly filtered out ## Repro + Verification ### Environment - OS: Linux (Docker or bare metal) - Runtime/container: Node 22+ / pnpm - Model/provider: Any (channel-agnostic) - Integration/channel: Facebook Messenger via Meta Graph API v21.0 - Relevant config: `channels.messenger.*` in openclaw config ### Steps 1. Configure Messenger credentials (via `openclaw setup` wizard or env vars) 2. Start gateway — verify webhook challenge response at `GET /messenger/webhook?hub.mode=subscribe&hub.verify_token=<token>&hub.challenge=<challenge>` 3. Send DM to configured Facebook Page 4. Observe inbound routing + auto-reply delivery ### Expected - Webhook verification returns challenge string with 200 - Inbound DM triggers auto-reply flow - Outbound reply delivered to sender in Messenger ### Actual - Works as expected (verified on a live Facebook Page — see Human Verification below) ## Evidence - [x] Failing test/log before + passing after - [ ] Trace/log snippets - [ ] Screenshot/recording - [ ] Perf numbers (if relevant) Unit tests added: - `extensions/messenger/src/channel.test.ts` — plugin structure, credential validation - `src/messenger/accounts.test.ts` — multi-source credential resolution - `src/messenger/bot-handlers.test.ts` — DM policy enforcement - `src/messenger/probe.test.ts` — Graph API probe - `src/messenger/send.test.ts` — outbound send + chunking - `src/messenger/signature.test.ts` — HMAC-SHA256 verification + timing-safe compare ## Human Verification (required) - **Verified scenarios:** Ran a personal Facebook Page with Messenger configured as the main channel on a live OpenClaw instance. Verified end-to-end: webhook registration + challenge, inbound DM routing, auto-reply delivery back to Messenger, pairing flow for new senders, credential resolution from config/env. - **Edge cases checked:** Missing/invalid signature header rejection, echo event filtering, message chunking at 2000 char boundary, media attachment download (image). - **What you did NOT verify:** Production-scale load testing, multiple simultaneous accounts, file-based credential paths, video/audio/file media types (only image tested end-to-end). ## Compatibility / Migration - Backward compatible? `Yes` — purely additive, no existing behavior changed - Config/env changes? `Yes` — new optional `channels.messenger.*` config block and env vars - Migration needed? `No` ## Failure Recovery (if this breaks) - **How to disable/revert:** Set `channels.messenger.enabled: false` in config, or remove Messenger env vars, or revert this PR - **Files/config to restore:** No migration — removing config entries disables the channel - **Known bad symptoms:** Webhook 403s (bad verify token), send failures (expired page token), signature validation errors in logs (bad app secret) ## Risks and Mitigations - **Risk:** Meta Graph API rate limits on high-volume pages - **Mitigation:** Async event processing with immediate 200 response; no retry loop on send failures - **Risk:** Page Access Token expiration (short-lived tokens) - **Mitigation:** Documented in `docs/channels/messenger.md`; probe endpoint surfaces token validity issues ## AI-Assisted - [x] AI-assisted (Claude Code Opus 4.6) - [x] Fully tested (unit tests + live Facebook Page end-to-end) - [x] I understand what the code does <!-- greptile_comment --> <h3>Greptile Summary</h3> Adds Facebook Messenger channel integration with webhook-based message handling via Meta Graph API v21.0. Implements HMAC-SHA256 signature verification for webhook security, multi-account credential resolution (config/file/env), and DM policy enforcement (pairing/allowlist/open/disabled). Includes comprehensive test coverage and documentation. **Key Changes:** - New `extensions/messenger` plugin with channel adapter - Core implementation in `src/messenger/`: accounts, bot handlers, message sending, signature validation, webhook monitor - Onboarding wizard integration in `src/channels/plugins/onboarding/messenger.ts` - Webhook endpoint at `/messenger/webhook` (GET for verification, POST for events) - Message chunking at 2000-char limit, media attachment support - Complete test suite covering signature validation, accounts, DM policy, sending, probing **Issues Found:** - Potential infinite loop in `sendMessageMessenger` when recursively calling `sendMediaMessenger` (see inline comment) <h3>Confidence Score: 4/5</h3> - Safe to merge after fixing the recursive call issue in sendMessageMessenger - Strong implementation with proper security (HMAC-SHA256 with timing-safe comparison), comprehensive tests, and good error handling. One logical bug found that could cause infinite loop. Credential handling follows secure patterns, webhook verification is robust, and DM policy enforcement is sound. The integration follows existing channel patterns closely. - Pay attention to `src/messenger/send.ts:72-80` - fix the recursive call before merging _{Last reviewed commit: e039966} <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->