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

# IM Channels

> Connect your agent to messaging platforms — Telegram, WhatsApp, Discord, Slack, Facebook Messenger, Instagram, LINE, Viber.

<Info>
  **Field reference:** [`im_channels`](/reference/im_channels) — every field, type, default, and tier for this page.
</Info>

IM Channels let your agent participate in messaging platforms directly. Users start a conversation on their preferred app, and the agent responds in the same thread.

## Supported platforms

| Platform               | How you connect                                                                                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Telegram Bot**       | Create a bot via [@BotFather](https://t.me/BotFather), paste the bot token, click **Register Webhook**.                                                                                           |
| **WhatsApp**           | Pair via QR code. The dashboard shows a QR you scan with the WhatsApp app on your phone.                                                                                                          |
| **WhatsApp Business**  | Set up through an authorised Meta Tech Provider partner — not a self-serve, in-dashboard connect. The **WhatsApp Business** button opens a short dialog with a **Contact Us** link to arrange it. |
| **Discord**            | Create a Discord application, copy the bot token, optionally pin the agent to a specific guild + channel.                                                                                         |
| **Slack**              | Create a Slack app, paste the bot token + signing secret. Click **Fetch bot user ID** to populate the bot's user ID for @-mention handling.                                                       |
| **Facebook Messenger** | Paste the page access token and app secret; a verify token is generated for you for Meta's webhook handshake.                                                                                     |
| **Instagram DMs**      | Same flow as Messenger — page access token + app secret + auto-generated verify token.                                                                                                            |
| **LINE**               | Paste the channel access token and channel secret from the LINE Developers console.                                                                                                               |
| **Viber**              | Paste the auth token, set the bot name (up to 28 chars), click **Register Webhook**.                                                                                                              |
| **MQTT**               | Subscribe to topics on an MQTT broker. Enter the broker URL, optional credentials, and the topics to watch; the agent reacts to messages and publishes replies to a reply topic.                  |
| **Redis**              | Subscribe to a Redis stream (durable, default) or pub/sub channel. Enter the connection URL, mode, and keys to watch; the agent reacts and writes replies back.                                   |
| **Database**           | Poll a PostgreSQL table for new rows on a schedule. Supply a connection string, an intake `SELECT`, and an optional update statement that runs after the agent processes each row.                |

The last three are **message-bus / data channels** rather than chat platforms — use them to wire your agent into infrastructure (IoT topics, job queues, a tasks table) so it reacts to events and writes results back. They open a long-lived connection that auto-reconnects if it drops.

## Adding a channel

1. Open your agent and go to **IM Channels** in the sidebar.
2. Click the **Add \<Platform>** button for the channel you want.
3. Give the channel a label (letters, numbers, hyphens, underscores — cannot be changed after creation).
4. Fill in the platform-specific credentials and save. For webhook-based platforms (Telegram, Viber, Meta) the verify/webhook URL is generated for you and shown in the card after creation.
5. The status indicator turns green once the connection is verified.

## Enabling and disabling

Each channel has an **ON / OFF** toggle. Disable to stop the agent from receiving messages on that platform without removing the configuration.

## Sender Allowlist

Each channel has a **Sender Allowlist** toggle. When enabled, the agent only responds to messages from senders you list (one entry per line — the supported format depends on the platform, e.g. phone number for WhatsApp, username/user-id for Telegram). Everyone else is silently ignored.

## Screening filters

Beyond the coarse Sender Allowlist, each channel supports an ordered list of **screening filter** rules that decide, per incoming message, whether the agent responds — and let you attach context notes to messages that match. Each rule has:

* **Match conditions** — a message matches only when *every* declared condition is true: sender is/ isn't in a list, text contains a phrase, text matches a regex, mentions the bot, is from another bot, has attachments, matches a topic glob (MQTT/Redis), or has a truthy field at a JSON path (for structured payloads).
* **Action** — `respond` (continue) or `skip` (drop the message before the agent runs).
* **Note** *(optional)* — when the rule matches and the action isn't skip, the note is injected into the agent's prompt for that turn. Notes from multiple matching rules accumulate.

Rules evaluate top-down; the first `skip` match drops the message. This is how you keep a busy channel's costs down (skip the noise) and give the agent context it can't infer (flag VIPs, mark urgency).

## Context and Notes

* **Context** — extra instructions the LLM reads alongside its system prompt when handling messages on this channel. Use this to give per-platform behaviour (e.g. "Replies on this Slack channel are public — be concise.").
* **Notes** — private operator notes that never reach the LLM.

## Spend budget

*(Owner-only.)* Each channel has an optional **Spend budget** — a **Spend cap (credits)** and a **Budget period** (**Daily**, **Weekly**, or **Monthly**). Once the channel's credit spend hits the cap, inbound messages are ignored until the period resets (UTC). Leave the cap at `0` for no limit. Use it to keep a busy or abused channel from draining credits.

## Processing pipeline (advanced)

*(Owner-only.)* Beyond the screening filters, each channel has the same optional pipeline as the platform's other event ingresses. In order:

1. **Event Pre-Processor (code).** Your own JavaScript or Python runs in a sandbox before anything else and returns a verdict — `pass_to_agent`, `drop`, `store`, or `run_tool`. See the [Event pre-processor](/sidebar-menu/event-pre-processor) reference.
2. **Interpreters.** Named rules that recognise what kind of message arrived and inject a hint into the agent's context so it knows what it's handling. See [Interpreters](/sidebar-menu/event-interpreters).
3. **Event Classifier (LLM).** An LLM reads each message and picks **React** or **Drop**, guided by your *What counts as relevant?* prompt. Off → every message that clears the filters reaches the agent.

The **Context** and **Notes** fields above live in the same editor but are available on every plan.

## Per-user context

Each messaging user is tracked as a separate subscriber. The agent maintains separate memory and conversation history per user, scoped by their platform user ID.

## Examples

**Hello world — a Telegram support bot.** Create a bot with @BotFather, paste the token, click **Register Webhook**. Your agent now answers DMs on Telegram with its full configuration.

**Simple — a private team channel.** Add a Slack channel, turn on the **Sender Allowlist**, and list your team's member IDs. The agent only responds to your team and ignores everyone else.

**Medium — a filtered, noted Discord channel.** Add a Discord channel with screening filters: a `skip` rule for messages from other bots, and a `respond`+note rule that flags messages containing "urgent" with the note "Mark as high priority and offer to escalate." The agent stays quiet on bot chatter and treats urgent messages with the right weight.

**Complex — an IoT reaction agent over MQTT.** Add an MQTT channel subscribed to `sensors/+/alert`. Add a screening filter matching `payload_jsonpath` `severity` so the agent only reacts when an alert payload actually carries a severity, with a note instructing it to summarise the alert and recommend an action. The agent's reply is published to the reply topic, where your dashboard or another service consumes it — your agent is now a reasoning step inside an event pipeline.

## Manage via the Management MCP

This area is managed through the [Management MCP](/manage-mcp) at `https://manage.agentheya.com/mcp`.

|          |                                                       |
| -------- | ----------------------------------------------------- |
| Endpoint | `https://manage.agentheya.com/mcp`                    |
| Tools    | `list_im_channels, add_im_channel, remove_im_channel` |

All tools take `owner_id` + `agent_id` as required arguments. See the [Management MCP guide](/manage-mcp) for authentication and the full tool catalogue.