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.

​
TikTok

TikTok works differently from the other channels, so it is worth reading before you set it up. What your agent can do
  • Post videos to the connected account, with caption, visibility, and comment / Duet / Stitch controls.
  • Post photo carousels (1–35 images).
  • Send a post to the creator’s TikTok inbox as a draft instead of publishing, so a human reviews it first.
  • List the account’s own posts with view, like, comment and share counts.
  • Report whether a post finished publishing.
What it cannot do yet Answering comments and direct messages is not available. TikTok’s public developer API has no endpoints for reading or replying to comments, and its webhooks never deliver comments or messages. That capability requires approved access to TikTok’s Business Messaging API — a partner-gated programme that needs a TikTok Business account and is currently unavailable in the EU and UK. The Auto-answer comments and DMs toggle stays visible but inactive until that access is in place. Everything above is unaffected. Before you connect
  • Media is posted from a URL, and TikTok only accepts URLs on a domain you have verified in your TikTok developer app. Unverified domains are rejected.
  • Photos must be JPEG or WEBP — TikTok rejects PNG.
  • Until your TikTok app passes TikTok’s content-posting audit, every post is forced to private regardless of the visibility you choose. This is a TikTok restriction, not an agent setting.
  • Visibility options depend on the creator’s own account: a private TikTok account cannot post publicly. Your agent checks this before posting and reports the allowed options if the requested one isn’t permitted.
Connecting
  1. Add a TikTok channel and give it a label.
  2. Click Connect TikTok account and approve the permissions as the account owner.
  3. Set the default post visibility and interaction toggles, then save.
You can attach more than one TikTok account to the same agent — add one channel per account. When several are connected, tell the agent which one to use by its label or @handle.

​
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.