Incoming requests (API)

This article documents puzzlebot Incoming requests. If you need it, see also the documentation for Outgoing requests: Outgoing requests (API).

To set up Incoming requests, **generate an API token** (*Bot — Settings — Integrations — Incoming requests*).

Important! Do not confuse it with the bot API key from @BotFather or the bot API key in Max. The API token belongs to the project and works for both the Telegram bot and the Max bot at the same time.

Format

Request format for Telegram:
https://api.puzzlebot.top/?token=API_TOKEN&method=METHOD_NAME&platform=tg

Request format for Max:
https://api.puzzlebot.top/?token=API_TOKEN&method=METHOD_NAME&platform=max

The format differs between messengers only in the platform parameter: its value is "tg" for Telegram and "max" for Max. If the platform parameter is not specified, the default value is "tg".

Request example:
https://api.puzzlebot.top/?token=WOPJL9thftfGtw65NBfVEXEj24qvZ1bj&method=getLinkActivations&link_id=5556&page=1&platform=tg

This request returns the list of users who followed a link (getLinkActivations) with a specific identifier (link_id=5556), limited to the data that fits on the first page (page=1), for the Telegram platform (platform=tg).

In the request URL, substitute the following (without spaces):

API_TOKEN — generated in the Bot Settings on the Integrations tab.
METHOD_NAME — any of the methods (example: getLinkActivations, max.sendMessage, tg.sendMessage) and their parameters (example: link_id and page).
platform — the target platform: tg (Telegram) or max (Max).
If the parameter is not passed, it defaults to tg (this keeps older integrations backward compatible).
If the request is made to a bot or user in Max, passing platform=max is required.

Parameters are passed using the POST or GET method, and the response comes in JSON format.

Important! You can make at most 120 requests per minute.

Response format (JSON) and universal fields:
To specify a chat or resource identifier in puzzlebot methods, use the universal platform_chat_id parameter (tg_chat_id is still supported for Telegram).
In responses, chat and bot identifiers are now returned with the prefix of the corresponding platform (tg_chat_id for Telegram or max_chat_id for Max) and are also duplicated in the universal platform_* fields:

platform_chat_id — the ID of the user/chat/resource on the platform.
platform_bot_id — the ID of the bot on the platform.

Addressing in Max:

To a user's private messages: pass the user ID in the platform_chat_id parameter (platform_chat_id=USER_ID&platform=max).
To a group / channel / resource: pass the group or channel ID in the platform_chat_id parameter (platform_chat_id=RESOURCE_ID&platform=max).
Actions on a group member (ban, status, permissions): pass the group ID in platform_chat_id and the member ID in user_id (platform_chat_id=RESOURCE_ID&user_id=USER_ID&platform=max).

Methods

tg.* — any request from the Telegram Bot API, where * stands for any Telegram Bot API request in the format of the official documentation, for example:

method: tg.unpinAllChatMessages
params:
chat_id - number, Telegram id of chat, bot id for private

success result: ok = true, result = true

Important! You CANNOT send files in multipart/form-data format through the sendPhoto, sendAudio, sendDocument, sendVideo, sendAnimation, sendVoice, sendVideoNote, sendPaidMedia and sendMediaGroup methods! Use the Telegram API and its corresponding methods for that, or pass a file_id / URL.

Max

max.* — any request from the Max API, where * stands for a request from the official Max API documentation, with a parameter format similar to the Telegram Bot API, for example:

method: max.sendMessage
params:
chat_id - number (Max id of chat or user id for private)
text - string (message text)
platform - string ("max")

success result: ok = true, result = Object, error_code = 0, http_code = 200

Available Max methods:

max.sendMessage, max.sendPhoto, max.sendAudio, max.sendDocument, max.sendSticker, max.sendVideo, max.sendLocation, max.sendContact, max.deleteMessage, max.editMessage, max.getMe, max.getChat, max.getMeInChat, max.getVideoInfo, max.getUploadUrl, max.getChats, max.leaveChat, max.setChatTitle, max.setChatPhoto, max.pinChatMessage, max.unpinAllChatMessages, max.sendChatAction, max.banChatMember, max.promoteChatMember, max.demoteChatMember, max.getChatMember, max.addChatMember, max.getChatAdministrators, max.setWebhook, max.deleteWebhook, max.getMessage, max.answerCallbackQuery, max.sendVideoNote, max.sendMediaGroup, max.sendVoice, max.sendAnimation, max.forwardMessage

System

Help (lists the available methods):
method: help
params: no

success result: code = 0, data = Array of all API methods
Test:
method: test
params: no

success result: code = 0, data = test text with your request params

General puzzlebot methods

Moderation

Get the list of users:
method: getUsersInChat
params:
    platform_chat_id - number, Telegram/Max id of chat, bot id for private
    page - number, page number starts with 1, a page have max 200 rows
    category_id - number, id of category for filter users, optional param
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = Array of users [user_id, first_name, last_name, username]
Get user information:
method: getUserInChatStatus
params:
    user_id - number, id of user
    platform_chat_id - number, Telegram/Max id of chat, bot id for private
    page - number, page number starts with 1, a page have max 50 rows
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = Object[user_id, platform_chat_id, first_name, last_name, username, joined (1 = joined, 0 = left, 2 = banned), joined_date, left_date, ban_date, categories - Array of categories ids]
Block a user (ban):
method: userBan
params:
    platform_chat_id - number, Telegram/Max id of chat
    user_id - number, id of user
    until_date - number, timestamp of end ban date, optional param
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"
Unblock a user (unban):
method: userUnban
params:
    platform_chat_id - number, Telegram/Max id of chat
    user_id - number, id of user
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"

Posting

Get the list of sent posts:
method: getPostsList
params:
page - number, page number starts with 1, a page have max 50 rows
platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = Array of posts [id, date_sent]
Send a post:
method: postSend
params:
    chats_ids - array of platform_chat_ids with separator "," (without quotes), "private" for send to all private chats
    categories_ids - array of categories ids with separator "," (without quotes) for filter users in private chats
    type - "message" (for send text message) | "media" (for send video / photo / audio) | "only_command" (for send command from post actions)
    file_id - string, file id from Telegram/Max for media type
    text - string, text of message for message type or caption for media type
    pin_post - boolean, pin post after send if it's true, false by default
    command_name - text, attach command to the post, no by default
    date - string, date in UTC format (19.04.2024 20:30 or 2024-04-19 20:30) or timestamp
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"
Delete a sent post:
method: postDelete
params:
post_id - number, post_id for delete

success result: code = 0, data = "ok"

Scenarios

Get the list of scenarios:
method: getScenariosList
params:
page - number, page number starts with 1, a page have max 50 rows
platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = Array of scenarios [id, name]
Change the state of scenarios for a user:
method: scenariosChange
params:
    user_id - number, id of user
    scenarios - JSON encoded Array[scenario_id : state (0 - for stop, 1 - for start)]
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"
Start a scenario for a user:
method: scenarioRun
params:
    user_id - number, id of user
    scenario_id - number, id of scenario
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"
Stop a scenario for a user:
method: scenarioStop
params:
    user_id - number, id of user
    scenario_id - number, id of scenario
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"

Entry

Get the list of links:
method: getLinksList
params:
page - number, page number starts with 1, a page have max 50 rows
platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = Array of links [id, name, type, variable, max_activations, max_links, enabled]
Get the list of users for a specific link:
method: getLinkActivations
params:
    link_id - number, id of link
    page - number, page number starts with 1, a page have max 50 rows
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = Array of links activations [link_id, link_key, link_owner_tg_user_id, user_id, date]

Variables

Change a variable:
method: variableChange
params:
    variable - string, name of variable
    expression - string, expression for calc value
    user_id - number, id of user for change personal variable (optional)
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"
Get a variable value:
method: getVariableValue
params:
    variable - string, name of variable
    user_id - number, id of user for get personal variable value (optional)
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "Variable value"
Clear a variable:
method: variableClear
params:
    variable - string, name of variable
    user_id - number, id of user for change personal variable (optional)
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"

Google Sheets

Get the contents of a Google Sheets spreadsheet as JSON (connected accounts only):
method: getSpreadSheetRows
params:
    spreadsheet_id - string, id of spreadsheet
    email - string, email for request
    sheets_ids - string, ids of sheets with separator "," (without quotes) (default no set, get all sheets)
    get_rows_cache_time - number, cache time of rows in seconds (default 5, max 86400)
    get_sheets_cache_time - number, cache time of sheets in seconds (default 5, max 86400)

success result: code = 0, data = Array of spreadsheets objects [sheet_id, sheet_title, rows]

Store 2.0

Get the list of products:
method: getShop2ItemsList
params:
page - number, page number starts with 1, a page have max 50 rows

success result: code = 0, data = Array of items [id, name, article, count_left]
Change product stock:
method: shop2ItemChangeCountLeft
params:
item_id - number, id of shop item
count_left - number, new count left for item (-1 for infinity)

success result: code = 0, data = "ok"

Store (old version)

Get the list of products:
method: getShopItemsList
params:
page - number, page number starts with 1, a page have max 50 rows

success result: code = 0, data = Array of items [id, name, article, count_left]
Change product stock:
method: shopItemChangeCountLeft
params:
item_id - number, id of shop item
count_left - number, new count left for item (-1 for infinity)

success result: code = 0, data = "ok"

Bots only

Connect a bot:
method: botConnect
params: no
success result: code = 0, data = "ok"
Disconnect a bot:
method: botDisconnect
params: no
success result: code = 0, data = "ok"
Enable a bot:
method: botEnable
params: no
success result: code = 0, data = "ok"
Disable a bot:
method: botDisable
params: no
success result: code = 0, data = "ok"
Get the list of chats:
method: getChatsList
params: no
success result: code = 0, data = Array of chats [chat_id, platform_chat_id, tg_chat_id, max_chat_id, title, description, type]
Download a file:
method: downloadFile
params:
file_id - string, Telegram/Max id of file to download
platform - string, optional (required for Max: "max", default: "tg")

success result: Output file with "Content-Type: application/octet-stream"

Constructor

Get the list of commands and conditions:
method: getCommandsList
params: no
success result: code = 0, data = Array of commands [id, name, group_id]
Get the list of command groups:
method: getCommandsGroupsList
params: no
success result: code = 0, data = Array of commands groups [id, name]
Send a command or condition:
method: sendCommand
params:
    command_name - string, name of command or condition
    platform_chat_id - number, Telegram/Max id of resource or user
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"

Dialogs

Start a dialog:
method: dialogStart
params:
user_id - number, id of user
platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"
End a dialog:
method: dialogEnd
params:
user_id - number, id of user
platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"

Resources only

Approve a request to join a resource:
method: joinRequestApprove
params:
    user_id - number, id of user
    platform_chat_id - number, Telegram/Max id of resource
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"
Decline a request to join a resource:
method: joinRequestDecline
params:
    user_id - number, id of user
    platform_chat_id - number, Telegram/Max id of resource
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"
Remove a user (kick):
method: userKick
params:
    platform_chat_id - number, Telegram/Max id of chat
    user_id - number, id of user
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"

Triggers (groups only)

Get the list of triggers:
method: getTriggersList
params:
page - number, page number starts with 1, a page have max 50 rows
platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = Array of triggers [id, platform_chat_id, name, enabled]
Send a trigger:
method: triggerSend
params:
    trigger_id - number, id of trigger
    user_id - number, id of user
    platform - string, optional (required for Max: "max", default: "tg")

success result: code = 0, data = "ok"

Errors

code = 1 — Wrong token format!
code = 2 — Wrong method format!
code = 3 — Token not found!
code = 4 — Unknown method!
code = 40 — No platform_chat_id / tg_chat_id param! | No user_id param!
code = 50 — Set webhook error!
code = 51 — Delete webhook error!
code = 100 — Internal error!
code = 102 — Variable evaluate exception!
code = 104 — Variable not found!
code = 200 — Command / condition not found!
code = 201 — User not found!
code = 202 — Chat not found!
code = 203 — User in chat not found!
code = 204 — Post not found!
code = 205 — Post is not sent!
code = 207 — Trigger not found!
code = 208 — Can't approve join request!
code = 209 — Can't decline join request!
code = 210 — Category not found!
code = 211 — Unknown type of post!
code = 212 — Empty chats!
code = 429 — Too many queries per minute! / Too many queries per month!