Channels SDK - Runtools.ai

rt.channels manages first-class agent channels such as Telegram and WhatsApp. Use it with rt.secrets to store provider credentials and then connect the channel to an agent.

Connect Telegram

await rt.secrets.set('TELEGRAM_GMAIL_AGENT_BOT_TOKEN', process.env.TELEGRAM_BOT_TOKEN!, {
  orgWide: true,
  category: 'tool',
  description: 'Telegram bot token for gmail-agent',
});

const channel = await rt.channels.connectTelegram({
  agent: 'gmail-agent',
  botTokenSecretName: 'TELEGRAM_GMAIL_AGENT_BOT_TOKEN',
});

await rt.channels.registerWebhook(channel.id);

Each Telegram bot can be connected to one agent at a time.

Connect WhatsApp

await rt.secrets.set('WHATSAPP_GMAIL_AGENT_ACCESS_TOKEN', process.env.WHATSAPP_ACCESS_TOKEN!, {
  orgWide: true,
  category: 'tool',
  description: 'WhatsApp Cloud API token for gmail-agent',
});

await rt.secrets.set('WHATSAPP_GMAIL_AGENT_APP_SECRET', process.env.WHATSAPP_APP_SECRET!, {
  orgWide: true,
  category: 'tool',
  description: 'Meta app secret for gmail-agent WhatsApp',
});

await rt.channels.validateWhatsAppConnection({
  agent: 'gmail-agent',
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: '123456789012345',
});

const whatsapp = await rt.channels.connectWhatsApp({
  agent: 'gmail-agent',
  accessTokenSecretName: 'WHATSAPP_GMAIL_AGENT_ACCESS_TOKEN',
  appSecretSecretName: 'WHATSAPP_GMAIL_AGENT_APP_SECRET',
  phoneNumberId: '123456789012345',
  businessAccountId: '987654321098765',
});

const registered = await rt.channels.registerWebhookWithSetup(whatsapp.id);
console.log(registered.setup?.webhookUrl);
console.log(registered.setup?.verifyToken);

Paste the returned callback URL and verify token into the Meta app’s WhatsApp webhook settings. Each WhatsApp Business phone number can be connected to one agent at a time.

Privacy

Channels default to approved_only. Unknown chats become pending requests and do not reach the agent.

await rt.channels.updatePrivacy(channel.id, {
  mode: 'approved_only',
  allowPrivateChats: true,
  allowGroups: true,
  unauthorizedReply: 'message',
});

Approve a pending Telegram chat:

const state = await rt.channels.getPrivacy(channel.id);
const request = state.requests[0];

await rt.channels.approveAccess(channel.id, {
  requestId: request.id,
});

Approve a known conversation directly:

await rt.channels.approveAccess(channel.id, {
  externalConversationId: 'telegram:chat:123456789',
  conversationType: 'private',
  conversationDisplayName: 'Arthur (@ArtKara1)',
});

Revoke access:

const { grants } = await rt.channels.getPrivacy(channel.id);
await rt.channels.removeAccessGrant(channel.id, grants[0].id);

Product channels

Use product channels when a product built on Runtools needs its own users to chat with an agent over Telegram, WhatsApp, Slack, Discord, iMessage, or another supported channel. The developer connects the channel once. End users do not connect Telegram or create Runtools accounts. Instead, Runtools links the provider sender identity, such as a Telegram user id or phone number, to your product user:

appId + externalUserId + agentChannelId + provider sender id

Once linked, channel-triggered agent runs use the same Hosted Connect end-user scope as your web app. If that product user has not connected Gmail, Stripe, Slack, or another data integration, tool execution returns connect_required. It never falls back to builder Connected Apps or org credentials.

Bind a channel to a product app

Create the agent channel normally, then bind it to the product app:

const channel = await rt.channels.connectTelegram({
  agent: 'atlas-agent',
  botTokenSecretName: 'TELEGRAM_ATLAS_BOT_TOKEN',
});

await rt.channels.registerWebhook(channel.id);

await rt.channels.bindProductChannel('atlas', {
  agentChannelId: channel.id,
  identityPolicy: 'link_required',
  groupPolicy: 'sender_scoped',
  unknownSenderReply:
    'Open Atlas to link this chat: {linkUrl}',
  metadata: {
    linkUrl: 'https://atlas.example.com/settings/channels/link',
  },
});

groupPolicy: 'disabled' blocks group chats for product channels. sender_scoped lets the same group contain multiple product users because each message is resolved by sender id.

Product-started linking

When a signed-in product user clicks “Connect Telegram” or “Connect WhatsApp” inside your product, create a short-lived channel link session from your server:

const session = await rt.channels.createProductLinkSession({
  appId: 'atlas',
  agentChannelId: channel.id,
  externalUserId: currentUser.id,
  email: currentUser.email,
  name: currentUser.name,
  returnUrl: 'https://atlas.example.com/settings/channels',
});

return Response.json({
  linkUrl: session.linkUrl,
  token: session.token,
});

After your product verifies the provider sender id, complete the session from your server:

await rt.channels.completeProductLinkSession({
  appId: 'atlas',
  sessionId: session.id,
  token: session.token!,
  productExternalUserId: currentUser.id,
  providerExternalUserId: telegramUserId,
  username: telegramUsername,
  displayName: telegramDisplayName,
});

For backend imports, admin tooling, or provider webhooks where you already trust the sender identity, link directly:

await rt.channels.linkProductChannelUser({
  appId: 'atlas',
  agentChannelId: channel.id,
  externalUserId: telegramUserId,
  productExternalUserId: currentUser.id,
  username: telegramUsername,
  displayName: telegramDisplayName,
});

Channel-started linking

If an unknown person messages a product-bound channel, Runtools creates a pending link session and replies with the configured link URL. The message is recorded for audit, but the agent is not called until the sender is linked to a product user. List and revoke links:

const links = await rt.channels.listProductLinks('atlas', {
  agentChannelId: channel.id,
  productExternalUserId: currentUser.id,
});

await rt.channels.revokeProductLink('atlas', links[0].id);

Methods

Method	Description
`rt.channels.list({ agent?, provider? })`	List channel connections
`rt.channels.connectTelegram(input)`	Connect a BYOK Telegram bot token secret to an agent
`rt.channels.connectWhatsApp(input)`	Connect a BYOK WhatsApp phone number to an agent
`rt.channels.validateWhatsAppConnection(input)`	Validate a WhatsApp token and phone number before saving secrets
`rt.channels.registerWebhook(channelId)`	Register the provider webhook and return the channel
`rt.channels.registerWebhookWithSetup(channelId)`	Register the provider webhook and return one-time setup values such as WhatsApp verify tokens
`rt.channels.disconnect(channelId)`	Disconnect a channel and clean up provider webhook state
`rt.channels.getPrivacy(channelId)`	Read policy, pending requests, and approved grants
`rt.channels.updatePrivacy(channelId, patch)`	Update channel privacy policy
`rt.channels.listAccessRequests(channelId, status?)`	List access requests
`rt.channels.approveAccess(channelId, input)`	Approve a pending request or known conversation
`rt.channels.denyAccessRequest(channelId, requestId)`	Deny a pending request
`rt.channels.removeAccessGrant(channelId, grantId)`	Revoke an approved conversation
`rt.channels.listProductBindings(appId)`	List product bindings for channels
`rt.channels.bindProductChannel(appId, input)`	Bind a developer-owned channel to a product app
`rt.channels.unbindProductChannel(appId, bindingId)`	Disable a product channel binding
`rt.channels.createProductLinkSession(input)`	Create a short-lived channel identity link session
`rt.channels.completeProductLinkSession(input)`	Complete a pending link session after product auth
`rt.channels.listProductLinks(appId, filters?)`	List linked channel identities for a product
`rt.channels.linkProductChannelUser(input)`	Directly link a channel sender to a product user
`rt.channels.revokeProductLink(appId, linkId)`	Revoke a product channel identity link

​Connect Telegram

​Connect WhatsApp

​Privacy

​Product channels

​Bind a channel to a product app

​Product-started linking

​Channel-started linking

​Methods