Combot API

The Combot API allows you to programmatically access analytics, member data, and moderation features for your Telegram groups. It follows conventions similar to the Telegram Bot API.

All API requests are made to:

https://api.combot.org/v5/<methodName>?api_key=<key>&chat_id=<id>

Responses are JSON objects. Every response contains an ok boolean field. On success, the result is in the result field. On failure, ok is false and a description field explains what went wrong.

Authentication

All API methods require an api_key parameter. You can generate your API key in Settings on the Combot website. The key is tied to your Telegram account and grants access to all groups where you are an administrator.

Making Requests

All methods accept both GET and POST requests. Parameters can be passed as query strings or form-encoded body. All responses are application/json.

Example:

curl "https://api.combot.org/v5/getChatAnalytics?api_key=YOUR_KEY&chat_id=-1001234567890"

Common Parameters

Pagination

Endpoints that return lists support pagination with page and limit parameters. Pages are 0-indexed.

Paginated responses include metadata:

{
  "ok": true,
  "total": 1250,
  "total_pages": 50,
  "has_next": true,
  "has_prev": false,
  "data": [...]
}

Error Handling

The response contains a JSON object which always has a Boolean field ok. If ok equals true, the request was successful and the result of the query can be found in the result field. In case of an unsuccessful request, ok equals false and the error may be explained in the description field. An error_code field may also be returned.

{
  "ok": false,
  "error_code": 404,
  "description": "Chat not found"
}

MCP Server

The Combot API is also available as an MCP (Model Context Protocol) server. This lets AI assistants like Claude interact with your Telegram group data directly — query analytics, manage members, view leaderboards, and perform moderation actions through natural language.

Quick Start

Claude Code

Run this command in your terminal:

claude mcp add combot --transport http https://mcp.combot.org/mcp --header "Authorization: Bearer YOUR_COMBOT_API_KEY"

Cursor

Add the following to your .cursor/mcp.json:

{
  "mcpServers": {
    "combot": {
      "type": "http",
      "url": "https://mcp.combot.org/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_COMBOT_API_KEY"
      }
    }
  }
}

Other MCP clients

For clients that don't support HTTP transport natively (e.g. Claude Desktop), use the mcp-remote proxy:

{
  "mcpServers": {
    "combot": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote", "https://mcp.combot.org/mcp"],
      "env": {
        "API_KEY": "YOUR_COMBOT_API_KEY"
      }
    }
  }
}

Authentication

The MCP server uses the same API key as the REST API. Generate your key in Settings. Pass it via the API_KEY environment variable or the Authorization: Bearer <key> header, depending on your MCP client.

Available Tools

The MCP server exposes the following tools, corresponding to the API endpoints documented below:

getChats

Returns all groups that the authenticated user can manage. If chat_id is provided, returns only the matching group.

/v5/getChats

Returns an array of groups:

{
  "ok": true,
  "groups": [
    {
      "id": -1001234567890,
      "title": "My Group",
      "username": "mygroup",
      "subs": 1234,
      "cs": { ... },
      "mod": { ... },
      "admins": [
        {
          "user_id": 12345678,
          "name": "Alice",
          "username": "alice",
          "type": "telegram",
          "is_creator": true,
          "can_be_edited": false,
          "tg_rights": {
            "can_manage_chat": true,
            "can_delete_messages": true,
            "can_manage_video_chats": true,
            "can_restrict_members": true,
            "can_promote_members": true,
            "can_change_info": true,
            "can_invite_users": true,
            "can_post_stories": false,
            "can_edit_stories": false,
            "can_delete_stories": false,
            "can_post_messages": false,
            "can_edit_messages": false,
            "can_pin_messages": true,
            "can_manage_topics": true,
            "is_anonymous": false
          },
          "roles": [1]
        },
        {
          "user_id": 87654321,
          "name": "Bob",
          "username": "bob_dev",
          "type": "custom",
          "is_creator": false,
          "roles": [2, 4]
        }
      ]
    }
  ]
}

Admin object

Returned in the admins array of getChats and identifies a user who has access to the group via Telegram admin status or as a Combot-only custom admin.

Permission roles

Combot represents per-admin access as an array of integer role IDs. The same constants are used in the roles field of Admin objects and in the roles parameter accepted by changeAdminPermissions and setAdmin.

When calling changeAdminPermissions or setAdmin, only 2, 3, and 4 are accepted. Pass an empty roles array to revoke all access (the server stores [0]).

Business setAdmin

Grants admin access to a user. Two mutually exclusive paths, selected by promote_in_telegram:

• Default (custom admin) — the user is added to Combot's custom-admin list and granted the requested Combot roles. They are not promoted to a Telegram administrator. The user must already be a member of the chat.
• With promote_in_telegram=true — the user is promoted to Telegram administrator via promoteChatMember with the supplied admin flag fields. Combot roles are stored alongside. Any existing custom-admin entry for the user is cleared (the two states are mutually exclusive). Requires the bot itself to hold can_promote_members in the chat.

The same endpoint also doubles as the edit path: re-calling it for an existing Telegram admin re-issues promoteChatMember with the supplied flags (updating the admin's Telegram rights) and overwrites their stored Combot roles.

/v5/setAdmin

Business removeAdmin

Removes a user's admin access from a group

/v5/removeAdmin

Business changeAdminPermissions

Sets the Combot roles for an existing admin (Telegram or custom) without touching their Telegram admin status. To revoke all access, send an empty roles array.

/v5/changeAdminPermissions

Pro getChatAnalytics

Returns analytics data for a chat over a given time period, including message counts, active users, hourly heatmap data, and a comparison with the previous period.

/v5/getChatAnalytics

Returns analytics object with current and previous period comparison, hourly heatmap, and recent join/leave activity.

Non-Pro groups are limited to a maximum 7-day date range.

Composite analytics

When chat_id contains a comma-separated list of 2–5 chat IDs, the response aggregates across all of them. Joined / Left / Active users are deduplicated across the selected chats — a user present in two of them counts as one. Messages are summed (events are not deduplicated).

• All selected chats must be of the same type (groups can only be combined with groups; channels with channels).
• The caller must have Analytics permission in every selected chat.
• At most 2 of the selected chats may be on Free or Pro plans; the rest must be on Business.

The composite response also includes a composite object describing the selected chats, and each entry in last_joined_users / last_left_users carries the source chat_id and chat_title.

Comparison mode

Add mode=compare to a composite request and the response returns one series per chat instead of an aggregate. No previous-period comparison is included. Each chart payload becomes:

• joined_series, left_series, messages_series, active_users_series (groups only) — each is an array of {chat_id, chat_title, chat_avatar, total, points}, where points is [[ts, count], ...].
• hours_series (groups only) — per-chat heatmap data: {chat_id, chat_title, chat_avatar, hours: [[hour, day_of_week, count], ...]}.

The flag compare: true is set on the result. last_joined_users and last_left_users are not deduplicated by user in composite mode (compare or not) — a user who joined or left two of the selected chats appears as two rows.

Pro getJournal

Returns the moderation journal (action log) for a chat. Includes bans, mutes, warnings, and other moderation actions with timestamps and involved users.

/v5/getJournal

Returns a paginated list of journal entries with timestamp, action_by, action_for, reason, action_id, and text.

action_id values:

Pro getChatUsers

Returns a list of chat members with activity data, join/leave dates, and moderation info. Supports filtering, sorting, and CSV export.

/v5/getChatUsers

Filters

Each filter requires an _operator parameter and a _value parameter. Supported operators: eq, gt, lt, between. For between, pass a second value with _value2. Groups only unless noted otherwise.

Date filters (Joined, Left, Last message) support an optional _unit parameter when using the last operator. Values: hours, days (default), weeks, months. Example: joined_filter_operator=last&joined_filter_value=7&joined_filter_unit=days

Returns a paginated list of user objects with user_id, title, username, avatar, joined, left, msg_total, active_days, last_message, and moderation data (XP, reputation, warnings) if enabled.

Pro getChatMember

Returns detailed information about a chat member.

/v5/getChatMember

Returns a user object with user_id, name, username, avatar, status (member or left), first_join (Unix timestamp), left (Unix timestamp), last_message (Unix timestamp), msg_total (groups only), and xp, reputation, warns when the respective features are enabled.

Pro setChatMemberData

Sets XP, reputation, and/or warns for a chat member. Requires can_restrict_members admin permission.

/v5/setChatMemberData

At least one of xp, reputation, or warns must be provided.

Business getUserActivity

Returns per-user message activity for a group: a daily message-count series and a day-of-week × hour heatmap. Groups only (not supported on channels).

/v5/getUserActivity

Defaults to the last 7 days when from/to are omitted. Returns:

{
  "ok": true,
  "result": {
    "messages":         [[unix_ms, count], ...],   // daily totals, ascending
    "hours":            [[hour, dow, count], ...], // 168 entries (7 × 24)
    "from":             unix_ms,                   // effective range start
    "to":               unix_ms,                   // effective range end
    "date_range_limit": days_or_null               // tier-imposed cap, if any
  }
}

dow is 0–6 (Monday–Sunday), hour is 0–23, both in the chat's timezone.

Pro getReferrals

Returns referral data for a chat over a given time period. Can be filtered by mode: all referrals, by invite link, or by approval.

/v5/getReferrals

Non-Pro groups are limited to a maximum 7-day date range.

Pro getInviteLinks

Returns a list of invite links for the chat with usage statistics.

/v5/getInviteLinks

Returns invite link objects with code, name, creator_id, users_count, left_count, and current_count.

Pro getInviteLinkDetails

Returns detailed join data for a specific invite link, including a joins-per-day chart and individual join records.

/v5/getInviteLinkDetails

Returns chart (joins per day) and joins (individual records with timestamp and user_id).

Business createInviteLink

Creates a new chat invite link and records it in Combot's invite-link tracking. Business plan is required.

Behaviour differs by caller type:

• Admin: Requires can_invite_users permission. All optional parameters below are honoured. The creator field is set to the calling admin's user ID. Limited to 20 links per admin per chat; returns a localized description when the cap is hit.
• Regular user: The User Invite Links feature must be enabled for the group by an admin. Optional parameters (name, expire_date, etc.) are ignored. Limited to 10 links per user; returns a localized description when the cap is hit.

/v5/createInviteLink

Response result contains link_code, invite_link (full URL), name, expire_date, member_limit, creates_join_request, and creator_id.

Pro restrictMember

Restricts a chat member's permissions. Requires can_restrict_members admin permission.

/v5/restrictMember

Pro banMember

Kicks or bans a chat member. Requires can_restrict_members admin permission.

/v5/banMember

Pro unbanMember

Unbans a previously banned chat member. Requires can_restrict_members admin permission. Only unbans if currently banned.

/v5/unbanMember

Leaderboards

Every leaderboard response contains at most 50 users. To load the next XP, reputation, or custom-period message page, pass the response's check_from value in the next request. All-time message results instead use a zero-based page number.

Optional row fields such as user_id and last-message time are returned to Telegram admins and Combot custom admins with the Analytics role. The requesting user's own row may also include its identifier when available, so clients must treat these fields as optional.

show_admins=true controls whether Telegram admins are included in the ranking; it does not grant privileged row access and does not filter Combot-only custom admins.

Pass usernames=true to append a user's Telegram username as the final tuple item when that user has one. The username follows any privileged fields; users without a username do not receive a trailing null.

Pass avatars=true to insert the avatar field at the documented tuple position. Without that parameter the avatar field is omitted entirely; when requested but unavailable, its value is null.

getXpLeaderboard

Returns the XP leaderboard for a group, including custom ranks and level thresholds. Groups only. If XP is disabled in the group settings, the endpoint returns 404. If XP is enabled but no member has accumulated XP yet, it returns an empty successful result.

/v5/getXpLeaderboard

Returns users as [xp, name, rank, user_id?, username?], or [xp, name, avatar, rank, user_id?, username?] when avatars are requested, plus ranks (custom rank names), exp (level thresholds), has_more, check_from, and optional me (requesting user's position and entry when resolved).

getRepLeaderboard

Returns the reputation leaderboard for a group. Groups only. If reputation is disabled in the group settings, the endpoint returns 404. If reputation is enabled but no member has accumulated reputation yet, it returns an empty successful result.

/v5/getRepLeaderboard

Returns users as [rep, name, user_id?, username?], or [rep, name, avatar, user_id?, username?] when avatars are requested, plus has_more, check_from, and optional me.

getUsersLeaderboard

Returns users ranked by message count for a time period. Groups only.

/v5/getUsersLeaderboard

Returns users as [messages, unique_reaction_givers, name, last_message_ms?, user_id?, username?], or [messages, unique_reaction_givers, name, avatar, last_message_ms?, user_id?, username?] when avatars are requested, plus has_more, check_from for custom periods or the next page for all time, and optional me. The reaction value counts distinct members who reacted to that member's messages during the requested custom period; all-time mode currently returns 0 for this field. The stable avatar position is null unless avatar images are requested.