Channel integrations

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

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.

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

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:

Receives inbound messages from the channel’s webhook or API
Normalizes them into Celai’s internal Message format
Formats outbound OutgoingMessage objects for the channel’s delivery API
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

Core framework

Channels and messaging

Data and knowledge

Supported channels

WhatsApp connector

Stream mode

Message type restrictions

Phone number allowlisting

Telegram connector

Chatwoot integration

Pluggable architecture

Security considerations

Configuration and control

​Supported channels

​WhatsApp connector

​Stream mode

​Message type restrictions

​Phone number allowlisting

​Telegram connector

​Chatwoot integration

​Pluggable architecture

​Security considerations

​Configuration and control

Supported channels

WhatsApp connector

Stream mode

Message type restrictions

Phone number allowlisting

Telegram connector

Chatwoot integration

Pluggable architecture

Security considerations

Configuration and control