openapi: 3.0.3
info:
  title: Telegram Bot Bot Info Messaging 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: Messaging
  description: Methods for sending messages and media
paths:
  /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: 🎲
      responses:
        '200':
          description: Dice message sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /answerCallbackQuery:
    post:
      operationId: answerCallbackQuery
      summary: Answer Callback Query
      description: Send answers to callback queries sent from inline keyboards.
      tags:
      - Messaging
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - callback_query_id
              properties:
                callback_query_id:
                  type: string
                  description: Unique identifier for the query to be answered
                text:
                  type: string
                  description: Text of the notification to display (0-200 characters)
                show_alert:
                  type: boolean
                  description: If true, alert instead of notification
                url:
                  type: string
                  description: URL to open upon button press
                cache_time:
                  type: integer
                  description: Maximum time in seconds for caching results (default 0)
      responses:
        '200':
          description: Callback query answered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanResponse'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for this user or bot
        is_bot:
          type: boolean
          description: True if this user is a bot
        first_name:
          type: string
          description: User's or bot's first name
        last_name:
          type: string
          description: User's or bot's last name
        username:
          type: string
          description: User's or bot's username
        language_code:
          type: string
          description: IETF language tag of the user's language
        is_premium:
          type: boolean
          description: True if this user is a Telegram Premium user
      required:
      - id
      - is_bot
      - first_name
    MessageIdResponse:
      type: object
      properties:
        ok:
          type: boolean
        result:
          type: object
          properties:
            message_id:
              type: integer
    Chat:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for this chat
        type:
          type: string
          enum:
          - private
          - group
          - supergroup
          - channel
          description: Type of chat
        title:
          type: string
          description: Title for supergroups, channels and group chats
        username:
          type: string
          description: Username for private chats, supergroups and channels
        first_name:
          type: string
          description: First name of the other party in a private chat
        last_name:
          type: string
          description: Last name of the other party in a private chat
        description:
          type: string
          description: Description for groups, supergroups and channel chats
        invite_link:
          type: string
          description: Primary invite link for the chat
        member_count:
          type: integer
          description: Number of members in a chat
      required:
      - id
      - type
    MessageResponse:
      type: object
      properties:
        ok:
          type: boolean
        result:
          $ref: '#/components/schemas/Message'
    BooleanResponse:
      type: object
      properties:
        ok:
          type: boolean
        result:
          type: boolean
    Message:
      type: object
      properties:
        message_id:
          type: integer
          description: Unique message identifier inside a chat
        from:
          $ref: '#/components/schemas/User'
        chat:
          $ref: '#/components/schemas/Chat'
        date:
          type: integer
          description: Date the message was sent in Unix time
        text:
          type: string
          description: For text messages, the actual UTF-8 text of the message
        caption:
          type: string
          description: Caption for the animation, audio, document, photo, video or voice
      required:
      - message_id
      - date
      - chat
  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