Channels

A Channel defines how a recommendation reaches a customer. While Offers define what to recommend and Decision Flows decide which offer to show, Channels handle the last mile: delivery mode, impression tracking, and provider integration. Each channel can have multiple placements (named slots like hero_banner or sidebar_widget) and connects to Creatives that contain the actual content. When you create a channel, KaireonAI automatically routes it to your default Decision Flow so it works immediately — no manual wiring required.

Channels are delivery-agnostic containers. The same offer can be delivered through email, push, and in-app simultaneously, each with different creatives optimized for that channel.

How Channels Work

You create a channel with a type (email, push, etc.), delivery mode, and impression tracking method
You add placements — named slots where content appears (e.g., hero_banner, checkout_upsell)
You create creatives — content variants linked to specific offers and channels
At recommendation time, the Decision Flow matches candidates to creatives for the requested channel and allocates them across placements

Channel Types

Type	Description	Common Use Cases
`email`	Email delivery	Marketing campaigns, transactional messages
`push`	Mobile push notifications	Real-time alerts, engagement nudges
`sms`	SMS text messages	Time-sensitive alerts, verification
`in_app`	In-application messages	Contextual recommendations, banners
`web`	Web browser (banners, overlays)	Website personalization
`webhook`	HTTP callback to external system	Custom integrations, third-party platforms
`whatsapp`	WhatsApp Business messages	Conversational commerce, order updates
`direct_mail`	Physical mail	High-value customer outreach

Starbucks Example

Channel	Type	Placements	Use Case
Mobile App	`in_app`	`home_carousel`, `order_screen_upsell`	BOGO offers, Stars promotions shown during ordering
Starbucks Email	`email`	`header_offer`, `body_cross_sell`	Weekly promotional emails with personalized offers
Push Notifications	`push`	`morning_digest`, `happy_hour_alert`	Time-sensitive flash sales, nearby store promos
Web	`web`	`hero_banner`, `sidebar_widget`	Website personalization for logged-in rewards members

Delivery Modes

Each channel operates in one of four modes that control how recommendations reach the customer:

API (Real-time)

External systems call the /api/v1/recommend endpoint to pull decisions in real time. The response includes ranked offers with their creatives, and the calling system renders them.Best for: Web personalization, in-app messages, real-time push, webhook integrations.Latency: Typically under 200ms end-to-end.

File (Batch)

Recommendations are exported as a file for ingestion by an external system. Configure format and destination in fileConfig.Supported formats:

Format	Description
`csv`	Comma-separated (configurable delimiter)
`tsv`	Tab-separated
`json`	JSON array of records
`jsonl`	JSON Lines (one object per line)
`parquet`	Apache Parquet columnar format
`fixed_width`	Fixed-width positional columns
`pipe_delimited`	Pipe-delimited values

Best for: Email campaign systems, direct mail vendors, data warehouse ingestion, batch CRM integrations.Destination: Files can be pushed to cloud storage connectors (S3, GCS, Azure Blob).

Integration (Provider)

Delivers recommendations via a platform integration with a specific provider. Provider credentials are stored encrypted in providerConfig.Best for: Managed delivery through SendGrid, Twilio, Firebase, WhatsApp Business API.Flow: Pipeline executes, creative content is assembled, delivery request is sent to the provider API.

Manual (Human Workflow)

Recommendations appear in a queue for agents or relationship managers to act on. No automated delivery — KaireonAI tracks decisions and outcomes.Best for: High-touch sales, advisory conversations, branch operations, call center agents.

Placements

A placement is a named slot within a channel where content can appear. Placements let you request recommendations for a specific slot, track performance per placement, and control how many offers appear in each position.

Channel	Placement	`slotType`	`maxSlots`
Web	`hero_banner`	`banner`	1
Web	`sidebar_widget`	`card`	3
Email	`header_offer`	`banner`	1
Email	`body_recommendation`	`card`	3
In-App	`home_carousel`	`card`	5
Push	`morning_digest`	`notification`	1

When used with the Composable Pipeline Group node, placements control how ranked offers are allocated across multiple slots in a single response.

Placement Fields

Field	Type	Required	Default	Description
`name`	string	Yes	—	Unique slot identifier (e.g., `hero_banner`)
`description`	string	No	`""`	Human-readable description
`slotType`	string	No	`"banner"`	Visual type: `banner`, `card`, `modal`, `notification`
`maxSlots`	integer	No	`1`	Maximum offers this placement can show
`schema`	object	No	`{}`	Content schema requirements
`targeting`	object	No	`{}`	Targeting rules for this placement

Impression Tracking

Channels control how customer impressions (views) are recorded. This affects contact policy enforcement and dashboard metrics.

Explicit (Default)
Implicit

The client application calls the Respond API after displaying the recommendation. You get precise control over when an impression is counted.

POST /api/v1/respond
{
  "customerId": "cust_123",
  "offerId": "act_abc",
  "channelId": "ch_email",
  "outcome": "impression"
}

When to use: Any channel where you can confirm the customer actually saw the recommendation (web, in-app, email opens).

Delivery Providers

When using Integration delivery mode, KaireonAI sends messages through configured providers. All providers support delivery tracking, idempotency, circuit breakers, and retry logic.

Provider	Channel Type	Configuration
AWS SES	`email`	Region, From Email, Reply-To
Twilio	`sms`	Account SID, Auth Token, From Number
Amazon SNS	`sms`, `push`	Region, Auth Mode, Sender ID
Firebase	`push`	Project ID, Service Account JSON
WhatsApp (Meta)	`whatsapp`	Phone Number ID, Access Token, API Version
WhatsApp (Twilio)	`whatsapp`	Account SID, Auth Token, From Number
Webhook	`webhook`	Target URL, Headers

WhatsApp Integration

KaireonAI supports WhatsApp Business messaging through two providers:

Meta Cloud API (Recommended)
Twilio WhatsApp

Direct integration with the official WhatsApp Business API. Supports template messages, text messages, and media messages.Setup:

Create a Meta Business account and WhatsApp Business app at developers.facebook.com
Get your Phone Number ID and permanent access token
Configure in Settings > Integrations > WhatsApp or via environment variables:
- WHATSAPP_PROVIDER=meta
- WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
- WHATSAPP_ACCESS_TOKEN=your_access_token
Set up the webhook at POST /api/v1/webhooks/whatsapp for delivery status callbacks

Uses Twilio’s WhatsApp Business API integration (same SDK as SMS).Setup:

Enable WhatsApp in your Twilio account
Get a WhatsApp-approved number
Configure via environment variables:
- WHATSAPP_PROVIDER=twilio
- WHATSAPP_TWILIO_ACCOUNT_SID=your_sid
- WHATSAPP_TWILIO_AUTH_TOKEN=your_token
- WHATSAPP_TWILIO_FROM_NUMBER=+14155238886

Auto-Routing to Decision Flows

When you create a channel or add a placement, KaireonAI automatically creates FlowRoutes linking them to the tenant’s default Decision Flow. New channels work immediately without manual routing setup.

New channel — FlowRoute created to the default flow
New placement — FlowRoute created to the default flow

You can override any auto-created route from the channel detail page or the Decision Flow configuration.

Auto-routing only creates routes to the default flow. To route a channel to a different flow, create the route manually or change the default flow first.

Provider Config

Each channel can store provider-specific configuration for external delivery:

{
  "provider": "sendgrid",
  "apiKey": "SG.xxxxx",
  "fromEmail": "offers@yourcompany.com",
  "fromName": "Your Company",
  "templateEngine": "handlebars"
}

Provider config is stored encrypted. API keys and credentials are never returned in GET responses.

Creating a Channel

Navigate to Channels

Go to Studio > Channels in the sidebar.

Click + New Channel

Click the + New Channel button.

Select type and delivery mode

Choose a channel type (email, push, etc.) and delivery mode (API, File, Integration, Manual).

Set impression tracking

Choose Explicit (default) or Implicit.

Add placements (optional)

Define named slots. Each placement has a name, slot type, and max offers.

Configure provider (optional)

Enter provider credentials for external delivery.

Save

The channel is immediately available for creatives and Decision Flows.

Field Reference

Field	Type	Required	Default	Description
`name`	string	Yes	—	Display name (1—255 chars)
`channelType`	string	No	`"email"`	`email`, `push`, `sms`, `in_app`, `web`, `webhook`, `whatsapp`, `direct_mail`
`status`	enum	No	`"draft"`	`draft`, `active`, `paused`, `archived`
`description`	string	No	`""`	Free-text description
`deliveryMode`	enum	No	`"api"`	`api`, `file`, `integration`, `manual`
`impressionMode`	enum	No	`"explicit"`	`explicit` or `implicit`
`providerConfig`	object	No	`{}`	Provider credentials (stored encrypted)
`fileConfig`	object	No	`{}`	File delivery settings (format, columns, destination)
`placements`	array	No	—	Named slots (see Placement Fields above)

API Quick Reference

Create

POST /api/v1/channels

{
  "name": "Starbucks Mobile",
  "channelType": "in_app",
  "deliveryMode": "api",
  "impressionMode": "explicit",
  "placements": [
    { "name": "home_carousel", "description": "Homepage offer carousel", "slotType": "card", "maxSlots": 5 },
    { "name": "order_screen_upsell", "description": "Add-on suggestion during ordering", "slotType": "card", "maxSlots": 2 }
  ]
}

Response: 201 Created with the full channel object.

List / Update / Delete

GET /api/v1/channels          # List all channels
PUT /api/v1/channels          # Update (send id in body)
DELETE /api/v1/channels?id={id}  # Delete

Deleting a channel also removes all associated placements. Creatives linked to this channel become orphaned and should be reassigned or deleted.

Next Steps

Creatives

Create content variants for each offer on this channel.

Decision Flows

Build pipelines that select and deliver offers through channels.

Composable Pipeline

Use the Group node to allocate offers across placements.

Contact Policies

Set frequency caps and suppression rules per channel.

Get Started

Deploy & Operate

Runbooks

Data Platform

Decisioning Studio

Execute & Optimize

Intelligence

Platform & Security

Integrations

Reports

Release Notes

How Channels Work

Channel Types

Starbucks Example

Delivery Modes

Placements

Placement Fields

Impression Tracking

Delivery Providers

WhatsApp Integration

Auto-Routing to Decision Flows

Provider Config

Creating a Channel

Field Reference

API Quick Reference

Create

List / Update / Delete

Next Steps

Creatives

Decision Flows

Composable Pipeline

Contact Policies

Get Started

Deploy & Operate

Runbooks

Data Platform

Decisioning Studio

Execute & Optimize

Intelligence

Platform & Security

Integrations

Reports

Release Notes

​How Channels Work

​Channel Types

​Starbucks Example

​Delivery Modes

​Placements

​Placement Fields

​Impression Tracking

​Delivery Providers

​WhatsApp Integration

​Auto-Routing to Decision Flows

​Provider Config

​Creating a Channel

​Field Reference

​API Quick Reference

​Create

​List / Update / Delete

​Next Steps

Creatives

Decision Flows

Composable Pipeline

Contact Policies

How Channels Work

Channel Types

Starbucks Example

Delivery Modes

Placements

Placement Fields

Impression Tracking

Delivery Providers

WhatsApp Integration

Auto-Routing to Decision Flows

Provider Config

Creating a Channel

Field Reference

API Quick Reference

Create

List / Update / Delete

Next Steps