Skip to main content
Field reference: im_channels — every field, type, default, and tier for this page.
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

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 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.
  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 at https://manage.agentheya.com/mcp. All tools take owner_id + agent_id as required arguments. See the Management MCP guide for authentication and the full tool catalogue.