API reference

Communities

8 endpoints in this group.

Lists Telegram communities

GET/api/v1/communities

The groups and channels the bot was added to, newest first. The member role sees only the communities of bots it can access. Scope: communities:read.

Scope
communities:read
SDK method
listCommunities · list_communities
MCP tool
listCommunitiesread-only

Paginated

Parameters

NameTypeRequiredDescription
bot_idqueryuuidnoThis bot only
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/communities?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_name": "string",
      "bot_username": "string",
      "chat_id": "string",
      "type": "string",
      "title": "Example",
      "username": "ayse",
      "bot_status": "string",
      "member_count": 1,
      "last_activity_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Community details

GET/api/v1/communities/{id}

Settings, moderation rules, the bot's status and permissions, member count and forum topics. The bot token is never returned. Scope: communities:read.

Scope
communities:read
SDK method
getCommunity · get_community
MCP tool
getCommunityread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_name": "string",
    "bot_username": "string",
    "chat_id": "string",
    "type": "string",
    "title": "Example",
    "username": "ayse",
    "bot_status": "string",
    "member_count": 1,
    "last_activity_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "bot_permissions": {
      "key": true
    },
    "welcome_enabled": true,
    "welcome_message": "string",
    "welcome_delete_after_sec": 1,
    "ai_enabled": true,
    "ai_hourly_limit": 1,
    "join_request_mode": "manual",
    "join_request_message": "string",
    "join_request_button": "string",
    "join_approved_message": "string",
    "rules": {
      "block_links": true,
      "block_forwards": true,
      "banned_words": [
        "string"
      ],
      "flood_count": 1,
      "flood_seconds": 1,
      "action": "delete",
      "exempt_admins": true
    },
    "forum_topics": [
      {
        "id": 1,
        "name": "Hiboty"
      }
    ],
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Updates community settings

PATCH/api/v1/communities/{id}

Only the fields you send change, including inside rules. The welcome message can't be empty while welcome is on; verify mode needs a join message and button. A missing bot permission doesn't block saving and is reported in warnings. Needs admin permission. Scope: communities:write.

Scope
communities:write
SDK method
updateCommunity · update_community
MCP tool
updateCommunity

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
welcome_enabledbooleanno
welcome_messagestringnolen ≤ 1000
welcome_delete_after_secenumno0 | 60 | 300 | 1800 | 3600
ai_enabledbooleanno
ai_hourly_limitintegernoval 1–500
join_request_modeenumnomanual | approve | verify
join_request_messagestringnolen ≤ 1000
join_request_buttonstringnolen ≤ 64
join_approved_messagestringnolen ≤ 1000
rulesobjectno
rules.block_linksbooleanno
rules.block_forwardsbooleanno
rules.banned_wordsstring[]noAn item with a comma or line break is split into several wordsitems ≤ 200
rules.flood_countintegernoval 0–50
rules.flood_secondsintegernoval 3–300
rules.actionenumnodelete | warn | mute
rules.exempt_adminsbooleanno

Example request

curl -X PATCH "https://hiboty.com/api/v1/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"welcome_enabled":true,"welcome_message":"Welcome {{isim}}!","rules":{"block_links":true,"flood_count":5,"flood_seconds":10,"action":"warn"}}'

Example response (200)

JSON
{
  "data": {
    "community": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_name": "string",
      "bot_username": "string",
      "chat_id": "string",
      "type": "string",
      "title": "Example",
      "username": "ayse",
      "bot_status": "string",
      "member_count": 1,
      "last_activity_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z",
      "bot_permissions": {
        "key": true
      },
      "welcome_enabled": true,
      "welcome_message": "string",
      "welcome_delete_after_sec": 1,
      "ai_enabled": true,
      "ai_hourly_limit": 1,
      "join_request_mode": "manual",
      "join_request_message": "string",
      "join_request_button": "string",
      "join_approved_message": "string",
      "rules": {
        "block_links": true,
        "block_forwards": true,
        "banned_words": [
          "string"
        ],
        "flood_count": 1,
        "flood_seconds": 1,
        "action": "delete",
        "exempt_admins": true
      },
      "forum_topics": [
        {
          "id": 1,
          "name": "Hiboty"
        }
      ],
      "updated_at": "2026-11-06T09:00:00.000Z"
    },
    "warnings": [
      {
        "code": "ornek",
        "message": "string"
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Removes a community

DELETE/api/v1/communities/{id}

Deletes the community record with its scheduled posts, invite links and statistics; the bot isn't removed from the Telegram group. Needs admin permission. Scope: communities:write.

Scope
communities:write
SDK method
removeCommunity · remove_community
MCP tool
removeCommunityirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Refreshes the member count from Telegram

POST/api/v1/communities/{id}/refresh-members

Sends a request to Telegram. The member role can call it too, but needs access to the bot. A Telegram error returns 502 channel_error; a disconnected bot returns 409 not_connected. Scope: communities:write.

Scope
communities:write
SDK method
refreshCommunityMembers · refresh_community_members
MCP tool
refreshCommunityMembersexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Example request

curl -X POST "https://hiboty.com/api/v1/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/refresh-members" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "member_count": 1
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.not_connected
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).channel_error