Bot API

Формат запросов

Все запросы идут по HTTPS на адрес вида

https://api.clouchat.org/bot<токен>/<метод>

Поддерживаются GET и POST. Параметры передаются в строке запроса или в теле application/x-www-form-urlencoded, application/json или multipart/form-data — последний нужен для загрузки файлов. Имена методов не зависят от регистра.

Ответ — всегда JSON с полем ok:

{"ok": true, "result": {"id": 7000000123, "is_bot": true, "first_name": "Shop", "username": "shop_helper_bot"}}

{"ok": false, "error_code": 400, "description": "Bad Request: chat not found"}

Неизвестный метод отвечает 404. При превышении лимита приходит 429 и parameters.retry_after — через сколько секунд повторить запрос.

Получение апдейтов

getUpdates — длинный опрос с параметрами offset, limit, timeout (до 50 секунд) и allowed_updates. Подтверждайте полученное, передавая offset на единицу больше последнего update_id. Одновременно для бота работает только один опрос.

setWebhook принимает только адрес https:// с доменным именем на портах 443, 80, 88 или 8443. Адреса во внутренних сетях не принимаются. Ваш сервер должен ответить на запрос в течение 15 секунд, иначе доставка будет повторена позже.

Задайте secret_token и сверяйте его в заголовке X-Clouchat-Bot-Api-Secret-Token, чтобы отличать наши запросы от чужих. Библиотеки проверяют его автоматически. Последняя ошибка доставки видна в getWebhookInfo.

Типы апдейтов: message, edited_message, channel_post, edited_channel_post, callback_query, inline_query, chosen_inline_result, my_chat_member, chat_member. Апдейты хранятся 24 часа.

Методы (54)

Методы не из этого списка отвечают 404. Что пока не поддерживается — в разделе Ограничения.

Получение апдейтов

• getUpdates
• setWebhook
• deleteWebhook
• getWebhookInfo

Бот

• getMe
• logOut
• close
• setMyCommands
• getMyCommands
• deleteMyCommands
• setMyName
• getMyName
• setMyDescription
• getMyDescription
• setMyShortDescription
• getMyShortDescription
• setChatMenuButton
• getChatMenuButton

Отправка

• sendMessage
• forwardMessage
• copyMessage
• sendPhoto
• sendVideo
• sendAnimation
• sendAudio
• sendVoice
• sendVideoNote
• sendDocument
• sendSticker
• sendLocation
• sendChatAction

Правка и удаление

• editMessageText
• editMessageCaption
• editMessageReplyMarkup
• deleteMessage
• deleteMessages

Файлы

• getFile

Ответы

• answerCallbackQuery
• answerInlineQuery
• answerWebAppQuery

Чаты и участники

• getChat
• getChatAdministrators
• getChatMember
• getChatMemberCount
• leaveChat
• banChatMember
• unbanChatMember
• restrictChatMember
• promoteChatMember
• pinChatMessage
• unpinChatMessage
• unpinAllChatMessages
• setChatTitle
• setChatDescription

Для совместимости работают и старые имена kickChatMember и getChatMembersCount.

Форматирование

parse_mode принимает HTML, MarkdownV2 и Markdown. Вместо него можно передать готовые entities, а для подписей к медиа — caption_entities.

Клавиатуры и колбэки

reply_markup принимают все методы отправки, copyMessage и методы правки.

• Кнопки под сообщением — callback_data (1–64 байта), url, copy_text, web_app, switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chat. Поле style: primary, danger или success. До 8 кнопок в ряду и 100 всего.
• Клавиатура вместо системной — до 12 кнопок в ряду, request_contact, request_location, web_app, а также remove_keyboard и force_reply.

Правка текста или подписи без reply_markup убирает кнопки. answerCallbackQuery показывает уведомление или окно; url в ответе может открыть только этого же бота. cache_time до часа позволяет повторять ответ без запроса к боту.

Inline-режим

Боту приходит inline_query; на каждый запрос он отвечает один раз через answerInlineQuery в течение 10 секунд.

Поддерживаемые результаты: article; сохранённые photo, gif, mpeg4_gif, video, audio, voice, document и sticker по file_id; location, venue, contact. cache_time по умолчанию 300 секунд, максимум 3600; is_personal кэширует ответ отдельно для каждого пользователя.

Если у результата есть кнопки, отправленное сообщение получает inline_message_id: по нему приходят колбэки, и бот может править это сообщение методами editMessage*.

Группы и каналы

Бот в группе с режимом приватности получает команды, упоминания и ответы на свои сообщения; администраторы и боты без режима приватности — все сообщения. В каналах боты-администраторы получают channel_post.

При изменении собственного статуса бот получает my_chat_member. Бот-администратор, который указал chat_member в allowed_updates, получает изменения других участников.

Каждое действие проверяется правами бота в этом чате. Изменение прав и названия работает в супергруппах и каналах.

Файлы

Загружайте файлы через multipart/form-data или передавайте file_id уже загруженного файла. Отправка по внешнему URL не поддерживается.

getFile возвращает file_path, по которому файл скачивается:

https://api.clouchat.org/file/bot<токен>/<file_path>

Идентификаторы

id пользователей и чатов могут быть больше 2³²: храните их в 64-битных целых числах. id групп и каналов отрицательные. id сообщений уникальны в пределах чата.

Лимиты

Ограничения

• Нет отправки файлов и inline-результатов по URL, thumbnail_url не используется.
• Пока не поддерживаются платежи, игры, наборы стикеров, опросы от ботов, альбомы (sendMediaGroup), editMessageMedia и login_url.
• answerWebAppQuery принимает только article с текстом.
• Мини-приложения открываются только на доменах из настроек бота, мост называется window.Clouchat.WebApp (см. Мини-приложения).