tdlight-telegram-bot-api/tdlight-api-openapi.yaml

12487 lines
553 KiB
YAML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

openapi: 3.0.0
info:
title: tdlight Bot API
description: OpenAPI schema for the tdlight bot api
version: 5.0.0
servers:
- url: 'https://botapi.giuseppem99.xyz/{type}{token}'
variables:
type:
default: bot
enum:
- bot
- user
token:
default: '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11'
description: Each bot is given a unique authentication token when it is created and each user is given a unique authentication token when logging in.
- url: 'https://telegram.rest/{type}{token}'
variables:
type:
default: bot
enum:
- bot
- user
token:
default: '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11'
description: Each bot is given a unique authentication token when it is created and each user is given a unique authentication token when logging in.
- url: '{base_url}/{type}{token}'
variables:
base_url:
default: 'https://botapi.giuseppem99.xyz'
description: Base url of the tdlight bot api server
type:
default: bot
enum:
- bot
- user
token:
default: '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11'
description: Each bot is given a unique authentication token when it is created and each user is given a unique authentication token when logging in.
tags:
- name: added
description: Added Methods in the tdlight-bot-api
- name: user-only
description: These methods can only be called as user
- name: modified
description: These methods are modified in the tdlight-bot-api
paths:
/userLogin:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Use this method to receive the authorization token to log in as user.
Note: You don't have your token yet, so the domain is just {base_url}/userLogin
Returns an `AuthorizationState` with the user token on success.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
phone_number:
description: Your phone number to log in.
type: string
required:
- phone_number
multipart/form-data:
schema:
type: object
properties:
phone_number:
description: Your phone number to log in.
type: string
required:
- phone_number
application/json:
schema:
type: object
properties:
phone_number:
description: Your phone number to log in.
type: string
required:
- phone_number
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
$ref: '#/components/schemas/AuthorizationState'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: '{base_url}'
description: Custom Endpoint to get the user token.
variables:
base_url:
default: 'https://botapi.giuseppem99.xyz'
description: Base url of the tdlight bot api server
/authCode:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Use this method in the authorization process to check your authentication code. Returns an `AuthorizationState` on success.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
code:
description: 'The verification code received via SMS, Telegram message, phone call, or flash call.'
type: integer
required:
- code
multipart/form-data:
schema:
type: object
properties:
code:
description: 'The verification code received via SMS, Telegram message, phone call, or flash call.'
type: integer
required:
- code
application/json:
schema:
type: object
properties:
code:
description: 'The verification code received via SMS, Telegram message, phone call, or flash call.'
type: integer
required:
- code
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
$ref: '#/components/schemas/AuthorizationState'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/authPassword:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Use this method in the authorization process to check your 2-factor-authorization password for correctness. Returns an `AuthorizationState` on success.
*Never* send your password over a plain http connection. Make sure https is enabled or use this API locally.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
password:
description: The password to check.
type: string
required:
- password
multipart/form-data:
schema:
type: object
properties:
password:
description: The password to check.
type: string
required:
- password
application/json:
schema:
type: object
properties:
password:
description: The password to check.
type: string
required:
- password
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
$ref: '#/components/schemas/AuthorizationState'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/registerUser:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Use this method to register a new user account. Only works after sending the authcode if the user is not yet registered. Returns an `AuthorizationState` on success.
User registration is disabled by default. You can enable it with the `--allow-users-registration` command line option or the env variable `TELEGRAM_ALLOW_USERS_REGISTRATION` set to `1` when using docker.s
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
first_name:
description: The first name of the user; 1-64 characters.
type: string
last_name:
description: The last name of the user; 0-64 characters.
type: string
required:
- first_name
multipart/form-data:
schema:
type: object
properties:
first_name:
description: The first name of the user; 1-64 characters.
type: string
last_name:
description: The last name of the user; 0-64 characters.
type: string
required:
- first_name
application/json:
schema:
type: object
properties:
first_name:
description: The first name of the user; 1-64 characters.
type: string
last_name:
description: The last name of the user; 0-64 characters.
type: string
required:
- first_name
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
$ref: '#/components/schemas/AuthorizationState'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/optimizeMemory:
post:
tags:
- added
description: Calling `optimizeMemory` will remove old data from the in-memory cache and give the freed memory back to the os. Returns *True* on success.
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
default: true
type: boolean
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/getMessageInfo:
post:
tags:
- added
description: Get information about a message. Returns a `Message` on success.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Message identifier in the chat specified in *from\_chat\_id*
type: integer
required:
- chat_id
- message_id
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Message identifier in the chat specified in *from\_chat\_id*
type: integer
required:
- chat_id
- message_id
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Message identifier in the chat specified in *from\_chat\_id*
type: integer
required:
- chat_id
- message_id
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
$ref: '#/components/schemas/Message'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/getChatMembers:
post:
tags:
- added
description: |-
Use this method to get a list of members in a chat. On success, returns an Array of [ChatMember](https://core.telegram.org/bots/api/#chatmember) objects that contains information about all chat members. Administrator privileges may be required for some filters.
Telegram only returns up to 10,000 members per group using this method. If you want to get more members, you can try to fetch additional users with different `query` parameters
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
filter:
description: 'Filter the members you want to get. Must be one of `members`, `banned`, `restricted`, `bots` or `admins`. Only works in supergroups and channels. Administrator privileges may be required for some filters.'
type: string
enum:
- members
- banned
- restricted
- bots
- admins
query:
description: Query to search for in names and usernames
type: string
offset:
description: Number of users to skip.
type: integer
limit:
description: The maximum number of users be returned; up to 200.
type: integer
minimum: 1
maximum: 200
required:
- chat_id
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
filter:
description: 'Filter the members you want to get. Must be one of `members`, `banned`, `restricted`, `bots` or `admins`. Only works in supergroups and channels. Administrator privileges may be required for some filters.'
type: string
enum:
- members
- banned
- restricted
- bots
- admins
query:
description: Query to search for in names and usernames
type: string
offset:
description: Number of users to skip.
type: integer
limit:
description: The maximum number of users be returned; up to 200.
type: integer
minimum: 1
maximum: 200
required:
- chat_id
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
filter:
description: 'Filter the members you want to get. Must be one of `members`, `banned`, `restricted`, `bots` or `admins`. Only works in supergroups and channels. Administrator privileges may be required for some filters.'
type: string
enum:
- members
- banned
- restricted
- bots
- admins
query:
description: Query to search for in names and usernames
type: string
offset:
description: Number of users to skip.
type: integer
limit:
description: The maximum number of users be returned; up to 200.
type: integer
minimum: 1
maximum: 200
required:
- chat_id
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: array
items:
$ref: '#/components/schemas/ChatMember'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/deleteMessages:
post:
tags:
- modified
description: |-
Use this method to delete multiple messages simultaneously.
This method can delete a set of message ids, or a range of message ids.
If you specify "message_ids", this method tries to delete the specified set of ids:
If some of the specified messages can't be found, they are skipped.
Returns True on success.
If you specify "start" and "end", this method deletes all the messages with message_id in range between start and end:
The start parameter MUST be less than the end parameter
Both start and end must be positive non zero numbers
The method will always return true as a result, even if the messages cannot be deleted
This method does not work on private chat or normal groups It is not suggested to delete more than 200 messages per call.
*NOTE*
The maximum number of messages to be deleted in a single batch is determined by the max-batch-operations parameter and is 10000 by default.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_ids:
type: array
items:
type: integer
start:
description: First message id to delete
type: integer
end:
description: Last message id to delete
type: integer
required:
- chat_id
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_ids:
type: array
items:
type: integer
start:
description: First message id to delete
type: integer
end:
description: Last message id to delete
type: integer
required:
- chat_id
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_ids:
type: array
items:
type: integer
start:
description: First message id to delete
type: integer
end:
description: Last message id to delete
type: integer
required:
- chat_id
required: true
responses:
'200':
description: 'Request was successful, the result is returned.'
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
default: true
type: boolean
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/ping:
post:
tags:
- added
description: Send an MTProto ping message to the telegram servers. Useful to detect the delay of the bot api server. Returns the time in seconds as double-precision floating-point number.
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: number
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/getChats:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Returns an ordered list of chats. For optimal performance the number of returned chats is chosen by the library.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
offset_chat_id:
description: Chat identifier to return chats from.
type: integer
multipart/form-data:
schema:
type: object
properties:
offset_chat_id:
description: Chat identifier to return chats from.
type: integer
application/json:
schema:
type: object
properties:
offset_chat_id:
description: Chat identifier to return chats from.
type: integer
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: array
items:
$ref: '#/components/schemas/Chat'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/getCommonChats:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Returns list of chats you have in commen with the other user. Currently returns an Error because of a tdlight bug. For optimal performance the number of returned chats is chosen by the library.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
user_id:
description: Unique identifier of the target user
type: integer
offset_chat_id:
description: Chat identifier to return chats from.
type: integer
required:
- user_id
multipart/form-data:
schema:
type: object
properties:
user_id:
description: Unique identifier of the target user
type: integer
offset_chat_id:
description: Chat identifier to return chats from.
type: integer
required:
- user_id
application/json:
schema:
type: object
properties:
user_id:
description: Unique identifier of the target user
type: integer
offset_chat_id:
description: Chat identifier to return chats from.
type: integer
required:
- user_id
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: array
items:
$ref: '#/components/schemas/Chat'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/getInactiveChats:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Returns a list of recently inactive supergroups and channels. Can be used when user reaches limit on the number of joined supergroups and channels and receives CHANNELS_TOO_MUCH error.
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: array
items:
$ref: '#/components/schemas/Chat'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/getNearbyChats:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Returns a list of chats nearby the specified location. Telegram may send old results if you change your location too quick.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
latitude:
description: Latitude of the location
type: number
longitude:
description: Longitude of the location
type: number
horizontal_accuracy:
description: 'The radius of uncertainty for the location, measured in meters; 0-1500'
type: number
required:
- latitude
- longitude
multipart/form-data:
schema:
type: object
properties:
latitude:
description: Latitude of the location
type: number
longitude:
description: Longitude of the location
type: number
horizontal_accuracy:
description: 'The radius of uncertainty for the location, measured in meters; 0-1500'
type: number
required:
- latitude
- longitude
application/json:
schema:
type: object
properties:
latitude:
description: Latitude of the location
type: number
longitude:
description: Longitude of the location
type: number
horizontal_accuracy:
description: 'The radius of uncertainty for the location, measured in meters; 0-1500'
type: number
required:
- latitude
- longitude
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: array
items:
$ref: '#/components/schemas/Chat'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/searchPublicChats:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Searches public chats by looking for specified query in their username and title. Currently only private chats, supergroups and channels can be public. Returns a meaningful number of results. Returns nothing if the length of the searched username prefix is less than 5. Excludes private chats with contacts and chats from the chat list from the results.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
query:
description: Query to search for.
type: string
required:
- query
multipart/form-data:
schema:
type: object
properties:
query:
description: Query to search for.
type: string
required:
- query
application/json:
schema:
type: object
properties:
query:
description: Query to search for.
type: string
required:
- query
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: array
items:
$ref: '#/components/schemas/Chat'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/setPollAnswer:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Changes the user answer to a poll. A poll in quiz mode can be answered only once. Send an empty array of `option_ids` to retract your vote.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Identifier of the message containing the poll.
type: integer
option_ids:
description: 0-based identifiers of answer options, chosen by the user. User can choose more than 1 answer option only is the poll allows multiple answers.
type: array
items:
anyOf:
- type: integer
required:
- chat_id
- message_id
- option_ids
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Identifier of the message containing the poll.
type: integer
option_ids:
description: 0-based identifiers of answer options, chosen by the user. User can choose more than 1 answer option only is the poll allows multiple answers.
type: array
items:
anyOf:
- type: integer
required:
- chat_id
- message_id
- option_ids
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Identifier of the message containing the poll.
type: integer
option_ids:
description: 0-based identifiers of answer options, chosen by the user. User can choose more than 1 answer option only is the poll allows multiple answers.
type: array
items:
anyOf:
- type: integer
required:
- chat_id
- message_id
- option_ids
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
default: true
type: boolean
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/joinChat:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Adds current user as a new member to a chat. Private and secret chats can't be joined using this method. Join either by chat_id or by invite_link
Returns `True` on success.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
invite_link:
description: Invite link to import; should begin with "https://t.me/joinchat/", "https://telegram.me/joinchat/", or "https://telegram.dog/joinchat/".
type: string
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
invite_link:
description: Invite link to import; should begin with "https://t.me/joinchat/", "https://telegram.me/joinchat/", or "https://telegram.dog/joinchat/".
type: string
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
invite_link:
description: Invite link to import; should begin with "https://t.me/joinchat/", "https://telegram.me/joinchat/", or "https://telegram.dog/joinchat/".
type: string
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
default: true
type: boolean
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/addChatMember:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Adds a new member to a chat. Members can't be added to private or secret chats. Returns `true` on success.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
user_id:
description: Unique identifier of the target user
type: integer
required:
- chat_id
- user_id
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
user_id:
description: Unique identifier of the target user
type: integer
required:
- chat_id
- user_id
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
user_id:
description: Unique identifier of the target user
type: integer
required:
- chat_id
- user_id
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
default: true
type: boolean
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/reportChat:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Reports a chat to the Telegram moderators. A chat can be reported only from the chat action bar, or if this is a private chats with a bot, a private chat with a user sharing their location, a supergroup, or a channel, since other chats can't be checked by moderators.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
reason:
description: 'The reason for reporting the chat. Can be one of `child_abuse`, `copyright`, `pornography`, `spam`, `unrelated_location`, `violence` or any custom string to send a custom reason'
type: string
message_ids:
description: Identifiers of reported messages.
type: array
items:
anyOf:
- type: integer
required:
- chat_id
- reason
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
reason:
description: 'The reason for reporting the chat. Can be one of `child_abuse`, `copyright`, `pornography`, `spam`, `unrelated_location`, `violence` or any custom string to send a custom reason'
type: string
message_ids:
description: Identifiers of reported messages.
type: array
items:
anyOf:
- type: integer
required:
- chat_id
- reason
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
reason:
description: 'The reason for reporting the chat. Can be one of `child_abuse`, `copyright`, `pornography`, `spam`, `unrelated_location`, `violence` or any custom string to send a custom reason'
type: string
message_ids:
description: Identifiers of reported messages.
type: array
items:
anyOf:
- type: integer
required:
- chat_id
- reason
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
default: true
type: boolean
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/createChat:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Creates a new group, supergroup or channel. Returns the newly created chat.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
title:
description: Title of the new chat; 1-128 characters.
type: string
type:
description: Type of the new chat, must be any of `group`, `supergroup` or `channel`
type: string
enum:
- group
- supergroup
- channel
user_ids:
description: May only be set for chats of type `group` and is required then. Identifiers of users to be added to the basic group. May not be empty.
type: array
items:
anyOf:
- type: integer
description:
description: Chat description; 0-255 characters. Only for types `supergroup` or `channel`.
type: string
required:
- title
- type
multipart/form-data:
schema:
type: object
properties:
title:
description: Title of the new chat; 1-128 characters.
type: string
type:
description: Type of the new chat, must be any of `group`, `supergroup` or `channel`
type: string
enum:
- group
- supergroup
- channel
user_ids:
description: Must only be set for chats of type `group` and is required then. Identifiers of users to be added to the basic group. May not be empty.
type: array
items:
anyOf:
- type: integer
description:
description: Chat description; 0-255 characters. Only for types `supergroup` or `channel`.
type: string
required:
- title
- type
application/json:
schema:
type: object
properties:
title:
description: Title of the new chat; 1-128 characters.
type: string
type:
description: Type of the new chat, must be any of `group`, `supergroup` or `channel`
type: string
enum:
- group
- supergroup
- channel
user_ids:
description: Must only be set for chats of type `group` and is required then. Identifiers of users to be added to the basic group. May not be empty.
type: array
items:
anyOf:
- type: integer
description:
description: Chat description; 0-255 characters. Only for types `supergroup` or `channel`.
type: string
required:
- title
- type
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
$ref: '#/components/schemas/Chat'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/searchMessages:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Searches for messages in all chats except secret chats. Returns the results in reverse chronological order (i.e., in order of decreasing (date, chat_id, message_id)). For optimal performance the number of returned messages is chosen by the library.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
query:
description: Query to search for.
type: string
offset_date:
description: The date of the message starting from which the results should be fetched. Use 0 or any date in the future to get results from the last message.
type: integer
offset_chat_id:
description: The chat identifier of the last found message, or 0 for the first request.
type: integer
offset_message_id:
description: The chat identifier of the last found message, or 0 for the first request.
type: integer
filter:
description: |-
Filter for message content in the search results. Must be one of `animation`, `audio`, `chat_photo`, `document`, `photo`, `photo_and_video`, `url`, `video`, `video_note`, `voice_and_video_note` or `voice_note`
type: string
enum:
- animation
- audio
- chat_photo
- document
- photo
- photo_and_video
- url
- video
- video_note
- voice_and_video_note
- voice_note
required:
- query
multipart/form-data:
schema:
type: object
properties:
query:
description: Query to search for.
type: string
offset_date:
description: The date of the message starting from which the results should be fetched. Use 0 or any date in the future to get results from the last message.
type: integer
offset_chat_id:
description: The chat identifier of the last found message, or 0 for the first request.
type: integer
offset_message_id:
description: The chat identifier of the last found message, or 0 for the first request.
type: integer
filter:
description: |-
Filter for message content in the search results. Must be one of `animation`, `audio`, `chat_photo`, `document`, `photo`, `photo_and_video`, `url`, `video`, `video_note`, `voice_and_video_note` or `voice_note`
type: string
enum:
- animation
- audio
- chat_photo
- document
- photo
- photo_and_video
- url
- video
- video_note
- voice_and_video_note
- voice_note
required:
- query
application/json:
schema:
type: object
properties:
query:
description: Query to search for.
type: string
offset_date:
description: The date of the message starting from which the results should be fetched. Use 0 or any date in the future to get results from the last message.
type: integer
offset_chat_id:
description: The chat identifier of the last found message, or 0 for the first request.
type: integer
offset_message_id:
description: The chat identifier of the last found message, or 0 for the first request.
type: integer
filter:
description: |-
Filter for message content in the search results. Must be one of `animation`, `audio`, `chat_photo`, `document`, `photo`, `photo_and_video`, `url`, `video`, `video_note`, `voice_and_video_note` or `voice_note`
type: string
enum:
- animation
- audio
- chat_photo
- document
- photo
- photo_and_video
- url
- video
- video_note
- voice_and_video_note
- voice_note
required:
- query
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: array
items:
$ref: '#/components/schemas/Message'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/searchChatMessages:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Searches for messages with given words in the chat. Returns the results in reverse chronological order, i.e. in order of decreasing message_id. For optimal performance the number of returned messages is chosen by the library.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
query:
description: Query to search for.
type: string
from_user_id:
description: If set, only messages sent by the specified sender will be returned
type: integer
from_message_id:
description: Identifier of the message starting from which history must be fetched; use 0 to get results from the last message.
type: integer
filter:
description: |-
Filter for message content in the search results. Must be one of `animation`, `audio`, `call`, `chat_photo`, `document`, `failed_to_send`, `mention`, `missed_call`, `photo`, `photo_and_video`, `pinned`, `unread_mention`, `url`, `video`, `video_note`, `voice_and_video_note` or `voice_note`
type: string
enum:
- animation
- audio
- call
- chat_photo
- document
- failed_to_send
- mention
- missed_call
- photo
- photo_and_video
- pinnedunread_mention
- url
- video
- video_note
- voice_and_video_note
- voice_note
required:
- chat_id
- query
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
query:
description: Query to search for.
type: string
from_user_id:
description: If set, only messages sent by the specified sender will be returned
type: integer
from_message_id:
description: Identifier of the message starting from which history must be fetched; use 0 to get results from the last message.
type: integer
filter:
description: |-
Filter for message content in the search results. Must be one of `animation`, `audio`, `call`, `chat_photo`, `document`, `failed_to_send`, `mention`, `missed_call`, `photo`, `photo_and_video`, `pinned`, `unread_mention`, `url`, `video`, `video_note`, `voice_and_video_note` or `voice_note`
type: string
enum:
- animation
- audio
- call
- chat_photo
- document
- failed_to_send
- mention
- missed_call
- photo
- photo_and_video
- pinnedunread_mention
- url
- video
- video_note
- voice_and_video_note
- voice_note
required:
- chat_id
- query
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target supergroup or channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
query:
description: Query to search for.
type: string
from_user_id:
description: If set, only messages sent by the specified sender will be returned
type: integer
from_message_id:
description: Identifier of the message starting from which history must be fetched; use 0 to get results from the last message.
type: integer
filter:
description: |-
Filter for message content in the search results. Must be one of `animation`, `audio`, `call`, `chat_photo`, `document`, `failed_to_send`, `mention`, `missed_call`, `photo`, `photo_and_video`, `pinned`, `unread_mention`, `url`, `video`, `video_note`, `voice_and_video_note` or `voice_note`
type: string
enum:
- animation
- audio
- call
- chat_photo
- document
- failed_to_send
- mention
- missed_call
- photo
- photo_and_video
- pinnedunread_mention
- url
- video
- video_note
- voice_and_video_note
- voice_note
required:
- chat_id
- query
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: array
items:
$ref: '#/components/schemas/Message'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/getCallbackQueryAnswer:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Sends a callback query to a bot and returns an answer. Returns an error with code 502 if the bot fails to answer the query before the query timeout expires.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Message identifier in the chat specified in *from\_chat\_id*
type: integer
callback_data:
description: Data that was attached to the callback button.
type: string
required:
- chat_id
- message_id
- callback_data
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Message identifier in the chat specified in *from\_chat\_id*
type: integer
callback_data:
description: Data that was attached to the callback button.
type: string
required:
- chat_id
- message_id
- callback_data
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Message identifier in the chat specified in *from\_chat\_id*
type: integer
callback_data:
description: Data that was attached to the callback button.
type: string
required:
- chat_id
- message_id
- callback_data
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
$ref: '#/components/schemas/CallbackQueryAnswer'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/deleteChatHistory:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Deletes all messages in the chat.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
for_everyone:
description: Pass true to try to delete chat history for all users.
type: boolean
remove_from_chat_list:
description: Pass true if the chat should be removed from the chat list.
type: boolean
required:
- chat_id
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
for_everyone:
description: Pass true to try to delete chat history for all users.
type: boolean
remove_from_chat_list:
description: Pass true if the chat should be removed from the chat list.
type: boolean
required:
- chat_id
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
for_everyone:
description: Pass true to try to delete chat history for all users.
type: boolean
remove_from_chat_list:
description: Pass true if the chat should be removed from the chat list.
type: boolean
required:
- chat_id
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
default: true
type: boolean
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/getScheduledMessages:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Returns all scheduled messages in a chat. The messages are returned in a reverse chronological order. Returns an array of `Message` on success.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
required:
- chat_id
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
required:
- chat_id
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
required:
- chat_id
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: array
items:
$ref: '#/components/schemas/Message'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/editMessageScheduling:
post:
tags:
- added
- user-only
description: |-
*ONLY FOR USERS*
Edits the time when a scheduled message will be sent. Scheduling state of all messages in the same album or forwarded together with the message will be also changed. Returns `true` on success.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Message identifier in the chat specified in *from\_chat\_id*. Message IDs for scheduled messages are negative.
type: integer
send_at:
description: 'Must be either a unix timestamp not further than 365 days in the future or `online` as string to send when the other chat participant comes online. Leave empty to send the message instantly'
anyOf:
- type: integer
- type: string
required:
- chat_id
- message_id
multipart/form-data:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Message identifier in the chat specified in *from\_chat\_id*
type: integer
send_at:
description: 'Must be either a unix timestamp not further than 365 days in the future or `online` as string to send when the other chat participant comes online. Leave empty to send the message instantly'
anyOf:
- type: integer
- type: string
required:
- chat_id
- message_id
application/json:
schema:
type: object
properties:
chat_id:
description: Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
anyOf:
- type: integer
- type: string
message_id:
description: Message identifier in the chat specified in *from\_chat\_id*
type: integer
send_at:
description: 'Must be either a unix timestamp not further than 365 days in the future or `online` as string to send when the other chat participant comes online. Leave empty to send the message instantly'
anyOf:
- type: integer
- type: string
required:
- chat_id
- message_id
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
$ref: '#/components/schemas/Message'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/getProxies:
post:
tags:
- added
description: |-
Returns all configured proxies. Requires no parameters.
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
type: array
items:
$ref: '#/components/schemas/Proxy'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/addProxy:
post:
tags:
- added
description: |-
Adds a proxy.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
server:
description: Server hostname or IP address to reach the proxy server.
type: string
port:
description: TCP port where the server is listening for incomming connections.
type: integer
type:
description: Type of proxy to be added. Must be either `mtproto`, `socks5` or `http`. MTProto proxies must provide a `secret` and Socks5/Http proxies can a `username` and `password`.
type: string
username:
description: Username used to authenticate against a Socks5/Http proxy.
type: string
password:
description: Password used to authenticate against a Socks5/Http proxy.
type: string
secret:
description: Secret used to authenticate against an MTProto proxy.
type: string
http_only:
description: Set to true if the proxy only supports HTTP requests (as opposed to transparent TCP connections via HTTP CONNECT).
type: boolean
required:
- server
- port
- type
multipart/form-data:
schema:
type: object
properties:
server:
description: Server hostname or IP address to reach the proxy server.
type: string
port:
description: TCP port where the server is listening for incomming connections.
type: integer
type:
description: Type of proxy to be added. Must be either `mtproto`, `socks5` or `http`. MTProto proxies must provide a `secret` and Socks5/Http proxies can a `username` and `password`.
type: string
username:
description: Username used to authenticate against a Socks5/Http proxy.
type: string
password:
description: Password used to authenticate against a Socks5/Http proxy.
type: string
secret:
description: Secret used to authenticate against an MTProto proxy.
type: string
http_only:
description: Set to true if the proxy only supports HTTP requests (as opposed to transparent TCP connections via HTTP CONNECT).
type: boolean
required:
- server
- port
- type
application/json:
schema:
type: object
properties:
server:
description: Server hostname or IP address to reach the proxy server.
type: string
port:
description: TCP port where the server is listening for incomming connections.
type: integer
type:
description: Type of proxy to be added. Must be either `mtproto`, `socks5` or `http`. MTProto proxies must provide a `secret` and Socks5/Http proxies can a `username` and `password`.
type: string
username:
description: Username used to authenticate against a Socks5/Http proxy.
type: string
password:
description: Password used to authenticate against a Socks5/Http proxy.
type: string
secret:
description: Secret used to authenticate against an MTProto proxy.
type: string
http_only:
description: Set to true if the proxy only supports HTTP requests (as opposed to transparent TCP connections via HTTP CONNECT).
type: boolean
required:
- server
- port
- type
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
$ref: '#/components/schemas/Proxy'
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/deleteProxy:
post:
tags:
- added
description: |-
Deletes a proxy.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
proxy_id:
description: The id that uniquely identifies that proxy server.
type: integer
required:
- proxy_id
multipart/form-data:
schema:
type: object
properties:
proxy_id:
description: The id that uniquely identifies that proxy server.
type: integer
required:
- proxy_id
application/json:
schema:
type: object
properties:
proxy_id:
description: The id that uniquely identifies that proxy server.
type: integer
required:
- proxy_id
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
default: true
type: boolean
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/enableProxy:
post:
tags:
- added
description: |-
Enables the specified proxy. Takes immediate effect.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
proxy_id:
description: The id that uniquely identifies that proxy server.
type: integer
required:
- proxy_id
multipart/form-data:
schema:
type: object
properties:
proxy_id:
description: The id that uniquely identifies that proxy server.
type: integer
required:
- proxy_id
application/json:
schema:
type: object
properties:
proxy_id:
description: The id that uniquely identifies that proxy server.
type: integer
required:
- proxy_id
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
default: true
type: boolean
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/disableProxy:
post:
tags:
- added
description: |-
Disables the specified proxy. Takes immediate effect.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
proxy_id:
description: The id that uniquely identifies that proxy server.
type: integer
required:
- proxy_id
multipart/form-data:
schema:
type: object
properties:
proxy_id:
description: The id that uniquely identifies that proxy server.
type: integer
required:
- proxy_id
application/json:
schema:
type: object
properties:
proxy_id:
description: The id that uniquely identifies that proxy server.
type: integer
required:
- proxy_id
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ok:
default: true
type: boolean
result:
default: true
type: boolean
required:
- ok
- result
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/getUpdates:
post:
description: 'Use this method to receive incoming updates using long polling ([wiki](https://en.wikipedia.org/wiki/Push_technology#Long_polling)). An Array of [Update](https://core.telegram.org/bots/api/#update) objects is returned.'
externalDocs:
url: 'https://core.telegram.org/bots/api/#getupdates'
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties: