API - Anchos/telegram-platform GitHub Wiki
Any Generic Request
{
"id": 0, // int, message ID, to identify server answers
"action": "XXX" // str, message type
}
Generic error response
{
"id": 123, // int, message ID that triggered the error
"code": 123, // int, error code (much like the standard HTTP error codes)
"desc": "XXX", // str, error description
}
INIT
Start the connection with our server
Request
{
"session_id": "XXX" // optional str, opaque session ID
}
Response
{
"session_id": "XXX", // str, opaque unique session ID, need to store this
"connection_id": "XXX", // str, opaque unique connection ID
"expires_in": 172800 // int, seconds till session expires
}
AUTH
After login button has been pressed and client pressed start in bot
Request
https://t.me/medev_bot?start=${connection_id}
Response
{
"user_id": 123456789, // int, unique user ID
"first_name": "XXX", // str, user's first name from telegram
"username": "@XXX", // str, @-based username from telegram
"language_code": "XXX", // str, 2-chars based lowercase language code
"photo": "XXX" // str, URL to latest user profile photo, can be null
}
LOGOUT
Disassociate the session and telegram user
Request
{
// only common fields
}
Response
{
// empty object in case of success, error message if don't
}
[DEPRICATED] GET_CATEGORIES
Get the list of available categories for channels
Request
{
// only common fields
}
Response
{
"items": [
{
"id": 1, // int, numeric ID of category, used in API requests
"name": "XXX", // str, name of category
}
],
"total": 1, // int, items array length
}
GET_TAGS
Get the list of available tags for channels
Request
{
"name": "XXX", // optional str, get tags starting with this string
"language": "XX", // optional str, 2-chars based language code, if omitted 'ru' is implied
}
Response
{
"items": [
{
"name": "XXX", // str, name of tag
}
],
"total": 1, // int, items array length
}
FETCH_CHANNELS
Get channels list
Request
{
"count": 0, // optional int, limit results array size
"offset": 0, // optional int, paginate over results array
"title": "XXX", // optional str, search substring in channel title, case insensitive
"category_id": 1, // optional int, get channels from some category
"members": [0, 0], // optional array of int, must be .length === 2, get channels with members between arr[0] and arr[1]
"cost": [0, 0], // optional array of int, must be .length === 2, get channels with cost between arr[0] and arr[1]
"likes": [0, 0], // optional array of int, must be .length === 2, get channels with likes between arr[0] and arr[1]
"mut_promo": true, // optional bool, get channels with set/unset mutual promotion flag
"verified": true, // optional bool, get only verified/unverified channels
"partner": true, // optional bool, get channels with currently active/unactive premium status
"language": "XX", // optional str, 2-chars based language code, if omitted 'ru' is implied
"order": "XXX", // optional str, order channels by some field, supported values:
// "+title", "-title" - order by channel title, ascending or descending
// "+members", "-members" (default) - order by channel members count, ascending or descending
// "+likes", "-likes" - order by channel likes, ascending or descending
// "+cost", "-cost" - order by advertisment cost, ascending or descending
}
Response
{
"data": {
"items": [
{
"category_id": 1, // int, channel category ID
"cost": 0, // int, advertisment cost
"description": "XXX", // str, channel description
"id": 0, // int, channel ID
"language": "XX", // str, 2-symbol based lowercase language code, like 'ru'
"members": 0, // int, channel members count
"members_growth": 0, // int, channel members growth
"photo": "XXX", // str, URL to channel's avatar, can be null
"telegram_id": -1, // int, channel's telegram ID
"title": "XXX", // str, channel's title
"username": "@XXX", // str, @-based channel's username ID
"verified": true, // bool, biplane's channel verification status
"views": 0, // int, channel's view statistics
"views_growth": 0, // int, channel's view stats growth
"vip": true, // bool, **DUMMY**, premium channel
"likes": 0, // int, channel likes counter
"mutual_promotion": false, // bool, channel admin wants to participate in mutual promotion
"tags": ["XXX", "XXX2"], // array of str, channel tags
}
], // array of channels
"total": 0, // int, total number of channels that satisfy the filter provided
"max_members": 0, // int, maximum number of members, database wide
"max_cost": 0, // int, maximum advertisment cost, database wide
"max_likes": 0 // int, maximum likes count, database wide
}
}
FETCH_CHANNEL
Get single channel
Request
{
"username": "@XXX" // str, @-based channel username
}
Response
{
"data": {
"category_id": 1, // int, channel category ID
"cost": 0, // int, advertisment cost
"description": "XXX", // str, channel description
"id": 0, // int, channel ID
"language": "XX", // str, 2-symbol based lowercase language code, like 'ru'
"members": 0, // int, channel members count
"members_growth": 0, // int, channel members growth
"photo": "XXX", // str, URL to channel's avatar, can be null
"telegram_id": -1, // int, channel's telegram ID
"title": "XXX", // str, channel's title
"username": "@XXX", // str, @-based channel's username ID
"verified": true, // bool, biplane's channel verification status
"views": 0, // int, channel's view statistics
"views_growth": 0, // int, channel's view stats growth
"vip": true, // bool, **DUMMY**, premium channel
"likes": 0, // int, channel likes counter
"mutual_promotion": false, // bool, channel admin wants to participate in mutual promotion
"tags": ["XXX", "XXX2"], // array of str, channel tags
}
}
VERIFY_CHANNEL
Try to verify channel moderation permissions
Request
{
"username": "@XXX" // str, @-based channel username
}
Response
{
// empty object in case of success, error message if don't
}
UPDATE_CHANNEL
(re-)Fetch channel data from telegram API. If there is no such channel in our base - add it.
Request
{
"username": "@XXX" // str, @-based channel username
}
Response
{
// empty object in case of success, error message if don't
}
LIKE_CHANNEL
Like/Dislike channel. Any user can do this.
Request
{
"username": "@XXX", // str, @-based channel username
"value": true // bool, like or dislike
}
Response
{
// empty object in case of success, error message if don't
}
MODIFY_CHANNEL
Set channel parameters. Only verified channel moderator can do this
Request
{
"username": "@XXX" // str, @-based channel username
"category_id": 1, // optional int, category ID to set
"tags": ["XXX", "XX2"], // optional str, tags array to set, new custom tags also can be defined here
"mut_promo": true, // optional bool, set the mutual_promotion flag for channel
"cost": 0, // optional int, set channel advertisment cost
"language": "XX", // optional str, set channel language (2-symbol based lowercase, like "ru")
"description": "XXXX", // optional str, set channel description
}
Response
{
"data": {
"category_id": 1, // int, channel category ID
"cost": 0, // int, advertisment cost
"description": "XXX", // str, channel description
"id": 0, // int, channel ID
"language": "XX", // str, 2-symbol based lowercase language code, like 'ru'
"members": 0, // int, channel members count
"members_growth": 0, // int, channel members growth
"photo": "XXX", // str, URL to channel's avatar, can be null
"telegram_id": -1, // int, channel's telegram ID
"title": "XXX", // str, channel's title
"username": "@XXX", // str, @-based channel's username ID
"verified": true, // bool, biplane's channel verification status
"views": 0, // int, channel's view statistics
"views_growth": 0, // int, channel's view stats growth
"vip": true, // bool, **DUMMY**, premium channel
"likes": 0, // int, channel likes counter
"mutual_promotion": false, // bool, channel admin wants to participate in mutual promotion
"tags": ["XXX", "XXX2"], // array of str, channel tags
}
}
[Not implemented yet] GET_OFFERS
Get offers that can be purchased for the channel, like "7 days of channel pinned on main page"
Request
{
}
Response
{
"items": [
{
"id": 1, // int, unique offer ID to use in order creation
"price_rub": 3.22, // float, offer price in RUB
"price_usd": 3.22, // float, offer price in USD
"price_eur": 3.22, // float, offer price in EUR
// further fields are related to offer description. It's unlikely that they can be used in frontend
"pin_main_days": 1, // int, pinning on the main page, days
"pin_category_days": 1, // int, pinning on the category page, days
"related_days": 1, // int, show channel as related on other channels page of the same category
// More fields are coming soon
},
]
}
[Not implemented yet] GET_ORDERS
Get orders history for the channel
Request
{
"username": "@XXX", // str, @-based channel username
"count": 0, // optional int, limit results array size
"offset": 0, // optional int, paginate over results array
}
Response
{
"items": [
{
"id": 1, // int, unique order ID
"user": "@XXX", // str, @-based telegram user's id who made a order
"created": "20180920T00:00:00Z", // datetime, UTC timestamp when order was created
"payment": { // payment info, can be null if no payment is made yet
"amount": 3.22, // float, offer price in EUR
"currency": "XXX", // str, 3-chars based currecy code (RUB, EUR, USD)
"status": "XXX", // str, payment status: "processing", "ok" or "fail"
"processed_at": "20180920T00:00:00Z", // datetime, UTC timestamp when payment was processed
},
"offers": {
2: 10, // key - int, offer ID; value - int, offers count
}
},
],
"total": 0, // int, total number of orders for the channel
}
[Not implemented yet] CREATE_ORDER
Create order to purchase something for some channel
Request
{
"username": "@XXX", // str, @-based channel username
"offers": {
2: 1, // key - int, offer ID; value - int, offers count
},
}
Response
{
"data": {
"id": 1, // int, unique order ID, put it to interkassa's form
"user": "@XXX", // str, @-based telegram user's id who made a order
"created": "20180920T00:00:00Z", // datetime, UTC timestamp when order was created
"offers": {
2: 10, // key - int, offer ID; value - int, offers count
}
}
}