# 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|POST /wp-json/teddy/v1/channels/facebook/webhook` |
| 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](https://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:

```bash
# 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

```bash
# 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](./PHASE-2.md): Page publish, Instagram DM, Zalo OA, Telegram.