> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leapfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Channel integrations

> How Lola Send connects to messaging platforms through pluggable channel connectors.

Celai's connector architecture is pluggable — adding a new messaging channel requires implementing a connector adapter, not changing agent logic. Connectors normalize inbound messages into Celai's internal format and format outbound responses for the target platform. Agents remain channel-agnostic.

## Supported channels

| Channel  | Connector            | Status      | Notes                               |
| -------- | -------------------- | ----------- | ----------------------------------- |
| WhatsApp | `WhatsappConnector`  | Primary     | Business API; allowlist-controlled  |
| Telegram | `TelegramConnector`  | Supported   | Ready to enable                     |
| Chatwoot | `ChatwootMiddleware` | Omnichannel | Human handoff and conversation sync |

## WhatsApp connector

WhatsApp is the primary messaging channel. The connector integrates with the WhatsApp Business API and is configured with:

| Configuration   | Environment variable       | Purpose                                            |
| --------------- | -------------------------- | -------------------------------------------------- |
| API token       | `TOKEN_WHATSAPP`           | Authentication with the WhatsApp Business API      |
| Phone number ID | `PHONE_NUMBER_ID`          | The WhatsApp Business phone number identifier      |
| Verify token    | `VERIFY_TOKEN_WHATSAPP`    | Webhook verification handshake                     |
| Allowed numbers | `ALLOWED_NUMBERS_WHATSAPP` | Comma-separated list for phone number allowlisting |

### Stream mode

The connector operates in `FULL` stream mode — the AI model generates the complete response before it is sent to the sender. This ensures message enhancement and formatting run on the complete text, not on partial fragments.

### Message type restrictions

The WhatsApp connector rejects document and image messages. When a sender sends a file, the LogicRouter's event handler intercepts it and responds with a text-only notification. This restriction ensures all conversation data flows through the text processing pipeline.

### Phone number allowlisting

`ALLOWED_NUMBERS_WHATSAPP` accepts a comma-separated list of phone numbers. Only numbers on this list can interact with Lola Send through the WhatsApp channel. This enables:

* **Controlled rollouts** — deploy to a subset of senders before general availability
* **Phased onboarding** — add senders incrementally as the bank expands service
* **Testing isolation** — restrict access to internal testers during development

```python theme={null}
allowed_number = os.environ.get("ALLOWED_NUMBERS_WHATSAPP")
allowed_number = allowed_number.split(",")

whatsapp_conn = WhatsappConnector(
    token=os.environ.get("TOKEN_WHATSAPP"),
    phone_number_id=os.environ.get("PHONE_NUMBER_ID"),
    verify_token=os.environ.get("VERIFY_TOKEN_WHATSAPP"),
    stream_mode=StreamMode.FULL,
    allowed_numbers=allowed_number,
)
```

## Telegram connector

The Telegram connector is built and ready to enable. It uses the same `StreamMode.FULL` configuration and connects via a bot token. Currently disabled in production — enabling it requires setting the `TELEGRAM_TOKEN` environment variable and registering the connector with the gateway.

<Info>
  Enabling Telegram requires no changes to agent logic, middleware, or routing. The connector normalizes Telegram messages into the same internal format used by WhatsApp.
</Info>

## Chatwoot integration

Chatwoot integration is implemented as middleware rather than a connector. It syncs all conversations to a Chatwoot inbox, providing:

* **Human agent visibility** — live monitoring of all active conversations
* **Escalation** — human agents can take over any conversation at any point
* **Conversation history** — full audit trail in the Chatwoot dashboard

| Configuration  | Environment variable         |
| -------------- | ---------------------------- |
| Enable/disable | `CHATWOOT_ENABLE_MIDDLEWARE` |
| Chatwoot URL   | `CHATWOOT_URL`               |
| Access key     | `CHATWOOT_ACCESS_KEY`        |
| Account ID     | `CHATWOOT_ACCOUNT_ID`        |
| Inbox name     | `CHATWOOT_INBOX_NAME`        |

Chatwoot is optional and can be disabled without affecting agent behavior or message processing.

## Pluggable architecture

To add a new channel, implement a connector that:

1. **Receives** inbound messages from the channel's webhook or API
2. **Normalizes** them into Celai's internal `Message` format
3. **Formats** outbound `OutgoingMessage` objects for the channel's delivery API
4. **Registers** with the MessageGateway via `gateway.register_connector(connector)`

Agent logic, middleware pipeline, routing, and state management remain unchanged. The new channel participates in the same processing pipeline as all existing channels.

## Security considerations

* **Allowlisting**: WhatsApp number allowlists restrict which senders can interact with Lola Send, enabling controlled rollouts and preventing unauthorized access during deployment phases.
* **Channel-agnostic security**: Authentication and identity verification happen in the middleware pipeline, not in the connector. Every channel benefits from the same security middleware.
* **Webhook verification**: The WhatsApp connector uses a verify token for webhook handshake, preventing unauthorized webhook registrations.

## Configuration and control

| Control           | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| Channel selection | The bank chooses which channels are active by registering connectors |
| Allowlists        | Phone number lists for controlled access on WhatsApp                 |
| Chatwoot          | Independently enabled or disabled; configured per deployment         |
| Stream mode       | Full message delivery ensures complete formatting before sending     |
| New channels      | Add connectors without modifying agents, middleware, or routing      |