Telegram Bot API

openapi: 3.0.3
info:
  title: Telegram Bot 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
externalDocs:
  description: Official Telegram Bot API Documentation
  url: https://core.telegram.org/bots/api
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: Getting Updates
    description: Methods for receiving incoming updates from Telegram
  - name: Bot Info
    description: Methods for getting and setting bot information
  - name: Messaging
    description: Methods for sending messages and media
  - name: Message Editing
    description: Methods for editing and deleting messages
  - name: Chat Management
    description: Methods for managing chats and chat settings
  - name: Member Management
    description: Methods for managing chat members and administrators
  - name: Invites
    description: Methods for managing chat invite links
  - name: Payments
    description: Methods for handling Telegram Payments
  - name: Stickers
    description: Methods for working with sticker sets
paths:
  /getMe:
    post:
      operationId: getMe
      summary: Get Bot Info
      description: A simple method for testing your bot authentication token. Returns basic information about the bot in the form of a User object.
      tags:
        - Bot Info
      responses:
        '200':
          description: Bot user object returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
  /getUpdates:
    post:
      operationId: getUpdates
      summary: Get Updates
      description: >-
        Receive incoming updates using long polling. Returns an array of Update
        objects. Notes: this method will not work if an outgoing webhook is set up.
      tags:
        - Getting Updates
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                offset:
                  type: integer
                  description: Identifier of the first update to be returned
                limit:
                  type: integer
                  description: Limits the number of updates to be retrieved (1-100)
                  minimum: 1
                  maximum: 100
                timeout:
                  type: integer
                  description: Timeout in seconds for long polling
                allowed_updates:
                  type: array
                  items:
                    type: string
                  description: List of update types the bot should receive
      responses:
        '200':
          description: Array of Update objects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatesResponse'
  /setWebhook:
    post:
      operationId: setWebhook
      summary: Set Webhook
      description: Specify a URL and receive incoming updates via an outgoing webhook.
      tags:
        - Getting Updates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  description: HTTPS URL to send updates to
                ip_address:
                  type: string
                  description: Fixed IP address to send webhook requests to
                max_connections:
                  type: integer
                  description: Maximum allowed number of simultaneous HTTPS connections
                  minimum: 1
                  maximum: 100
                allowed_updates:
                  type: array
                  items:
                    type: string
                  description: List of update types the bot should receive
                drop_pending_updates:
                  type: boolean
                  description: Pass true to drop all pending updates
                secret_token:
                  type: string
                  description: A secret token to be sent in a header in every webhook request
      responses:
        '200':
          description: Webhook set successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
  /deleteWebhook:
    post:
      operationId: deleteWebhook
      summary: Delete Webhook
      description: Remove webhook integration.
      tags:
        - Getting Updates
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                drop_pending_updates:
                  type: boolean
                  description: Pass true to drop all pending updates
      responses:
        '200':
          description: Webhook deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
  /getWebhookInfo:
    post:
      operationId: getWebhookInfo
      summary: Get Webhook Info
      description: Get current webhook status.
      tags:
        - Getting Updates
      responses:
        '200':
          description: Webhook info object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookInfoResponse'
  /sendMessage:
    post:
      operationId: sendMessage
      summary: Send Message
      description: Send text messages.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - text
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat or username
                text:
                  type: string
                  description: Text of the message to be sent
                parse_mode:
                  type: string
                  enum: [Markdown, MarkdownV2, HTML]
                  description: Mode for parsing entities in the message text
                disable_notification:
                  type: boolean
                  description: Sends the message silently
                reply_to_message_id:
                  type: integer
                  description: If the message is a reply, ID of the original message
      responses:
        '200':
          description: Message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /forwardMessage:
    post:
      operationId: forwardMessage
      summary: Forward Message
      description: Forward messages of any kind.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - from_chat_id
                - message_id
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                from_chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the chat where the original message was sent
                message_id:
                  type: integer
                  description: Message identifier in the chat specified in from_chat_id
                disable_notification:
                  type: boolean
                  description: Sends the message silently
      responses:
        '200':
          description: Forwarded message object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /copyMessage:
    post:
      operationId: copyMessage
      summary: Copy Message
      description: Copy messages of any kind without the forward marker.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - from_chat_id
                - message_id
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                from_chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the source chat
                message_id:
                  type: integer
                  description: Message identifier in the source chat
                caption:
                  type: string
                  description: New caption for media; pass empty string to remove caption
      responses:
        '200':
          description: Copied message identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageIdResponse'
  /sendPhoto:
    post:
      operationId: sendPhoto
      summary: Send Photo
      description: Send photos.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - photo
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                photo:
                  type: string
                  description: Photo to send (file_id, URL, or multipart/form-data)
                caption:
                  type: string
                  description: Photo caption
                parse_mode:
                  type: string
                  description: Mode for parsing entities in the caption
      responses:
        '200':
          description: Photo message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /sendDocument:
    post:
      operationId: sendDocument
      summary: Send Document
      description: Send general files.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - document
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                document:
                  type: string
                  description: File to send (file_id, URL, or multipart/form-data)
                caption:
                  type: string
                  description: Document caption
      responses:
        '200':
          description: Document message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /sendAudio:
    post:
      operationId: sendAudio
      summary: Send Audio
      description: Send audio files as a playable music track.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - audio
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                audio:
                  type: string
                  description: Audio file to send (file_id, URL, or multipart/form-data)
                caption:
                  type: string
                  description: Audio caption
                duration:
                  type: integer
                  description: Duration of the audio in seconds
                performer:
                  type: string
                  description: Performer
                title:
                  type: string
                  description: Track name
      responses:
        '200':
          description: Audio message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /sendVideo:
    post:
      operationId: sendVideo
      summary: Send Video
      description: Send video files.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - video
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                video:
                  type: string
                  description: Video to send (file_id, URL, or multipart/form-data)
                duration:
                  type: integer
                  description: Duration of sent video in seconds
                width:
                  type: integer
                  description: Video width
                height:
                  type: integer
                  description: Video height
                caption:
                  type: string
                  description: Video caption
      responses:
        '200':
          description: Video message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /sendVoice:
    post:
      operationId: sendVoice
      summary: Send Voice
      description: Send audio files as a voice message.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - voice
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                voice:
                  type: string
                  description: Audio file to send (file_id, URL, or multipart/form-data)
                caption:
                  type: string
                  description: Voice message caption
                duration:
                  type: integer
                  description: Duration of the voice message in seconds
      responses:
        '200':
          description: Voice message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /sendLocation:
    post:
      operationId: sendLocation
      summary: Send Location
      description: Send a point on the map.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - latitude
                - longitude
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                latitude:
                  type: number
                  format: float
                  description: Latitude of the location
                longitude:
                  type: number
                  format: float
                  description: Longitude of the location
                horizontal_accuracy:
                  type: number
                  description: The radius of uncertainty in meters (0-1500)
                live_period:
                  type: integer
                  description: Period in seconds during which location can be updated
      responses:
        '200':
          description: Location message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /sendContact:
    post:
      operationId: sendContact
      summary: Send Contact
      description: Send phone contacts.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - phone_number
                - first_name
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                phone_number:
                  type: string
                  description: Contact's phone number
                first_name:
                  type: string
                  description: Contact's first name
                last_name:
                  type: string
                  description: Contact's last name
                vcard:
                  type: string
                  description: Additional data about the contact in vCard format
      responses:
        '200':
          description: Contact sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /sendPoll:
    post:
      operationId: sendPoll
      summary: Send Poll
      description: Send a native poll.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - question
                - options
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                question:
                  type: string
                  description: Poll question (1-300 characters)
                options:
                  type: array
                  items:
                    type: string
                  description: List of answer options (2-10 strings)
                is_anonymous:
                  type: boolean
                  description: True if the poll needs to be anonymous
                type:
                  type: string
                  enum: [regular, quiz]
                  description: Poll type (regular or quiz)
                allows_multiple_answers:
                  type: boolean
                  description: True if the poll allows multiple answers
      responses:
        '200':
          description: Poll message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /sendDice:
    post:
      operationId: sendDice
      summary: Send Dice
      description: Send an animated emoji that will display a random value.
      tags:
        - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                emoji:
                  type: string
                  description: Emoji on which the dice throw animation is based
                  default: "\U0001F3B2"
      responses:
        '200':
          description: Dice message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /editMessageText:
    post:
      operationId: editMessageText
      summary: Edit Message Text
      description: Edit text and game messages.
      tags:
        - Message Editing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - text
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Required if inline_message_id is not specified
                message_id:
                  type: integer
                  description: Required if inline_message_id is not specified
                inline_message_id:
                  type: string
                  description: Required if chat_id and message_id are not specified
                text:
                  type: string
                  description: New text of the message
                parse_mode:
                  type: string
                  description: Mode for parsing entities in the message text
      responses:
        '200':
          description: Edited message object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /editMessageCaption:
    post:
      operationId: editMessageCaption
      summary: Edit Message Caption
      description: Edit captions of messages.
      tags:
        - Message Editing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Required if inline_message_id is not specified
                message_id:
                  type: integer
                  description: Required if inline_message_id is not specified
                caption:
                  type: string
                  description: New caption of the message
                parse_mode:
                  type: string
                  description: Mode for parsing entities in the caption
      responses:
        '200':
          description: Edited message object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /deleteMessage:
    post:
      operationId: deleteMessage
      summary: Delete Message
      description: Delete a message, including service messages.
      tags:
        - Message Editing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - message_id
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
                message_id:
                  type: integer
                  description: Identifier of the message to delete
      responses:
        '200':
          description: Message deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
  /getUserProfilePhotos:
    post:
      operationId: getUserProfilePhotos
      summary: Get User Profile Photos
      description: Get a list of profile pictures for a user.
      tags:
        - Bot Info
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
              properties:
                user_id:
                  type: integer
                  description: Unique identifier of the target user
                offset:
                  type: integer
                  description: Sequential number of the first photo to be returned
                limit:
                  type: integer
                  description: Limits the number of photos to be retrieved (1-100)
      responses:
        '200':
          description: User profile photos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfilePhotosResponse'
  /getFile:
    post:
      operationId: getFile
      summary: Get File
      description: Get basic info about a file and prepare it for downloading.
      tags:
        - Bot Info
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - file_id
              properties:
                file_id:
                  type: string
                  description: File identifier to get info about
      responses:
        '200':
          description: File object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
  /getChat:
    post:
      operationId: getChat
      summary: Get Chat
      description: Get up-to-date information about the chat.
      tags:
        - Chat Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
      responses:
        '200':
          description: Chat object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
  /getChatAdministrators:
    post:
      operationId: getChatAdministrators
      summary: Get Chat Administrators
      description: Get a list of administrators in a chat.
      tags:
        - Chat Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
      responses:
        '200':
          description: Array of ChatMember objects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMembersResponse'
  /getChatMemberCount:
    post:
      operationId: getChatMemberCount
      summary: Get Chat Member Count
      description: Get the number of members in a chat.
      tags:
        - Chat Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
      responses:
        '200':
          description: Number of chat members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegerResponse'
  /getChatMember:
    post:
      operationId: getChatMember
      summary: Get Chat Member
      description: Get information about a member of a chat.
      tags:
        - Chat 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: ChatMember object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMemberResponse'
  /leaveChat:
    post:
      operationId: leaveChat
      summary: Leave Chat
      description: Use this method for your bot to leave a group, supergroup or channel.
      tags:
        - Chat Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
              properties:
                chat_id:
                  oneOf:
                    - type: integer
                    - type: string
                  description: Unique identifier for the target chat
      responses:
        '200':
          description: Bot left the chat
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
  /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_

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telegram/refs/heads/main/openapi/telegram-bot-openapi.yml