Channels

The Channels module (@runflow-ai/sdk/channels) is a thin translation layer between messaging channels and your agent. It does two things:

Parses each raw webhook request into a normalized InboundEvent
Renders and sends channel-agnostic OutboundMessages, absorbing each channel’s quirks (text chunking, button limits, media fixups, interactive fallbacks)

Available from @runflow-ai/sdk v1.5.0:

import { createChannelHandler, meta, reply } from '@runflow-ai/sdk/channels';

Everything is explicit — no magic. You import a provider factory (meta(), telegram(), …) and pass it. There is no global registry and no side-effect imports. Outbound messages are POSTed through the SDK connector, so credentials stay server-side — your agent code never holds a channel token.

Who does what

The module deliberately owns no flow control and imposes no state contract:

Layer	Responsibility
Platform (HTTP trigger)	Flow control: coalesces the inbound burst by a configured key (debounce), dedup, ordering, retry, webhook auth. Delivers one turn with `input.events[]` already grouped — the coalescing key doubles as the user identity.
Channels module (this page)	Translation only: raw request → `InboundEvent`, `OutboundMessage` → channel wire format.
Your project	The turn: agent + domain logic, prompts, and your own state.

When a user sends 3 quick messages, the platform groups them into a single execution and your handler receives all 3 events at once — no manual debouncing.

Quick start

The whole entry point:

main.ts

import { createChannelHandler, meta } from '@runflow-ai/sdk/channels';
import { runTurn } from './agent/runner';

export default createChannelHandler({
  provider: meta({ connector: 'whatsapp-acme', phoneNumberId: '123456789012345' }),
  run: runTurn,
});

Your domain logic receives the whole coalesced burst, already parsed:

agent/runner.ts

import { reply, type RunTurn } from '@runflow-ai/sdk/channels';
import { agent } from './agent';

export const runTurn: RunTurn = async ({ ctx, events }) => {
  const text = events
    .map((e) => ('text' in e ? e.text : `[${e.type}]`))
    .join('\n');

  const result = await agent.process({
    message: text,
    userId: ctx.userId, // = the coalescing key = the identity
  });

  return [reply.text(result.message)];
};

Return an array of messages and the provider renders each one for the channel — chunking, button limits and media formats are handled for you.

Inbound events

InboundEvent is a discriminated union. Every event carries userId (the stable conversation key), plus messageId, profileName and raw (the original payload, as an escape hatch) when the channel provides them.

`type`	Payload fields	Notes
`text`	`text`	Plain message
`button`	`payload`, `text`	Quick-reply / inline button tap
`audio`	`mediaId`, `mimeType?`	Voice note — resolve with `fetchMedia`
`image`	`mediaId`, `mimeType?`, `caption?`
`video`	`mediaId`, `mimeType?`, `caption?`
`document`	`mediaId`, `mimeType?`, `filename?`, `caption?`
`location`	`latitude`, `longitude`, `name?`
`contacts`	`contacts: { name, phone }[]`	Shared contact cards
`flow-reply`	`responseData`	WhatsApp Flow form submission
`unknown`	`messageType`	Unrecognized payload — inspect `raw`

Malformed events never take down the burst: each event is parsed in isolation, and non-message payloads (status callbacks, a bot’s own messages) are silently skipped.

Replying

Build outbound messages with the reply helpers:

import { reply } from '@runflow-ai/sdk/channels';

return [
  reply.text('Pedido confirmado!'),
  reply.buttons('Como quer receber?', [
    { id: 'pickup', label: 'Retirar na loja' },
    { id: 'delivery', label: 'Entrega' },
  ]),
  reply.image('https://cdn.acme.com/receipt.png', 'Seu comprovante'),
  reply.document('https://cdn.acme.com/contract.pdf', { filename: 'contrato.pdf' }),
  reply.audio('https://cdn.acme.com/voice.ogg'),
  reply.link('Acompanhe seu pedido', 'Rastrear', 'https://acme.com/track/123'),
  reply.flow('1234567890', 'Finalize seu cadastro', 'Abrir formulário'),
];

Messages are channel-agnostic — the provider renders each type to the channel’s wire format and degrades gracefully where the channel lacks a feature (e.g. buttons become a numbered text list on channels without interactive messages). Replies are sent sequentially (chat order matters). If one fails, the remaining messages are marked skipped — never attempted — so a platform retry can resend the tail without duplicating the head.

Providers

WhatsApp Cloud — `meta()`

meta({ connector: 'whatsapp-acme', phoneNumberId: '123456789012345' })

Option	Default	Description
`connector`	trigger binding	Connector instance slug
`phoneNumberId`	trigger binding	The `phone_number_id` used on the send URL
`sendResource`	`'send-message'`	Resource slug for sending (passthrough to `POST /{phone_number_id}/messages`)
`mediaResource`	`'get-media-url'`	Resource slug for resolving inbound media ids

The Meta provider bakes in real production lessons so you don’t relearn them:

Text clipped at 4,096 chars; interactive bodies at 1,024 (avoids error 131009) — a longer body is sent as text followed by the buttons
Max 3 buttons (Meta’s limit) — zero or more than 3 degrade to a numbered text list; button titles clipped at 20 chars
.webp image URLs rewritten to .jpg (Meta rejects webp with error 131053, often silently)
Brazilian phone numbers normalized (legacy 12-digit numbers get the mobile 9 inserted — landlines untouched)
Typing indicator piggybacks on mark-as-read, through the same send resource
reply.flow() renders a native WhatsApp Flow message; inbound Flow submissions arrive as flow-reply events

Telegram — `telegram()`

telegram({ connector: 'telegram-acme' })

Option	Default	Description
`connector`	trigger binding	Connector instance slug (bot token lives in the connector base URL)
`resources`	Bot API names in kebab-case	Override any resource slug: `sendMessage` → `send-message`, `sendPhoto` → `send-photo`, `sendVoice` → `send-voice`, `sendDocument` → `send-document`, `sendChatAction` → `send-chat-action`, `getFile` → `get-file`

Long texts are chunked at 4,096 chars, captions clipped at 1,024, and button ids clipped at Telegram’s 64-byte callback_data limit. reply.link() and reply.flow() degrade to plain text (no Telegram equivalent).

Kommo CRM — `kommo()`

Kommo is CRM-as-channel: it has no direct messaging API, so outbound = patch a lead custom field with the reply, then run the salesbot that delivers it.

kommo({ connector: 'kommo-acme', replyFieldId: 987654 })

Option	Default	Description
`connector`	trigger binding	Connector instance slug
`replyFieldId`	trigger binding address	The lead custom-field id the salesbot reads
`patchResource`	`'patch-lead'`	Resource that PATCHes the lead custom field
`salesbotResource`	`'run-salesbot'`	Resource that triggers the salesbot

The userId is the lead id. All rich message types degrade to plain text (buttons become a numbered list) — the salesbot field only carries text.

Chatwoot — `chatwoot()`

Chatwoot is helpdesk-as-channel, conversation-based:

chatwoot({ connector: 'chatwoot-acme', accountId: 7 })

Option	Default	Description
`connector`	trigger binding	Connector instance slug
`accountId`	trigger binding address	Chatwoot account id (path param on every call)
`sendResource`	`'send-message'`	Resource that creates a message in the conversation

The userId is the conversation id — Chatwoot’s native thread and the send target. The provider includes bot-loop prevention: outgoing, agent_bot and agent (user) messages are ignored, so the agent never answers itself.

Generic webhooks — `custom()`

For an HTTP trigger fed by an arbitrary system (CRM, ERP, internal service), custom() replaces hand-rolled parsing. Declare where the fields live — a dot-path into the body or a function:

import { createChannelHandler, custom } from '@runflow-ai/sdk/channels';

export default createChannelHandler({
  provider: custom({
    text: 'data.text',        // dot-path (numeric segments index arrays)
    userId: 'contact.id',     // numbers coerce to string
    messageId: (body) => body.event_id,
  }),
  run: async ({ events }) => {
    // inbound-only by default: return [] and reply through your own transport
    return [];
  },
});

Option	Default	Description
`text`	`'message'`	Where the message text lives
`userId`	`'userId'`	Where the user/conversation id lives (usually the trigger’s coalescing key field)
`messageId`	`'msgId'`	Provider message id, for tracing
`parse`	—	Full override: `(rawBody) => InboundEvent \| null` — wins over the extractors
`send`	—	Optional outbound: without it, replies fail with a clear error (a generic webhook has no implied way to answer)

Events without text are surfaced as { type: 'unknown', raw } instead of being dropped, so your turn can still inspect data-only webhooks.

Connector resources

Providers send through a connector resource that you control. The provider builds the correct API payload; your resource forwards it. Defaults match the catalog connectors, so Meta, Telegram and Chatwoot work out of the box — override the slugs to point at your own connector:

Provider	Catalog connector	Default resources
`meta`	WhatsApp Business Cloud	`send-message`, `get-media-url`
`telegram`	Telegram Bot	`send-message`, `send-photo`, `send-voice`, `send-document`, `send-chat-action`, `get-file`
`chatwoot`	Chatwoot	`send-message`
`kommo`	— (create your own)	`patch-lead`, `run-salesbot`

// Point at your own connector + resource slugs
meta({ connector: 'meta-acme', sendResource: 'enviar-msg', phoneNumberId: '...' });

Connector and address resolve from explicit factory options first, then from the trigger’s channel binding (ctx.binding) when your trigger delivers one. If neither supplies what the wire needs, the provider fails loud and early with a legible error.

Multi-channel routing

provider can be a resolver — route per turn (e.g. by tenant or by binding):

createChannelHandler({
  provider: (ctx) => ctx.binding?.provider === 'meta' ? meta() : telegram(),
  run: runTurn,
});

Because InboundEvent and OutboundMessage are channel-agnostic, the same runTurn serves every channel.

Media (audio, images, files)

The boundary: channels fetches, the SDK understands. provider.fetchMedia() resolves a media event into something fetchable; transcription, vision and OCR stay in the SDK’s media layer.

import { transcribe } from '@runflow-ai/sdk';

export const runTurn: RunTurn = async ({ ctx, events, provider }) => {
  const audio = events.find((e) => e.type === 'audio');
  if (audio) {
    const file = await provider.fetchMedia!(ctx, audio);         // channel-specific
    const { text } = await transcribe({ audioUrl: file.url! });  // channel-agnostic
    return [reply.text(`Você disse: ${text}`)];
  }
  return [reply.text('Envie um áudio!')];
};

Per-channel behavior:

Provider	`fetchMedia` behavior
`meta`	Resolves the media id via the Graph API. The returned URL is Bearer-gated — to get raw bytes, use a custom `mediaResource` that returns `{ base64 }` (the `{ download: true }` option is passed through as a hint)
`telegram`	Returns a directly usable download URL by default; `{ download: true }` fetches the bytes
`kommo` / `chatwoot`	The inbound media id is already a public URL — returned as-is

Credentials stay in the connector, server-side: the agent never holds the channel token.

Typing indicators

On by default where the channel supports it (Meta, Telegram) — best-effort, never blocks the turn:

createChannelHandler({
  provider: meta({ ... }),
  run: runTurn,
  typing: (e) => e.type === 'audio', // false to disable, or a per-event predicate
});

Glass box: hand-rolling the handler

createChannelHandler is sugar over exported pieces — hand-roll main if you want the whole flow in sight:

import { meta, parseEvents, sendAll } from '@runflow-ai/sdk/channels';
import { runTurn } from './agent/runner';

export default async function main(input: any) {
  const provider = meta({ connector: 'whatsapp-acme', phoneNumberId: '...' });

  const events = parseEvents(provider, input);            // parse + per-event isolation
  if (!events.length) return { ok: true, skipped: true };

  const ctx = { ...input.context, userId: input.context?.userId ?? events[0].userId };
  const replies = await runTurn({ ctx, events, provider });
  const results = await sendAll(provider, ctx, replies);  // sequential, per-message results

  return { ok: results.every((r) => r.status === 'sent'), results };
}

The handler returns { ok, sent, results }, where each SendResult is:

`status`	Meaning
`sent`	Delivered to the channel API
`failed`	Attempted and errored (`error` has the message)
`skipped`	Never attempted because a prior message failed (`reason: 'prior_failed'`) — safe to resend on retry

parseEvents reads input.events[] — the platform delivers each coalesced request as { method, path, query, headers, body, receivedAt } and the channel payload is unwrapped from .body automatically. Inputs with a single request.body (no batching) also work.

Bring your own channel

A provider is just a factory returning the ChannelProvider contract — parse + send, with optional typing and fetchMedia. No registry to update, no handler changes:

import type { ChannelProvider, InboundEvent, OutboundMessage, TurnContext } from '@runflow-ai/sdk/channels';

export function myChannel(opts: { connector: string }): ChannelProvider {
  return {
    name: 'custom',
    parse(rawBody): InboundEvent | null {
      const b = rawBody as any;
      if (!b?.from) return null; // not a message → skip silently, never throw
      return { type: 'text', text: b.message ?? '', userId: String(b.from), raw: b };
    },
    async send(ctx: TurnContext, to: string, message: OutboundMessage) {
      // render `message` to your wire format and POST via a connector resource
    },
  };
}

Rules of the contract: parse must be defensive (return null for non-messages, never throw on malformed payloads) and send should throw on hard failures so the handler records a per-message result.

Next Steps

Connectors

The transport channels send through — credentials stay server-side

Media Processing

Transcribe audio and process images from inbound events

Agents

The turn your channel handler runs

Memory

Persist conversation state across turns

Getting Started

CLI

Core Concepts

Real-World Examples

Advanced

Configuration

Extending Runflow

Help & Support

Who does what

Quick start

Inbound events

Replying

Providers

WhatsApp Cloud — `meta()`

Telegram — `telegram()`

Kommo CRM — `kommo()`

Chatwoot — `chatwoot()`

Generic webhooks — `custom()`

Connector resources

Multi-channel routing

Media (audio, images, files)

Typing indicators

Glass box: hand-rolling the handler

Bring your own channel

Next Steps

Connectors

Media Processing

Agents

Memory

​Who does what

​Quick start

​Inbound events

​Replying

​Providers

​WhatsApp Cloud — meta()

​Telegram — telegram()

​Kommo CRM — kommo()

​Chatwoot — chatwoot()

​Generic webhooks — custom()

​Connector resources

​Multi-channel routing

​Media (audio, images, files)

​Typing indicators

​Glass box: hand-rolling the handler

​Bring your own channel

​Next Steps

Connectors

Media Processing

Agents

Memory

Who does what

Quick start

Inbound events

Replying

Providers

WhatsApp Cloud — `meta()`

Telegram — `telegram()`

Kommo CRM — `kommo()`

Chatwoot — `chatwoot()`

Generic webhooks — `custom()`

Connector resources

Multi-channel routing

Media (audio, images, files)

Typing indicators

Glass box: hand-rolling the handler

Bring your own channel

Next Steps