Documentation
Documentation
https://core.telegram.org/bots/api
GettingStarted
https://core.telegram.org/bots
Authentication
https://core.telegram.org/bots/api#authorizing-your-bot
OpenAPI Specification
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