group
group.add
Add Group
Effects: write, requires channel telegram
Add a specific group to your discovery list by @username or invite link (t.me/...).
Groups and channels only — this does NOT add an individual person/contact. To add a person by @username (e.g. a customer or lead), use contacts.discover then contacts.sync instead.
When to use:
- You already know the group's @username or invite link
- Adding a known group without searching
Returns: group metadata including id, title, member_count.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Which of the workspace's accounts on this channel acts (from channels.list). OMIT to use the workspace's default account. |
channel | string | yes | Channel the group is on (e.g. 'telegram') |
link | string | yes | The group's @username or invite link (e.g. '@phuket' or 't.me/...') |
group.add_member
Add Member to Group
Effects: write
Add a member to an existing group on Telegram or WhatsApp.
What this does:
- Adds the specified member to the group
- Resolves the member by username, phone number, or JID
- Reports if the member is already in the group
Returns: success, chat_id, member, already_member.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Which of the workspace's accounts on this channel acts (from channels.list). OMIT to use the account the group's conversation is filed on. |
channel | string | yes | Channel where the group exists (e.g., 'telegram', 'whatsapp') |
chat_id | string | yes | ID of the group/channel to add the member to. Group id exactly as group.list reports it: a signed numeric id on Telegram, or a JID ending in @g.us on WhatsApp. A WhatsApp group has no numeric id, so this is a string either way. Read it from group.list; never compose one. |
member | string | yes | The member to add (format depends on channel: @username on Telegram, phone on WhatsApp) |
group.admins
List Group Admins
Effects: read, requires channel telegram
List administrators of a group on Telegram (or other channels).
Returns admin metadata including:
- Admin rank (creator or admin)
- Username and real name
- Can they post (for restricted groups)
- Bot status
Use this to understand group leadership before outreach or evaluation.
Returns: group_id, title, admins list, total admin count.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Which of the workspace's accounts on this channel acts (from channels.list). OMIT to use the account the group belongs to. |
group_id | integer | yes | Group to act on. Accepts either the discovered-group id from group.search / group.list, or the platform's own group id (e.g. a Telegram chat id like -1001234567890). |
group.create
Create Group
Effects: write
Create a new group on a channel: a Telegram group, a WhatsApp group, or a Discord SERVER (a community with text channels inside; Discord calls it a guild) owned by the connected account. Returns the new group's chat ID and invite link.
What this does:
-
Creates a new group with the specified title
-
Returns chat_id, invite_link, and channel_ref for further operations
-
Optionally registers the group in your inbox for monitoring
-
Discord: also makes the text
channelsasked for (beside #general) and one permanent invite link; chat_id is the server id, channel_ref the #general thread,channelslists every text channel with its thread_ref (messages.send posts into one). People cannot be added to a server: send them invite_link. A step Discord refused after the server was made (a channel, the invite) is inproblems; the server exists. Nothing is hosted by DialogBrain: the server lives at Discord. -
Telegram: group_type='channel' makes a BROADCAST CHANNEL; add username='<name>' to make it public (public_link in the answer). A Telegram broadcast channel: group.create(channel='telegram', group_type='channel', title=..., username=...); then write into it with messages.send(thread_id=<returned thread_id>). Steps refused after the chat was made (username, invite link) are in
problems; the chat exists.
Returns: success, chat_id, channel_ref, title, thread_id, invite_link, public_link, problems.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
about | string | no | Optional description or about text for the group |
account_id | integer | no | Which of the workspace's accounts on this channel creates the group (from channels.list). OMIT with one account; with several the workspace's own account is preferred over a shared one. |
channel | string | yes | Channel to create the group on: 'telegram', 'whatsapp' or 'discord' (a server) |
channels | array | no | Discord only: text channels to create inside the new server, beside its default #general, e.g. ["rules", "announcements", "submissions"], or objects {"name", "topic"}; at most 10 (more are added in Discord itself). Refused on channels whose groups have no rooms inside (Telegram, WhatsApp). |
group_type | string | no | Type of group to create. Options: 'supergroup' (default), 'basic', 'channel'. 'channel' = Telegram broadcast channel: subscribers read, only admins post (messages.send to its thread posts into it). 'channel' is refused on WhatsApp and Discord; 'supergroup'/'basic' are Telegram-only and ignored on WhatsApp. (default supergroup) |
participants | array | no | People to put in the group at creation: phone numbers or JIDs on WhatsApp, @usernames or phone numbers on Telegram. Without this the group is created empty and the creator is its only member, which on WhatsApp means nobody can be shown it — there is no invite link to send. Reported back per person in participants_added and participants_failed. |
register_in_inbox | boolean | no | Auto-register the created group in your inbox for monitoring. Default: true. (default True) |
title | string | yes | Title/name of the group to create |
username | string | no | Telegram only, for a supergroup or a channel: make it PUBLIC at https://t.me/<username> (5-32 characters, letters, digits and underscore, starting with a letter; '@' is accepted). If Telegram refuses it (taken, invalid, too many public chats) the chat still exists: success stays true, the reason is in problems and invite_link is a private link. On success public_link is set. |
group.get_invite_link
Get Group Invite Link
Effects: write
Get an invite link for an existing group (Telegram, WhatsApp) or Discord server.
What this does:
- Telegram: mints a FRESH link (e.g. t.me/+...) on every call; previously issued links stay valid
- WhatsApp: returns the group's EXISTING link, the same one each time. Do not describe it to anyone as newly issued
- Discord: mints a permanent discord.gg/... link into a server the account is in (chat_id: the server id, a channel id, or a channel's thread ref); the account needs Create Invite there
- Requires the connected account to be the group's owner or an admin with invite rights
When to use:
- A member can't be added directly because their privacy settings block invites (group.add_member fails with a privacy error) — send them this link instead
- Onboarding people to a private group
Returns: success, chat_id, invite_link.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Which of the workspace's accounts on this channel mints the link (from channels.list). OMIT with one account. |
channel | string | yes | Channel where the group exists (e.g., 'telegram', 'whatsapp', 'discord') |
chat_id | string | yes | ID of the group/channel to export an invite link for. Group id exactly as group.list reports it: a signed numeric id on Telegram, or a JID ending in @g.us on WhatsApp. A WhatsApp group has no numeric id, so this is a string either way. Read it from group.list; never compose one. Discord: the server id, a channel id, or the channel's thread ref (discord:<account>:<channel>) from channels.list. |
group.join
Join Group
Effects: write, requires channel telegram
Join a group and start syncing its messages to your inbox. The group must be in your discovery list (use group.search or group.add first).
What this does:
- Joins the group on Telegram (or other channel)
- Creates a thread in your inbox for syncing messages
- Optionally enables AI auto-reply drafts
Returns: success, thread_id, auto_reply_enabled.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Which of the workspace's accounts on this channel acts (from channels.list). OMIT to use the account the group belongs to. |
enable_auto_reply | boolean | no | Enable AI auto-reply drafts for messages in this group. Drafts can be reviewed and sent manually. Default: false (large public groups would otherwise generate drafts for every incoming message). |
group_id | integer | yes | Group to act on. Accepts either the discovered-group id from group.search / group.list, or the platform's own group id (e.g. a Telegram chat id like -1001234567890). |
group.leave
Leave Group
Effects: write, requires channel telegram
Leave a group and stop syncing its messages to your inbox. The group will be moved back to discovered state (can rejoin later).
What this does:
- Leaves the group on Telegram (or other channel)
- Stops syncing new messages
- Disables any AI auto-reply drafts for this group
- Keeps the group in discovery list (not deleted)
Returns: success, thread_id.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Which of the workspace's accounts on this channel acts (from channels.list). OMIT to use the account the group belongs to. |
group_id | integer | yes | Group to leave. Accepts either the discovered-group id from group.list (lifecycle='monitored'), or the platform's own group id (e.g. a Telegram chat id like -1001234567890). |
group.list
List Groups
Effects: read, requires channel telegram
List groups in this workspace's DISCOVERY/SCORING list (the discovered_group table).
⚠️ This is NOT your messageable inbox. It is a subset used for discovery + quality scoring. Absence here does NOT mean a chat isn't joined or can't be messaged.
Each row includes thread_channel_ref — the ref a synced thread carries — so you can match rows against search_threads results. To get a thread_id you can send to, use search_threads.
Lifecycle values:
- discovered: found but not yet evaluated
- bookmarked: saved for later
- monitored: joined and actively syncing messages
- dismissed: hidden
By default, dismissed groups are excluded.
Returns: id, title, member_count, lifecycle, scan_status, overall_score, is_member, can_post, my_rank.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Only groups of this account (from channels.list). OMIT to list groups of every account. |
channel | string | no | Filter by channel (e.g. 'telegram'). Optional. |
lifecycle | string | no | Filter by state: discovered, bookmarked, monitored (=joined/syncing), dismissed. OMIT to include all states (dismissed excluded by default elsewhere). (one of discovered, bookmarked, monitored, dismissed) |
limit | integer | no | Maximum number of results (1-100, default 20) (default 20; min 1.0; max 100.0) |
min_score | number | no | Minimum overall score (0.0-1.0). Optional. (min 0.0; max 1.0) |
offset | integer | no | Pagination offset. OMIT to start at row 0 (default). (min 0.0) |
group.moderate
Moderate Group
Effects: write
Run ONE moderation action on a group: a Telegram bot group, a Telegram group or channel the connected Telegram ACCOUNT created, a Discord SERVER the connected account administers, or a WhatsApp group the connected number is a member of.
Telegram account actions (channel='telegram'; the person's own account, not a bot; chat_id = the chat id (-100...), its telegram: ref or our thread id; params.account_id names the account when the workspace has several and the chat has no conversation in the inbox; only an account connected in THIS workspace, never one shared in; the caller must be a workspace owner or admin):
- delete: the OWNER (creator) deletes the group, supergroup or broadcast channel for everyone. Irreversible: params.confirm_name must be the chat's exact current title as Telegram has it (ask the person; a mismatch is refused and names the title Telegram has). The inbox conversation is archived, its messages kept. error_type outcome_unknown means it may have been deleted: check before retrying
- history_visible: params: visible (true/false). Whether NEW members see the messages sent before they joined. Supergroups only (a basic group has no such switch; a broadcast channel always shows its history); the account must be an admin allowed to change the info
- set_title: params: title. set_description: params: description ("" clears it). Both need those admin rights too; safe to repeat
Discord actions (channel='discord'; chat_id = the server id, a channel id, a channel's thread ref or our thread id; params.account_id names the account when the workspace has several and chat_id does not; only an account connected in THIS workspace, never one shared in):
- community: switch Community mode on (rules screening and announcement channels become possible). params: rules_channel (default #rules), updates_channel (where Discord posts its notices to the team; default a hidden #moderator-only, made when missing), announcement_channel (the one turned into an announcement channel, default #announcements; false for none); channels by id, ref or #name. Discord's conditions change server defaults (verification level at least low, media filter for everyone, notifications to mentions only): the answer lists them in settings_changed; tell the person
- icon: params: file_id of a PNG/JPEG/GIF/WebP in this workspace
- set_title: params: title. set_description: params: description (community servers only)
- role: params: name, permissions (names such as view_channel, send_messages, manage_messages, kick_members, moderate_members, administrator, or Discord's bitfield as a number), color (#rrggbb), hoist, mentionable. Not idempotent: a retry makes a second role
- slowmode: params: channel (id, ref or #name) and seconds (0 to 21600; 0 turns it off), both required
- delete: the OWNER deletes the server. Irreversible: params.confirm_name must be the server's exact name (ask the person); with two-factor on, Discord wants params.mfa_code, the current authenticator code the person reads out (redacted from every log and trace)
Every Discord action needs the caller to be a workspace owner or admin.
Discord refusals are worded: no_permission (not an admin), mfa_required, not_community, bad_request (a value Discord rejected).
WhatsApp actions (channel='whatsapp'; chat_id = the group JID (...@g.us), its whatsapp: ref or our thread id; only the workspace's own numbers, not one shared in; the number that is in the group is used):
- set_title: params: title (at most 100 characters). Any member may rename unless the group's admins locked its info; WhatsApp's refusal is passed through. Needs edit rights in the workspace. When two of the workspace's numbers are in the group, params.account_id is required. The inbox thread takes the new name.
Telegram BOT actions (channel='telegram_bot'):
- invite_link: mint a fresh invite link; older links stay valid. Optional params: name, member_limit, expire_date, creates_join_request
- revoke_invite_link: params: invite_link
- admins: list administrators (user_id, username, name, status)
- member_count: how many members the group has
- member_status: one member's status. params: user_id
- promote / demote: params: user_id, optional rights {can_*: bool}
- ban / unban: params: user_id, optional revoke_messages
- mute / unmute: params: user_id, optional until_date (unix ts)
- pin / unpin: params: message_id (omit on unpin for the latest), optional silent
- set_title: params: title
- set_description: params: description
⚠️ A Telegram BOT cannot add a member or create a group — the Bot API has no method for either. To bring someone in, mint an invite_link and send it to them.
Telegram rules that surprise callers (all verified against a live group):
- A bot may only promote/demote admins IT promoted. Check
can_be_editedin member_status first: false means demote will answer 'not enough rights', and that is Telegram, not a failure on our side. - promote additionally needs the bot to hold can_promote_members in the group; plain admin rights are not enough.
- After unmute the status stays 'restricted' while every can_send_* is true. That is Telegram labelling anyone who carries an explicit permission set — it does NOT mean still muted. Read the permissions, not the status.
- unban lifts the ban but does not bring the person back: the status becomes 'left' and they must rejoin.
Returns: success plus the action's own keys (invite_link, admins, member_count, status) and result, Telegram's own payload.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
action | string | yes | Which action to run (see the tool description for the list) |
channel | string | yes | Channel the group lives on, e.g. 'telegram_bot', 'telegram' (an account), 'discord' or 'whatsapp' |
chat_id | string | yes | Group to act on: the platform chat id (e.g. -1004487018858), a channel_ref, or our numeric DB thread id |
params | object | no | Action-specific arguments, e.g. {'user_id': 123} for promote/ban, {'message_id': '456'} for pin, {'title': '...'} for set_title |
group.preview_messages
Preview Group Messages
Effects: read, requires channel telegram
Read recent public messages from a group without joining it. Only works for groups where can_preview_history=true.
Use this to manually evaluate message quality before deciding to join. For an automated quality score, use group.scan instead.
Returns: list of recent messages with sender identity (username, name, admin flag), text (150-char previews; pass full_text=true for untruncated), date, is_reply.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Which of the workspace's accounts on this channel acts (from channels.list). OMIT to use the account the group belongs to. |
full_text | boolean | no | Return untruncated message text. OMIT for 150-char previews (keeps large batches consumable). |
group_id | integer | yes | Group to act on. Accepts either the discovered-group id from group.search / group.list, or the platform's own group id (e.g. a Telegram chat id like -1001234567890). |
limit | integer | no | Number of recent messages to fetch (1-100, default 20) (default 20; min 1.0; max 100.0) |
group.promote_admin
Promote Member to Admin
Effects: write
Promote a member to admin in an existing group on Telegram or WhatsApp.
What this does:
- Gives the specified member admin status in the group
- On Telegram, this grants visibility of all group messages (even if not a bot)
- Defaults to minimal/empty rights; specify custom rights if needed
Returns: success, chat_id, member.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Which of the workspace's accounts on this channel acts (from channels.list). OMIT to use the account the group's conversation is filed on. |
channel | string | yes | Channel where the group exists (e.g., 'telegram', 'whatsapp') |
chat_id | string | yes | ID of the group/channel where the member will be promoted. Group id exactly as group.list reports it: a signed numeric id on Telegram, or a JID ending in @g.us on WhatsApp. A WhatsApp group has no numeric id, so this is a string either way. Read it from group.list; never compose one. |
member | string | yes | The member to promote (format depends on channel: @username on Telegram, phone on WhatsApp) |
rights | object | no | Optional admin rights dict (Telegram-specific). If not provided, defaults to minimal/admin status only. Example: {"post_messages": true, "edit_messages": true} |
group.scan
Scan Group
Effects: read, write, requires channel telegram
Scan a group to evaluate its quality before joining. Fetches recent messages, analyzes activity, spam, and engagement, then returns a quality score and plain-English verdict.
When to use:
- After finding groups with group.search
- Before deciding which groups to join
Returns: overall_score (0-1), is_disqualified, disqualify_reasons, individual scores, and a verdict string.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Which of the workspace's accounts on this channel acts (from channels.list). OMIT to use the account the group belongs to. |
group_id | integer | yes | Group to act on. Accepts either the discovered-group id from group.search / group.list, or the platform's own group id (e.g. a Telegram chat id like -1001234567890). |
group.search
Search Groups
Effects: read, write, requires channel telegram
Search for public groups or channels by topic on Telegram (or other channels). Returns matching groups with title, member count, and whether messages can be previewed.
Finds public groups/channels by topic — NOT individual people. To find or add a specific person by @username, use contacts.discover / contacts.find instead.
When to use:
- Finding groups related to a topic or niche
- Building a list of groups for outreach or monitoring
After searching, use group.scan to evaluate quality before joining.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
account_id | integer | no | Which of the workspace's accounts on this channel acts (from channels.list). OMIT to use the workspace's default account. |
channel | string | yes | Channel to search on (e.g. 'telegram') |
keywords | string | yes | Search keywords or phrase (e.g. 'crypto trading signals'). A list of keywords is also accepted and joined with spaces. |
limit | integer | no | Maximum number of results to return (1-50, default 20) (default 20; min 1.0; max 50.0) |