Channels (multi-channel messaging)

Channels (multi-channel messaging) Teddy routes external messaging platforms through a thin adapter layer into the same public chat + RAG pipeline as the site widget. Architecture Facebook / future channels │ ▼…

v5 README.md Download markdown Updated July 18, 2026

Channels (multi-channel messaging)#

Teddy routes external messaging platforms through a thin adapter layer into the same public chat + RAG pipeline as the site widget.

Architecture#

Facebook / future channels
        │
        ▼
ChannelAdapterInterface  (verify / parse / send)
        │
        ▼
ChannelIngressService → ChatDispatcher (scope=public)
        │
        ▼
Adapter.send_reply()

Facebook Messenger (v1)#

Item Value
REST `GET
Settings Teddy → Settings → Channels
Session id bean_ch_facebook_{psid}
Rate limit Same rate_limit setting, keyed per PSID

Meta checklist (ops)#

  1. developers.facebook.com → Create App → type Business

  2. Add product Messenger

  3. Link your Facebook Page

  4. Generate a Page access token → extend to long-lived

  5. App → Webhooks → Callback URL:

    https://YOUR-PUBLIC-HTTPS/wp-json/teddy/v1/channels/facebook/webhook

  6. Verify token = value saved in Teddy Settings → Channels

  7. Subscribe fields: messages, messaging_postbacks

  8. Subscribe the Page to the webhook

  9. Paste token + optional App Secret into Teddy Settings; enable Messenger

Local Docker#

Meta cannot call *.test. Use a tunnel:

# Cloudflare quick tunnel example (point at your proxy HTTPS or localhost:port)
cloudflared tunnel --url https://blackbean.test

Then set the Meta callback to the tunnel URL + /wp-json/teddy/v1/channels/facebook/webhook.

Development mode: only users with roles on the app/Page can message the bot until App Review / Live.

Test without Meta#

# Webhook verify
curl -s "https://SITE/wp-json/teddy/v1/channels/facebook/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=12345"
# expect: 12345

# Fake inbound (signature skipped if App Secret empty)
curl -s -X POST "https://SITE/wp-json/teddy/v1/channels/facebook/webhook" \
  -H "Content-Type: application/json" \
  -d '{"object":"page","entry":[{"id":"PAGE","messaging":[{"sender":{"id":"USER1"},"message":{"text":"Hello"}}]}]}'

Classes#

  • Bean\Teddy\Channels\ChannelMessage
  • Bean\Teddy\Channels\ChannelAdapterInterface
  • Bean\Teddy\Channels\FacebookMessengerAdapter
  • Bean\Teddy\Channels\ChannelIngressService
  • Bean\Teddy\REST\ChannelsController
  • Bean\Teddy\Channels\ChannelsServiceProvider

Phase 2 (not in v1)#

See PHASE-2.md: Page publish, Instagram DM, Zalo OA, Telegram.