Telegram Member Management API

openapi: 3.0.3
info:
  title: Telegram Bot Bot Info Member Management API
  description: The Telegram Bot API is an HTTP-based interface created for developers keen on building bots for Telegram. Bots can receive messages, send messages, manage chats, handle payments, work with stickers, and much more. All methods are HTTPS POST requests to https://api.telegram.org/bot<token>/METHOD_NAME.
  version: '9.5'
  contact:
    name: Telegram Support
    url: https://core.telegram.org/bots/api
  license:
    name: Terms of Service
    url: https://telegram.org/tos
  termsOfService: https://telegram.org/tos
servers:
- url: https://api.telegram.org/bot{token}
  description: Telegram Bot API Server
  variables:
    token:
      default: YOUR_BOT_TOKEN
      description: Bot authentication token obtained from @BotFather
security:
- BotToken: []
tags:
- name: Member Management
  description: Methods for managing chat members and administrators
paths:
  /banChatMember:
    post:
      operationId: banChatMember
      summary: Ban Chat Member
      description: Ban a user in a group, a supergroup or a channel.
      tags:
      - Member Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chat_id
              - user_id
              properties:
                chat_id:
                  oneOf:
                  - type: integer
                  - type: string
                  description: Unique identifier for the target group or username
                user_id:
                  type: integer
                  description: Unique identifier of the target user
                until_date:
                  type: integer
                  description: Date when the user will be unbanned (Unix time)
                revoke_messages:
                  type: boolean
                  description: Pass true to delete all messages from the chat for the user
      responses:
        '200':
          description: User banned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
  /unbanChatMember:
    post:
      operationId: unbanChatMember
      summary: Unban Chat Member
      description: Unban a previously banned user in a supergroup or channel.
      tags:
      - Member Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chat_id
              - user_id
              properties:
                chat_id:
                  oneOf:
                  - type: integer
                  - type: string
                  description: Unique identifier for the target group
                user_id:
                  type: integer
                  description: Unique identifier of the target user
                only_if_banned:
                  type: boolean
                  description: Do nothing if the user is not banned
      responses:
        '200':
          description: User unbanned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
  /restrictChatMember:
    post:
      operationId: restrictChatMember
      summary: Restrict Chat Member
      description: Restrict a user in a supergroup.
      tags:
      - Member Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chat_id
              - user_id
              - permissions
              properties:
                chat_id:
                  oneOf:
                  - type: integer
                  - type: string
                  description: Unique identifier for the target chat
                user_id:
                  type: integer
                  description: Unique identifier of the target user
                permissions:
                  $ref: '#/components/schemas/ChatPermissions'
                until_date:
                  type: integer
                  description: Date when restrictions will be lifted for the user (Unix time)
      responses:
        '200':
          description: User restrictions updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
  /promoteChatMember:
    post:
      operationId: promoteChatMember
      summary: Promote Chat Member
      description: Promote or demote a user in a supergroup or a channel.
      tags:
      - Member Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chat_id
              - user_id
              properties:
                chat_id:
                  oneOf:
                  - type: integer
                  - type: string
                  description: Unique identifier for the target chat
                user_id:
                  type: integer
                  description: Unique identifier of the target user
                can_change_info:
                  type: boolean
                  description: Pass true if the administrator can change chat title, photo and other settings
                can_post_messages:
                  type: boolean
                  description: Pass true if the administrator can post in the channel
                can_edit_messages:
                  type: boolean
                  description: Pass true if the administrator can edit messages of other users
                can_delete_messages:
                  type: boolean
                  description: Pass true if the administrator can delete messages of other users
                can_restrict_members:
                  type: boolean
                  description: Pass true if the administrator can restrict, ban or unban chat members
                can_promote_members:
                  type: boolean
                  description: Pass true if the administrator can add new administrators
                can_manage_chat:
                  type: boolean
                  description: Pass true if the administrator can manage the chat
      responses:
        '200':
          description: Administrator rights updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
  /setChatAdministratorCustomTitle:
    post:
      operationId: setChatAdministratorCustomTitle
      summary: Set Chat Administrator Custom Title
      description: Set a custom title for an administrator in a supergroup promoted by the bot.
      tags:
      - Member Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chat_id
              - user_id
              - custom_title
              properties:
                chat_id:
                  oneOf:
                  - type: integer
                  - type: string
                  description: Unique identifier for the target chat
                user_id:
                  type: integer
                  description: Unique identifier of the target user
                custom_title:
                  type: string
                  description: New custom title for the administrator (0-16 characters)
      responses:
        '200':
          description: Custom title set successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
  /approveChatJoinRequest:
    post:
      operationId: approveChatJoinRequest
      summary: Approve Chat Join Request
      description: Approve a chat join request.
      tags:
      - Member Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chat_id
              - user_id
              properties:
                chat_id:
                  oneOf:
                  - type: integer
                  - type: string
                  description: Unique identifier for the target chat
                user_id:
                  type: integer
                  description: Unique identifier of the target user
      responses:
        '200':
          description: Join request approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
  /declineChatJoinRequest:
    post:
      operationId: declineChatJoinRequest
      summary: Decline Chat Join Request
      description: Decline a chat join request.
      tags:
      - Member Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chat_id
              - user_id
              properties:
                chat_id:
                  oneOf:
                  - type: integer
                  - type: string
                  description: Unique identifier for the target chat
                user_id:
                  type: integer
                  description: Unique identifier of the target user
      responses:
        '200':
          description: Join request declined
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
components:
  schemas:
    ChatPermissions:
      type: object
      properties:
        can_send_messages:
          type: boolean
          description: True if the user is allowed to send text messages
        can_send_audios:
          type: boolean
          description: True if the user is allowed to send audios
        can_send_documents:
          type: boolean
          description: True if the user is allowed to send documents
        can_send_photos:
          type: boolean
          description: True if the user is allowed to send photos
        can_send_videos:
          type: boolean
          description: True if the user is allowed to send videos
        can_send_polls:
          type: boolean
          description: True if the user is allowed to send polls
        can_send_other_messages:
          type: boolean
          description: True if the user is allowed to send animations, games, stickers
        can_add_web_page_previews:
          type: boolean
          description: True if the user is allowed to add web page previews to messages
        can_change_info:
          type: boolean
          description: True if the user is allowed to change chat title, photo and settings
        can_invite_users:
          type: boolean
          description: True if the user is allowed to invite new users to the chat
        can_pin_messages:
          type: boolean
          description: True if the user is allowed to pin messages
    BooleanResponse:
      type: object
      properties:
        ok:
          type: boolean
        result:
          type: boolean
  securitySchemes:
    BotToken:
      type: apiKey
      in: path
      name: token
      description: Bot authentication token obtained from @BotFather (embedded in URL path)
externalDocs:
  description: Official Telegram Bot API Documentation
  url: https://core.telegram.org/bots/api