Gambu Bot API

Справочник для разработчиков ботов.

Бот — это особый аккаунт со своим владельцем и статическим токеном. Он живёт в тех же чатах, что и люди: отправляет сообщения и медиа, получает входящие события («апдейты»), рисует кнопки под своими сообщениями и может открывать мини-приложение.

Базовый URL: https://api.gambu.ru/bot/v1

Запросы и ответы — JSON в UTF-8. Пишущие методы — POST с телом, читающие — GET с параметрами в строке запроса.

---

1. Быстрый старт

Пять шагов от пустого места до первого ответа бота. Дальше — вебхук вместо опроса (§7), медиа (§9–10) и кнопки (§13).

Шаг 1. Создайте бота

Боты заводятся прямо в приложении Gambu: профиль → «Мои боты» → создать. Там же живут перевыпуск токена, переключатели поведения и удаление бота.

Имя бота (username) обязано оканчиваться на bot — например weather_bot.

Шаг 2. Сохраните токен

Токен показывается ровно один раз — при создании и при перевыпуске. В базе хранится только его хэш, восстановить потерянный токен нельзя, можно лишь перевыпустить (старый при этом перестаёт работать немедленно).

export TOKEN='bot_aZ12Qw34Er56:xK9...'

Шаг 3. Проверьте токен — getMe

curl -sS -H "Authorization: Bot $TOKEN" https://api.gambu.ru/bot/v1/getMe

Схема авторизации — Bot, не Bearer. Ответ с полями bot_id и username означает, что токен рабочий.

Шаг 4. Заберите входящие — getUpdates

Напишите боту из приложения, затем:

curl -sS -H "Authorization: Bot $TOKEN" \
  "https://api.gambu.ru/bot/v1/getUpdates?offset=0&timeout=25"

В ответе — массив updates. Возьмите из первого апдейта chat_id и update_id.

Шаг 5. Ответьте — sendMessage

curl -sS -X POST https://api.gambu.ru/bot/v1/sendMessage \
  -H "Authorization: Bot $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"chat_id":"<chat_id из апдейта>","text":"Привет!"}'

Следующий вызов getUpdates делайте с offset, равным update_id уже обработанного апдейта: выдача идёт строго «больше offset», и тем же числом апдейты подтверждаются и убираются из очереди.

Готовый цикл на Python — в §20.

---

2. Токен и авторизация

Как создаётся бот

Суффикс bot для бота обязателен и человеку недоступен: значок «BOT» есть только в интерфейсе, а имя уходит в цитаты, упоминания, ссылки /u/<username>, уведомления и журналы — там бота от человека отличает только имя. Пространство имён общее для людей, каналов и ботов: занятое имя повторно не выдаётся.

Один владелец может держать до 20 ботов.

Как устроен токен

Токен выглядит как <bot_id>:<секрет>, например bot_aZ12Qw34Er56:xK9.... Часть до двоеточия — это bot_id, он же идентификатор отправителя в сообщениях бота; он неизменен.

Срока годности у токена нет, автоматической ротации тоже: утёкший токен действует, пока владелец не перевыпустит его вручную («Мои боты» → перевыпуск). Перевыпуск действует немедленно — токены нигде не кэшируются.

Заголовок авторизации

Каждый запрос к /bot/v1/* несёт заголовок:

Authorization: Bot <token>

Именно Bot. Регистр самого слова схемы значения не имеет (Bot, bot), а Bearer не принимается: такой заголовок разбирается как «схемы Bot нет» и даёт 401 missing_token.

Последние две строки важны на практике: 503 означает «проверить не получилось», а не «доступ закрыт». Перевыпускать токен в ответ на них не нужно — нужен повтор с задержкой.

Ограничение владельца

Если владельца бота ограничила модерация, ограничение распространяется и на его ботов: пишущие методы Bot API отвечают 403 account_restricted. Спрашивается мера и владельца, и самого бота.

Читающие методы (getMe, getUpdates, getMyCommands, getWebhookInfo) не ограничиваются. Ответ бота человеку, который сам ограничен, тоже разрешён.

Тело такого отказа шире обычного: кроме error в нём приходят status, until (unix-время окончания), reason (текст для человека) и appeal: "support" — обжалование подаётся через поддержку в приложении.

---

3. Формат ответов

Успешный ответ — JSON, состав зависит от метода. У пишущих методов он обычно выглядит так:

{"ok": true, "message_id": "b3f1...", "created_at": 1758300000}

Ошибка — HTTP-код и тело с машинным кодом причины:

{"error": "not_a_member"}

Общее правило: 4xx — чините запрос, 5xx — повторяйте позже. Коды storage_unavailable и try_later всегда означают «проверить не удалось», а не «нельзя»; правильная реакция на них — повтор с экспоненциальной задержкой.

Полная таблица кодов — §19.

---

4. getMe

GET /bot/v1/getMe

Возвращает карточку самого бота. Единственный способ убедиться, что токен рабочий.

curl -sS -H "Authorization: Bot $TOKEN" https://api.gambu.ru/bot/v1/getMe

{
  "bot_id": "bot_aZ12Qw34Er56",
  "username": "weather_bot",
  "display_name": "Погода",
  "about": "Прогноз по городу"
}

Ошибки — только авторизационные (§2).

---

5. Апдейты

Входящие события лежат в персональной очереди бота. Забрать их можно двумя способами: опросом (getUpdates, §6) или доставкой на ваш URL (вебхук, §7). Вебхук очередь не отменяет — если доставка не удалась, апдейт остаётся в очереди и достаётся опросом.

Формат апдейта

{
  "update_id": 1758300000123456789,
  "type": "message",
  "chat_id": "c1b2...",
  "from_user_id": "u9f8...",
  "message_id": "9c4e...",
  "msg_type": "image",
  "text": "Смотри, что получилось",
  "media_key": "media/9f1c....jpg",
  "thumbnail_url": "thumbs/2ab4....jpg",
  "file_url": "https://storage.yandexcloud.net/...",
  "thumbnail_file_url": "https://storage.yandexcloud.net/...",
  "topic_id": "t_7k2...",
  "created_at": 1758300000
}

Что стоит учесть:

• chat_id — это не from_user_id. Отвечать нужно в чат.
• Ссылки на файлы подписываются на выдаче. Апдейт может пролежать в очереди до 7 суток, поэтому ссылка из старого апдейта уже может не работать.
• topic_id не приходит в callback_query и edited_message. Тема сообщения с кнопкой на пути нажатия не передаётся.

Типы апдейтов

Что приходит в группах

В группе и канале боту пересылаются только команды, а не весь поток сообщений. Это правило постоянное и не отключается.

Командой считается сообщение, начинающееся с / и непробельного символа: /status, /help@weather_bot. Строки / привет и // — обычный текст.

• /cmd без @ получают все боты чата;
• /cmd@username — только названный бот (сравнение без учёта регистра);
• собственные сообщения бот не получает.

Подпись к фото, начинающаяся с /cmd, тоже доходит как команда.

В личном чате пересылается всё: текст, медиа и правки.

Режим «только владелец»

Личный чат с ботом может завести любой, кто нашёл бота поиском, и по умолчанию его сообщения попадают в ту же очередь, что сообщения владельца.

Переключатель «только владелец» живёт в приложении, в карточке бота. Когда он включён, в очередь попадают только сообщения владельца; остальные остаются в чате, бот их просто не получает. Фильтр стоит на входе в очередь, поэтому фильтровать входящие на своей стороне не требуется.

Перевыпуск ссылки на файл: getFile

GET /bot/v1/getFile?chat_id=<id>&message_id=<id>&file_id=<ключ>

Ссылка file_url из апдейта живёт час. Если бот складывает апдейты в свою очередь, разбирает их пачкой или перезапустился и перечитал getUpdates со старого смещения, ссылка успеет истечь, и хранилище ответит 403. getFile подписывает ссылку заново по ключу, который в апдейте есть всегда.

curl -sSG "https://api.gambu.ru/bot/v1/getFile" \
  -H "Authorization: Bot $TOKEN" \
  --data-urlencode "chat_id=c1b2..." \
  --data-urlencode "message_id=9c4e..."

Ответ:

{
  "ok": true,
  "file_id": "media/9f1c....jpg",
  "file_url": "https://storage.yandexcloud.net/...",
  "expires_in": 3600,
  "msg_type": "image"
}

Ссылка адресуется парой «чат + сообщение», а не одним ключом: подписывается только то вложение, которое действительно лежит в указанном сообщении указанного чата, и только если бот в этом чате состоит.

Срок выданной ссылки — тот же час, он приходит явным полем expires_in. Сохранять ссылку по-прежнему не нужно, сохраняйте file_id.

---

6. getUpdates

GET /bot/v1/getUpdates?offset=<int64>&timeout=<секунды>

Длинный опрос очереди. Отдаёт апдейты с update_id строго больше offset.

Размер выдачи фиксирован — 100 апдейтов за вызов; параметра limit нет. Если апдейтов больше, заберите остаток следующим вызовом.

curl -sS -H "Authorization: Bot $TOKEN" \
  "https://api.gambu.ru/bot/v1/getUpdates?offset=$OFFSET&timeout=25"

{"updates": [{"update_id": 1758300000123456789, "type": "message", "...": "..."}]}

Пустой список и отказ чтения — намеренно разные ответы: пустой ответ бот принимает за спокойный чат и следующую попытку делает нескоро.

Апдейты старше 7 суток из очереди удаляются. Основной способ держать очередь короткой — подтверждать обработанное параметром offset; у бота, который не подтверждает ничего, очередь будет возвращать одно и то же.

---

7. Вебхук

Альтернатива опросу: сервис сам делает POST на ваш URL с телом-апдейтом.

setWebhook

POST /bot/v1/setWebhook

{"url": "https://example.com/gambu/hook", "secret": "необязательно"}

Ответ: {"ok": true, "url": "...", "secret": "..."}.

Отказы: 400 invalid_json, 400 invalid_url, 400 secret_too_long, 503 try_later.

deleteWebhook

POST /bot/v1/deleteWebhook — без тела. Снимает вебхук: апдейты снова забираются только опросом.

Ответ {"ok": true}, отказ — 503 try_later.

getWebhookInfo

GET /bot/v1/getWebhookInfo

{"url": "https://example.com/gambu/hook", "has_secret": true}

Сам секрет не отдаётся — он показывается один раз при setWebhook. Отказ — 503 storage_unavailable.

Что приходит на ваш URL

POST, Content-Type: application/json, тело — один апдейт в том же формате, что в getUpdates (включая file_url). Плюс три заголовка:

Доставка считается успешной при любом ответе 2xx. Попыток три, с линейной задержкой (1 с, 2 с), таймаут одной попытки — 8 секунд. Подпись и метка времени пересчитываются на каждую попытку.

Если доставка не удалась, апдейт остаётся в очереди и его можно забрать через getUpdates. Автоматически вебхук при этом не отключается — доставка будет пробоваться и для следующих апдейтов.

Проверка подписи на вашей стороне

Подписываются идентификатор, метка времени и тело — не только тело. Это закрывает и повтор перехваченного запроса, и подмену update_id, по которому вы дедуплицируете. Метка времени защищает, только если вы её проверяете: отбивайте запросы старше 5 минут.

Порядок обязателен: сначала подпись, потом свежесть. До сверки подписи ни метка времени, ни update_id доверия не заслуживают.

import hmac, hashlib, time

def verify(secret: str, sig: str, update_id: str, ts: str, body: bytes) -> int:
    if not sig.startswith("v1="):
        raise ValueError("неизвестная версия подписи")
    want = hmac.new(secret.encode(),
                    f"{int(update_id)}.{int(ts)}.".encode() + body,
                    hashlib.sha256).hexdigest()
    if not hmac.compare_digest(want, sig[3:].lower()):
        raise ValueError("подпись не сходится")
    if abs(time.time() - int(ts)) > 300:      # допуск 5 минут в обе стороны
        raise ValueError("запрос слишком старый")
    return int(update_id)

---

8. sendMessage

POST /bot/v1/sendMessage

{
  "chat_id": "c1b2...",
  "text": "Готово: **отчёт** [по ссылке](https://gambu.ru)",
  "parse_mode": "markdown",
  "topic_id": "t_7k2...",
  "reply_to_message_id": "9c4e...",
  "reply_markup": {"inline_keyboard": [[{"text": "Ещё", "callback_data": "more"}]]}
}

Ответ:

{"ok": true, "message_id": "9c4e...", "created_at": 1758300000, "topic_id": "t_7k2..."}

Поле topic_id в ответе: null, если это личный чат или у чата выключены темы; "general", если темы включены, а сообщение ушло в общую ленту.

Разметка текста: parse_mode

Без поля parse_mode текст уходит как есть. С "parse_mode": "markdown" сервер разбирает подмножество Markdown:

Вложенность работает (**жирный с _курсивом_**, [**жирная ссылка**](https://...)), а внутри моноширинного фрагмента — нет: там всё буквально. Чтобы отправить сам символ разметки, экранируйте его обратным слешем: \*, \_, \[, \\, а также обратный слеш перед обратной кавычкой.

Что важно знать заранее:

• Одиночная * разметкой не считается. В приложениях Gambu *так* — это курсив, а не жирный. Жирный — только **, курсив — только _.
• Ссылки только http и https, без пробелов. Схемы javascript:, data:, mailto:, tel: и адрес без схемы отбиваются: ссылку от бота открывает системный браузер на устройстве человека.
• Отдельного поля entities нет ни в запросе, ни в апдейте — разметка живёт в самом тексте. Отсюда предел: экранированный символ остаётся в тексте обычным символом, и если таких символов окажется пара (\*раз\*), читатель снова увидит в них разметку. Такой запрос отбивается кодом bad_markup.
• Моноширинный фрагмент — однострочный. Перевод строки или обратная кавычка внутри него дают bad_markup.
• Вложенность ограничена восемью уровнями, ссылка внутри ссылки запрещена.
• Ошибка разметки — это 400, а не «отправим как есть». Несбалансированный маркер, пустое содержимое маркера, пустой текст ссылки, адрес с пробелом или недопустимой схемой дают bad_markup; неизвестная схема разбора (html, markdownv2) — bad_parse_mode.

Разметка работает одинаково у sendMessage, у подписей медиа (§10) и у editMessageText (§11) — одним и тем же полем и по тем же правилам.

Отказы

---

9. getUploadURL

POST /bot/v1/getUploadURL

Первый шаг двухшаговой отправки медиа. Ключей к хранилищу у бота нет, поэтому файл он заливает сам по подписанной ссылке, а серверу передаёт только ключ.

{"mime_type": "image/jpeg", "filename": "shot.jpg"}

Ответ:

{
  "key": "media/6f2a....jpg",
  "upload_url": "https://storage.yandexcloud.net/...",
  "thumbnail_key": "thumbs/1c8d....jpg",
  "thumbnail_upload_url": "https://storage.yandexcloud.net/..."
}

Поля thumbnail_* приходят только для image/* и video/*. Превью необязательно, но с ним сообщение выглядит так же, как у человека.

Ссылка на загрузку живёт 15 минут. Файл заливается обычным PUT с телом файла — и только после успешного PUT вызывается метод отправки (§10).

Отказы: 400 invalid_json, 400 missing_mime_type, 503 media_storage_not_configured.

---

10. sendPhoto, sendDocument, sendVideo, sendAudio, sendVoice

Второй шаг отправки медиа: ключ из getUploadURL плюс необязательные подпись и длительность. Все пять методов принимают одно и то же тело.

Отдельного музыкального типа сообщения в Gambu нет: audio — это голосовое, приложения рисуют его плеером с длительностью и складывают во вкладку «Голосовые». Поэтому sendAudio и sendVoice дают одинаковый результат, и выбор между ними ни на что не влияет.

{
  "chat_id": "c1b2...",
  "media_key": "media/6f2a....mp4",
  "thumbnail_key": "thumbs/1c8d....jpg",
  "duration_ms": 12500,
  "caption": "**Отчёт** за сутки",
  "parse_mode": "markdown",
  "topic_id": "t_7k2...",
  "reply_to_message_id": "9c4e...",
  "reply_markup": {"inline_keyboard": [[{"text": "Открыть", "url": "https://example.com"}]]}
}

Ответ — такой же, как у sendMessage.

Отказы — все коды sendMessage, плюс:

Порядок обязателен: сначала PUT файла по upload_url, затем метод отправки. Проверяйте код ответа PUT у себя: сообщение, отправленное с ключом, по которому файл так и не появился, окажется в чате без содержимого.

Про видео стоит знать две вещи:

• Превью можно не присылать. Присланный кадр показывается сразу; если его нет, кадр достраивается фоновой обработкой — той же, что у видео от человека, и до этого момента в ленте будет пустой прямоугольник.
• duration_ms — это подпись под сообщением, а не измеренная длительность файла. Значение не проверяется; присылайте настоящее.

---

11. editMessageText

POST /bot/v1/editMessageText

Меняет текст и/или клавиатуру своего ранее отправленного текстового сообщения. Открытые приложения обновляют его в реальном времени.

{"chat_id": "c1b2...", "message_id": "9c4e...", "text": "Готово", "reply_markup": null}

Ответ:

{"ok": true, "message_id": "9c4e...", "edited_at": 1758300123, "topic_id": null}

Два практических замечания:

• chat_id должен указывать на чат правящегося сообщения. Членство бота в чате при правке не перепроверяется, и запрос с неверным chat_id ответит успехом, не изменив ничего.
• Клавиатура перезаписывается всегда. Если вы правите только текст, а кнопки нужно сохранить, пришлите reply_markup заново.

Лимита частоты у правки нет — он стоит только на отправке.

---

12. deleteMessage

POST /bot/v1/deleteMessage

Убирает своё ранее отправленное сообщение из чата. Служебные реплики («ищу...», одноразовый код, промежуточный результат) незачем оставлять в ленте навсегда, а editMessageText их не убирает — он только меняет текст.

{"chat_id": "c1b2...", "message_id": "9c4e..."}

Ответ:

{"ok": true, "message_id": "9c4e..."}

Повторный вызов на уже удалённом сообщении ошибкой не считается: ответ тот же, плюс "already_deleted": true. Это позволяет просто повторить запрос, если ответ потерялся в сети.

Удалить можно только сообщение самого бота. Роль admin в группе этого не меняет: чужие сообщения удаляются в приложении, а не токеном бота.

Удаление доходит до открытых приложений сразу — и в ленту чата, и в строку списка чатов.

Лимита частоты у удаления нет — он стоит только на отправке.

---

13. Кнопки и answerCallbackQuery

Клавиатуры

Поле reply_markup принимает ровно один из трёх режимов; смешивать их нельзя — иначе 400 invalid_reply_markup.

{"inline_keyboard": [[{"text": "Да", "callback_data": "yes"},
                      {"text": "Сайт", "url": "https://example.com"}]]}

{"keyboard": [[{"text": "Погода"}, {"text": "Курс"}]]}

{"remove_keyboard": true}

Ограничения — нарушение даёт 400 invalid_reply_markup, а не обрезку:

Значение callback_data другим участникам чата не показывается — это приватная нагрузка кнопки.

answerCallbackQuery

POST /bot/v1/answerCallbackQuery

Закрывает нажатие inline-кнопки: показывает нажавшему всплывающее уведомление.

{"callback_query_id": "3f9c...", "text": "Принято", "show_alert": false}

Ответ — всегда {"ok": true}. Истёкший, чужой или уже отвеченный идентификатор тоже даёт ok: метод идемпотентен, повторный вызов безопасен.

Отвечать нужно в течение 5 минут — столько живёт незакрытое нажатие. Незакрытые нажатия не переживают обновление сервиса, поэтому ответ на них безопасно повторять: метод идемпотентен.

Отказы: 400 invalid_json, 400 missing_callback_query_id.

---

14. Темы в группах

Группа с включённым режимом тем — это набор отдельных лент, и каждое сообщение принадлежит одной из них.

• Апдейт message несёт topic_id того сообщения, о котором он. Поля нет — значит это личный чат, группа без тем или общая лента.
• sendMessage и методы отправки медиа принимают необязательный topic_id и возвращают его в ответе: null вне режима тем, "general" — общая лента чата с темами.
• editMessageText тему не меняет. Передать topic_id можно, но только равный текущей теме сообщения (у сообщения в общей ленте — "general"), иначе 400 topic_immutable.
• Тема не приходит в callback_query и edited_message.

Чтобы отвечать туда, откуда пришёл вопрос, просто верните topic_id из апдейта в метод отправки.

Последняя строка — не формальность: «тему проверить не удалось» не равно «темы нет». В этом случае сообщение не отправляется вовсе, потому что молчаливая отправка в общую ленту увела бы ответ мимо адреса, а перенести его потом нечем.

---

15. Бот в группе: роль и права

Бот состоит в группе обычным участником с ролью, и права роли действуют на него так же, как на человека. Если участникам запрещено отправлять медиа или ссылки, бот с ролью member получит 403 not_allowed_media или 403 not_allowed_links. Иначе запрет обходился бы за минуту: достаточно было бы завести бота и отправлять через него.

Для законного случая есть роль admin: владелец чата выдаёт её боту-публикатору (лента, дайджест, оповещения), и ограничения роли member перестают действовать.

Отключение звука и медленный режим к ботам не применяются — их роль играет собственный лимит частоты (§18).

Добавляет бота в группу человек — из приложения, как обычного участника. Методов «вступить в чат» и «выйти из чата» у Bot API нет.

Правило «в группах приходят только команды» (§5) эту дверь не закрывает: оно про то, что бот получает, а не про то, что он отправляет.

---

16. Команды: setMyCommands и getMyCommands

Команды — это метаданные для меню в приложении. Сервер их не интерпретирует: /start и всё остальное доходит до бота обычным апдейтом, логика остаётся на вашей стороне.

setMyCommands

POST /bot/v1/setMyCommands

{"commands": [{"command": "start", "description": "Начать"},
              {"command": "help", "description": "Что я умею"}]}

Метод полностью заменяет список. Пустой массив очищает меню.

Ответ: {"ok": true, "commands": [...]} — нормализованный список.

Отказы: 400 invalid_json, 400 invalid_commands (негодное имя, пустое или слишком длинное описание, больше 100 команд), 500 internal_error.

getMyCommands

GET /bot/v1/getMyCommands → {"commands": [...]}.

Отказ — 503 storage_unavailable.

---

17. Мини-приложения

Мини-приложение — это бот с веб-страницей: приложение Gambu открывает ваш URL во встроенном браузере и передаёт туда подписанную строку initData с личностью пользователя. Формат — стандартная строка запроса с парами «ключ-значение» и полем hash.

Как включить. Владелец задаёт URL своему боту в приложении; по API это POST /v1/bots/:botId/webapp под токеном владельца, тело {"web_app_url": "https://...", "published": true}. URL обязан быть https. Значение published: true выводит мини-приложение в общий каталог.

Что получает ваш фронтенд. Приложение вызывает POST /v1/apps/:username/launch и получает:

{
  "url": "https://example.com/app",
  "init_data": "auth_date=1758300000&hash=...&query_id=...&user=%7B...%7D",
  "expires_in": 86400,
  "bot": {"bot_id": "bot_aZ12...", "username": "shop_bot", "display_name": "Магазин"}
}

Значение init_data — URL-кодированная строка запроса с парами auth_date, query_id, user (компактный JSON: id, first_name, опционально username и photo_url) и hash.

Как проверить initData на своём сервере. Секрет подписи выводится из токена бота:

secret_key    = HMAC_SHA256(key="WebAppData", data=<токен бота>)      # hex
data_check    = пары кроме hash, отсортированные по ключу, "k=v" через "\n"
hash          = hex(HMAC_SHA256(key=<байты secret_key>, data=data_check))

Срок годности initData — 24 часа (auth_date входит в подпись, запас на расхождение часов — 5 минут в будущее). Проверять возраст обязаны вы: подпись без проверки срока — это вечный пропуск, а перехваченная строка открывает мини-приложение от чужого имени. Истёк — приложение запросит запуск заново.

Перевыпуск токена бота меняет и секрет подписи: выданные ранее строки initData перестают сходиться сразу.

Если запуск отвечает 400 webapp_unavailable, у бота ещё нет секрета подписи — так бывает у ботов, созданных до появления мини-приложений. Лечится перевыпуском токена.

Обратный канал. Мини-приложение отправляет боту произвольную строку — она приходит апдейтом type: "web_app_data", где text — сама строка (до 4096 символов), а chat_id — личный чат человека с ботом.

---

18. Лимиты

Лимит частоты считается отдельно для каждого бота.

---

19. Сводная таблица кодов ошибок

---

20. Примеры

curl: отправить сообщение

TOKEN='bot_aZ12Qw34Er56:xK9...'

curl -sS -X POST https://api.gambu.ru/bot/v1/sendMessage \
  -H "Authorization: Bot $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"chat_id":"c1b2...","text":"Привет из curl"}'

curl: отправить картинку

# 1. взять ссылку на загрузку
RESP=$(curl -sS -X POST https://api.gambu.ru/bot/v1/getUploadURL \
  -H "Authorization: Bot $TOKEN" -H 'Content-Type: application/json' \
  -d '{"mime_type":"image/jpeg","filename":"shot.jpg"}')

KEY=$(printf '%s' "$RESP" | python3 -c 'import json,sys;print(json.load(sys.stdin)["key"])')
URL=$(printf '%s' "$RESP" | python3 -c 'import json,sys;print(json.load(sys.stdin)["upload_url"])')

# 2. залить файл прямо в хранилище
curl -sS -X PUT --upload-file shot.jpg "$URL"

# 3. отправить сообщение с этим ключом
curl -sS -X POST https://api.gambu.ru/bot/v1/sendPhoto \
  -H "Authorization: Bot $TOKEN" -H 'Content-Type: application/json' \
  -d "{\"chat_id\":\"c1b2...\",\"media_key\":\"$KEY\",\"caption\":\"Отчёт\"}"

Python: клиент на стандартной библиотеке

import json, urllib.request, urllib.error

BASE = "https://api.gambu.ru/bot/v1"

class Gambu:
    def __init__(self, token: str):
        self.token = token

    def call(self, method: str, payload: dict | None = None, query: str = ""):
        url = f"{BASE}/{method}{query}"
        data = json.dumps(payload).encode() if payload is not None else None
        req = urllib.request.Request(url, data=data, method="POST" if data else "GET")
        req.add_header("Authorization", f"Bot {self.token}")
        if data:
            req.add_header("Content-Type", "application/json")
        try:
            with urllib.request.urlopen(req, timeout=40) as r:
                return json.load(r)
        except urllib.error.HTTPError as e:
            body = json.loads(e.read() or b"{}")
            raise RuntimeError(f"{e.code} {body.get('error', '?')}") from None

Python: эхо-бот

import time

bot = Gambu("bot_aZ12Qw34Er56:xK9...")
offset = 0

while True:
    try:
        res = bot.call("getUpdates", query=f"?offset={offset}&timeout=25")
    except RuntimeError as e:
        print("не удалось забрать апдейты:", e)   # 503 — повторяем, не сдаёмся
        time.sleep(5)
        continue

    for u in res["updates"]:
        offset = u["update_id"]                   # подтверждаем всё до этого номера
        if u["type"] != "message" or not u.get("text"):
            continue
        bot.call("sendMessage", {
            "chat_id": u["chat_id"],
            "text": "Вы написали: " + u["text"],
            # отвечаем в ту же тему, если сообщение пришло из темы
            **({"topic_id": u["topic_id"]} if u.get("topic_id") else {}),
        })

Два неочевидных места в этом цикле:

1. offset двигается на update_id обработанного апдейта, а не на +1 — выдача идёт строго «больше offset».
2. 503 — не повод остановиться. Отказ чтения очереди и пустая очередь приходят разными ответами именно затем, чтобы сбой не был принят за тишину.

---

21. Чего в API нет

Чтобы не искать: перечисленного ниже в Gambu Bot API нет, и ничем из описанного выше это не заменяется.

• Поля entities. Разметка живёт в самом тексте, массива сущностей нет ни в запросе, ни в апдейте. Форматирование при этом есть — parse_mode: "markdown" у отправки, подписей и правки, §8.
• Других схем разбора. HTML и MarkdownV2 не поддерживаются; незнакомое значение parse_mode отбивается кодом bad_parse_mode.
• Остальных маркеров разметки — зачёркнутого, спойлера, блоков кода и цитат: приложения их показывают, но через parse_mode бот их пока не отправляет.
• Пересылки сообщений. Ответ цитатой при этом есть — reply_to_message_id у методов отправки, §8.
• Правки медиа и подписей. Править можно только текст своего текстового сообщения. Удалить своё сообщение при этом можно, §12.
• Параметра limit и выбора типов апдейтов у getUpdates.
• Отправки стикеров, медиагрупп, опросов и геопозиции. Видео, аудио и голосовые при этом есть, §10.
• Собственного идентификатора файла. getFile (§5) перевыпускает ссылку по ключу из апдейта и адресуется парой «чат + сообщение»: отдельный идентификатор, живущий сам по себе, позволял бы подписывать объекты чужих чатов.
• Скачивания файла силами сервиса. getFile отдаёт ссылку, качает бот.
• Управления участниками чата — блокировки, выдачи ролей, карточки чата и карточки участника, вступления в чат и выхода из него.
• Закрепления сообщений, реакций, отметок «прочитано» и индикатора «печатает».
• Апдейтов о том, что бота добавили в чат или удалили из него, а также о реакциях и ответах в опросах.
• Inline-режима и кнопок «поделиться контактом или геопозицией».
• Кнопки запуска мини-приложения внутри reply_markup — мини-приложение открывается из каталога и из карточки бота.

Вопросы по Bot API — support@gambu.ru.