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 |
|---|---|---|---|
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 |
|---|---|---|---|
channel | string | yes | Channel where the group exists (e.g., 'telegram', 'whatsapp') |
chat_id | integer | yes | ID of the group/channel to add the member to |
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 |
|---|---|---|---|
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 (Telegram or WhatsApp). 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
Returns: success, chat_id, channel_ref, title, thread_id.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
about | string | no | Optional description or about text for the group |
channel | string | yes | Channel to create the group on (e.g., 'telegram', 'whatsapp') |
group_type | string | no | Type of group to create. Options: 'supergroup' (default), 'basic'. Telegram-only; ignored on WhatsApp. (default supergroup) |
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 |
group.get_invite_link
Get Group Invite Link
Effects: write
Export an invite link for an existing group (Telegram).
What this does:
- Mints a fresh invite link (e.g. t.me/+...) for the group; previously issued links stay valid
- 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 |
|---|---|---|---|
channel | string | yes | Channel where the group exists (e.g., 'telegram') |
chat_id | integer | yes | ID of the group/channel to export an invite link for |
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 |
|---|---|---|---|
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 |
|---|---|---|---|
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 |
|---|---|---|---|
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 the connected account administers (Telegram bot groups today).
Actions:
- 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' |
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 |
|---|---|---|---|
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 |
|---|---|---|---|
channel | string | yes | Channel where the group exists (e.g., 'telegram', 'whatsapp') |
chat_id | integer | yes | ID of the group/channel where the member will be promoted |
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 |
|---|---|---|---|
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 |
|---|---|---|---|
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) |