Skip to main content
Channels let an agent receive and reply through external messaging apps. Telegram and WhatsApp are first-class BYOK channels, and the same contract is used for future Slack, Discord, SMS, and Teams support. Every first-class channel has two parts:
  • A channel connection on the agent, configured in Agent → Channels
  • A matching official Tool Hub tool for provider-specific sends and actions
Adding a first-class channel also makes the matching official provider tool available to the agent. The native channel worker handles the normal reply back to the source chat, while the tool is for explicit sends and provider-specific actions such as messaging another approved Telegram chat or sending an approved WhatsApp template.

​
Product channels

If you are building a product on Runtools, the developer connects the messaging channel once and product users simply chat. That channel credential is only the transport. Customer data tools still use Hosted Connect. Runtools links each provider sender, such as a Telegram user id, Slack user id, or phone number, to one product user:
When that sender messages the product-bound channel, the agent run receives the product user’s Hosted Connect scope. If that user has not connected Gmail, Stripe, Slack, or another integration, tool execution fails closed with connect_required. It does not use the builder’s Connected Apps or another user’s credentials. Unknown senders get a link-required reply and the agent is not called. Group conversations are disabled by default; products can opt into sender-scoped groups when each message has a trustworthy sender id.

​
Privacy model

Channels are protected before the agent sees anything. The default policy is approved_only:
  • Unknown chats become pending requests
  • Pending messages are stored as channel audit events only
  • Pending messages do not enter thread history
  • Pending messages do not call the agent or expose tools
Owners can switch a channel to public or disabled, and can independently allow private chats, groups, and unauthorized approval notices. For Telegram groups, approved groups can contribute passive history, but the agent only replies when the bot is mentioned, replied to, or receives a command/callback.

​
Telegram setup

  1. Create a bot in BotFather.
  2. Save the bot token as a secret.
  3. Open the agent’s Channels tab.
  4. Add Telegram and connect the saved token.
  5. Send /start to the bot.
  6. Approve the private chat or group in the channel privacy panel.
Telegram group chats require BotFather privacy mode to be disabled if you want normal group messages to appear in history. With privacy mode on, Telegram only forwards slash commands, button clicks, and replies to bot messages.

​
WhatsApp setup

  1. Create or choose a Meta app with WhatsApp Cloud API enabled.
  2. Create a system-user access token with access to the WhatsApp Business Account.
  3. Copy the Meta app secret and WhatsApp phone number ID.
  4. Open the agent’s Channels tab.
  5. Add WhatsApp and paste the access token, app secret, phone number ID, and optional WABA ID.
  6. Copy the callback URL and verify token returned by Runtools into the Meta app webhook settings.
  7. Subscribe the app to WhatsApp message events if automatic WABA subscription was not available.
  8. Approve the phone conversation in the channel privacy panel when the first user messages the number.
Each WhatsApp Business phone number can be connected to one agent at a time. WhatsApp free-form messages are limited by Meta’s customer service window. Outside that window, agents should use approved WhatsApp templates through the whatsapp tool.

​
iMessage setup (Sendblue)

iMessage is a bring-your-own Sendblue account: people text your Sendblue number and the agent replies over iMessage (or SMS fallback).
  1. Sign up at Sendblue and get a sending number plus your API Key ID and API Secret Key from the dashboard.
  2. Open the agent’s Channels tab.
  3. Add iMessage and paste the API Key ID, API Secret Key, and your Sendblue number (E.164, e.g. +14155551234).
  4. Copy the receive webhook URL Runtools returns and set it as the inbound/receive webhook in your Sendblue dashboard.
  5. Text the number — approve the conversation in the channel privacy panel when the first person messages it.
Inbound webhooks are authenticated by an unguessable token carried in the callback URL, so pasting the URL as-is is enough. If you prefer Sendblue’s native secret, set the displayed webhook secret as the webhook’s Secret in Sendblue — Runtools also accepts it in the sb-signing-secret header. The agent replies to direct messages automatically. Group iMessage threads are supported when the number is added to a group; every group message reaches the agent (subject to the privacy panel).

​
Official tools

Official channel tools use the same approval system as inbound messages. In approved_only mode, they can send only to approved conversations or to the current approved source conversation. Username-only or raw provider-id sends require public mode or a previously known approved conversation. This keeps agents with powerful tools, such as Gmail, from being reachable by arbitrary external users.