channels
channels.connect
Connect Channel
Effects: write, external_api
🔌 Connect a messaging channel to this workspace, or find out how.
Call with no channel for the catalogue: every channel, its connect_mode and its link.
Call with channel only to learn what to ask the person for (credential_fields).
Call with channel + credentials to connect a credentials channel: email over IMAP with an app password, telegram_bot with a bot token, line with the channel access token and channel secret, avito.
Channels that need a QR scan, a phone code or a browser sign-in (telegram, whatsapp, instagram, facebook, email (Google sign-in), youtube, tiktok, x, threads, linkedin, zalo, maxru, the voice carriers) cannot be connected from here: the tool answers success with needs_person=true and the link https://dialogbrain.com/connect/<channel>, which opens the connection dialog for that channel. Give the person that link; do not tell them to look for it in settings. A website widget is not connected here at all: use widgets.create.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
channel | string | no | Channel id, e.g. 'email', 'telegram_bot', 'whatsapp'. Omit for the catalogue. |
credentials | object | no | The fields credential_fields asked for. Never echoed back. |
display_name | string | no | Name for the account in the channel list. |
channels.connect_telegram_bot
Connect Telegram Bot
Effects: write, external_api
🤖 Connect a Telegram Bot (Bot API) channel from its bot token.
When to use:
- After a bot was created via @BotFather and you have its token.
- The token alone is sufficient — no Telegram user account is needed.
Validates the token, creates the channel account, and registers the webhook so the bot starts receiving messages immediately.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
bot_token | string | yes | Telegram bot token from @BotFather (e.g. '123456789:ABCdef...'). |
channels.contacts
Load Channel Contacts
Effects: write
👥 Load people into a custom channel account, so its conversations are titled with names and each person has a card in the workspace's contacts.
contacts is a list of {contact_id, display_name, conversation_id?, avatar_url?, details?}. contact_id is the platform's id for the person. details may carry email, phone, about, company, job_title, linkedin, website. Give conversation_id for people the account already has a conversation with.
import_history: 'answered' reads into the inbox only the conversations in which the other side wrote; 'all' reads every conversation; omit it to load names only. The import runs in the background; a second request while one runs is queued, not lost. Check progress with channels.list(account_id=...): history_import.skipped counts the conversations left out and not_imported names the first 100 with the reason. Up to 5000 contacts per call; loading again is safe.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | yes | The custom channel account (from channels.list). |
contacts | array | yes | People to load: {contact_id, display_name, conversation_id?, avatar_url?, details?}. |
import_history | string | no | Also read their existing conversations: 'answered' or 'all'. OMIT to load names only. (one of answered, all) |
channels.get_profile
Get Channel Profile
Effects: read
🪪 Read a connected channel's current bot profile: display name, long description, short description, the / command menu and the persistent menu button.
Pass language_code to read back a localized variant instead of the default one.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
channel_account_id | integer | yes | The channel account to read, from channels list. |
language_code | string | no | IETF language code (e.g. 'en') to read a localized variant of the text fields instead of the default. OMIT for the default variant. |
channels.list
List Channels
Effects: read
📋 The messaging channels connected to this workspace and whether they are working.
One row per channel account: channel, display_name, status, error, and reconnect_url when the account needs repair. A channel in status 'error' is NOT receiving messages — say so plainly and give the person reconnect_url; it opens the repair directly, so do not tell them to look for it in settings and do not build a link of your own.
Pass only_broken=true to check for outages without listing the healthy channels.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | One account in detail, with its large_group_threshold (groups this large are left out of sync; change it with channels.sync_settings). For a custom channel this adds whether it is listening or polling, why inbound is down, how many contacts it has, the progress of a history import, a health check and the agents that would answer on it. For Discord: whether the gateway stream is up (connected_at, last event), how many servers, server channels and DMs the account sees, how many chats are synced and the sync scope. OMIT to list the workspace's channels. |
chats | string | no | With account_id: that account's chats, synced or NOT (search.threads sees only synced ones). A text finds the chats whose title contains it, e.g. 'showcase' finds 'Server › #showcase' of a big Discord server left out for its size; '*' lists them all. At most 50 per answer, synced first, then by kind and title; chats_page says total, has_more and next_offset. Each comes with thread_id, synced, why it is out of sync, member_count, and for a Discord server channel its topic, can_view and can_send (false = this account may not read / post there, null = unknown). Turn one on with threads.update(thread_id=..., synced=true). OMIT otherwise. |
chats_offset | integer | no | With chats: skip this many chats, to read the next page (pass chats_page.next_offset). OMIT for the first page. |
only_broken | boolean | no | true = only the accounts that need attention (status 'error'). OMIT to list every channel of the workspace. |
channels.reconnect
Reconnect Channel
Effects: write
🔌 Bring a disconnected account back on its own, when the channel allows it.
Use it when channels.list shows an account as not connected / needs_reauth, or a send answers that the account is offline. A LinkedIn or Discord account connected through a browser login takes the session that login holds now (nothing is opened or typed on the site; the session must belong to the same member). When it cannot (no session in the browser, the same dead session, another channel), the answer says what a person has to do. Needs the member, admin or owner role.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | yes | The connected account (from channels.list). |
page_id | string | no | Discord only: a browser.open page of this workspace that is signed in to Discord as this account. The token is read from that open page (a sign-in made with browser.open is not saved to the account's browser identity). It must be the same Discord user. |
channels.subscribe
Pay for a channel
Effects: write
💳 Choose how this workspace pays for a paid channel, so it can be connected.
When to use: a connect tool answered billing_required (e.g. channels.connect_telegram_bot, channels.connect).
- OMIT
methodto see the monthly price and which payment methods work right now (nothing is charged). method: "credits"pays from the workspace credit balance: the first month is charged when the channel is connected, then monthly from the balance. Then call the connect tool again.method: "stripe_card"(or another card/crypto method) returnsredirect_url, a checkout page the person must open and pay; connect after they have paid.
Spends the workspace's money: use it when the person asked to connect the channel.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
channel_type | string | yes | Channel to pay for, as the connect tool names it, e.g. 'telegram_bot', 'whatsapp'. |
method | string | no | How to pay: 'credits' (workspace balance) or a method type from the preview. OMIT to only see the price and the methods. |
channels.sync_settings
Channel Sync Settings
Effects: write
⚙️ Change how large a group can be and still sync on one connected account.
Groups and channels with large_group_threshold members or more are left out of sync (default 50; 0 = never leave a group out for its size). The current value is in channels.list(account_id=...). Raising it brings back the chats left out for their size that are now under it, with their recent history (not on an account set to sync only new messages; on one set to 'selected chats' they come back waiting to be picked). Lowering it applies to chats found from now on and never switches a chat off. One chat can also be switched on alone with threads.update(synced=true). Changing it needs the channel's owner or a workspace owner/admin.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | yes | The connected account (from channels.list). |
large_group_threshold | integer | yes | Groups with this many members or more are left out of sync; 0 = never. |
channels.update_profile
Update Channel Profile
Effects: write, external_api
🪪 Update a connected channel's bot profile: display name, long description (the "What can this bot do?" card), short description, the / command menu, and the persistent menu button next to the input field.
Every field is optional — pass only what you want to change; any field you omit is left exactly as it is.
menu_button with type="web_app" is what puts a persistent button next to the input field that opens a Mini App page bound to this bot (pass the page's https URL as menu_button.url).
Two things this tool CANNOT set, because the Bot API does not expose them — both stay BotFather-only: the bot's AVATAR, and registering a NAMED Mini App (t.me/bot/appname). menu_button.web_app and any web_app message button work off a direct URL and need no such registration.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
channel_account_id | integer | yes | The channel account to update, from channels list. |
commands | array | no | The / command menu: a list of {command, description} objects (command: lowercase letters/digits/underscores, <= 32 chars; description: <= 256 chars; <= 100 commands total). OMIT to leave unchanged. |
description | string | no | Long description shown on the "What can this bot do?" card before Start (<= 512 characters). OMIT to leave unchanged. |
language_code | string | no | IETF language code (e.g. 'en') to set a localized variant of the text fields instead of the default. OMIT for the default variant every user without a matching locale sees. |
menu_button | object | no | The persistent button next to the input field: {type: "commands"|"default"|"web_app", text?, url?}. "commands" shows the / menu, "default" removes the custom button, and "web_app" opens a Mini App at url (must be https://) with the button labelled text. OMIT to leave unchanged. |
name | string | no | Bot display name (<= 64 characters). OMIT to leave unchanged. |
short_description | string | no | Short description shown on the profile page (<= 120 characters). OMIT to leave unchanged. |