Документация Bot API

1. Получение токена

Бот создаётся через @BotFather прямо в клиенте BuryGram:

1. Открой чат с @BotFather.
2. Отправь /newbot.
3. Задай отображаемое имя, затем username (традиционно заканчивается на bot).
4. BotFather вернёт токен вида 123456789:AA...xyz.

Токен - секрет. Не публикуй его и не коммитьте в git; при утечке перевыпусти через BotFather.

2. Авторизация и URL

Токен передаётся в пути запроса:

https://api.bg.buryspb.ru/bot<TOKEN>/<method>

Пример:

curl https://api.bg.buryspb.ru/bot123456789:AA...xyz/getMe

Токен можно передавать и заголовком Authorization: Bearer <TOKEN> (поддерживается наряду с путём).

3. Запросы и ответы

Параметры можно передавать любым из способов:

• строка запроса (query string);
• application/x-www-form-urlencoded;
• application/json;
• multipart/form-data - для загрузки файлов.

Успешный ответ:

{"ok": true, "result": { ... }}

Ошибка:

{"ok": false, "error_code": 400, "description": "CHAT_ID_INVALID"}

4. Получение обновлений: getUpdates

Long polling. Параметры:

curl "https://api.bg.buryspb.ru/bot<TOKEN>/getUpdates?timeout=30"

Если у бота активен вебхук, getUpdates вернёт 409 CONFLICT.

5. Вебхуки

Вместо polling можно получать обновления POST-запросами на твой HTTPS-сервер.

curl -X POST "https://api.bg.buryspb.ru/bot<TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","secret_token":"my-secret"}'

Вебхук и getUpdates взаимоисключающие.

6. Отправка сообщений: sendMessage

curl -X POST "https://api.bg.buryspb.ru/bot<TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":123456789,"text":"<b>Привет</b>","parse_mode":"HTML"}'

Также есть sendRichMessage - расширенный формат сообщений.

7. Медиа

Методы: sendPhoto, sendAnimation, sendAudio, sendDocument, sendLivePhoto, sendSticker, sendVideo, sendVideoNote, sendVoice.

Файл передаётся как multipart/form-data (поле с именем метода, например photo) либо по file_id. Дополнительно: caption, parse_mode, reply_markup, reply_to_message_id.

curl -X POST "https://api.bg.buryspb.ru/bot<TOKEN>/sendPhoto" \
  -F chat_id=123456789 \
  -F photo=@cat.jpg \
  -F caption="Кот"

8. Контакты и геолокация

• sendContact - chat_id, phone_number, first_name, last_name
• sendLocation - chat_id, latitude, longitude
• sendVenue - chat_id, latitude, longitude, title, address

9. Редактирование и удаление

• editMessageText - chat_id, message_id, text, parse_mode, reply_markup
• deleteMessage - chat_id, message_id

10. Инлайн-кнопки и callback

Кнопки задаются в reply_markup:

{"inline_keyboard":[[{"text":"Нажми","callback_data":"btn1"}]]}

При нажатии приходит callback_query; ответьте методом answerCallbackQuery (callback_query_id, text, show_alert, url).

11. Команды бота

• setMyCommands - commands (JSON-массив {"command","description"})
• getMyCommands
• deleteMyCommands

{"commands":[{"command":"start","description":"Запуск"}]}

12. Кнопка меню чата

• setChatMenuButton - chat_id (опционально), menu_button
• getChatMenuButton

13. Файлы

getFile принимает file_id и возвращает file_path. Скачать файл:

https://api.bg.buryspb.ru/file/bot<TOKEN>/<file_path>

14. Web Apps и inline-режим

• answerWebAppQuery - web_app_query_id, result
• savePreparedInlineMessage - user_id, result

15. Premium, звёзды и эмодзи-статус

• giftPremiumSubscription - подарить Premium пользователю
• setUserEmojiStatus - установить эмодзи-статус
• getMyStarBalance - баланс звёзд бота: {"ok":true,"result":{"amount":N}}
• getStarTransactions - история операций (параметры limit, offset): {"ok":true,"result":{"transactions":[…],"next_offset":"…"}}

curl "https://api.bg.buryspb.ru/bot<TOKEN>/getMyStarBalance"
curl "https://api.bg.buryspb.ru/bot<TOKEN>/getStarTransactions?limit=20"

16. Эфемерные сообщения

Нестандартное расширение: сообщения, видимые только получателю (например, в Web App). Используются sendMessage с эфемерной целью и методы:

• editEphemeralMessageText
• editEphemeralMessageMedia
• editEphemeralMessageCaption
• editEphemeralMessageReplyMarkup
• deleteEphemeralMessage

17. Лимиты

18. Примеры

curl - проверка токена:

curl "https://api.bg.buryspb.ru/bot<TOKEN>/getMe"

Python:

import requests

TOKEN = "123456789:AA...xyz"
BASE = "https://api.bg.buryspb.ru/bot" + TOKEN

r = requests.post(BASE + "/sendMessage", json={
    "chat_id": 123456789,
    "text": "Привет из бота!",
})
print(r.json())

Вебхук (Python/Flask, псевдокод):

@app.post("/hook")
def hook():
    upd = request.json
    chat = upd["message"]["chat"]["id"]
    requests.post(BASE + "/sendMessage",
                  json={"chat_id": chat, "text": "Получил!"})
    return {"ok": True}

19. Ошибки

20. Полный список методов

Платёжные методы (sendInvoice, createInvoiceLink, answerPreCheckoutQuery, answerShippingQuery, refundStarPayment, savePreparedKeyboardButton) доступны. sendInvoice/createInvoiceLink создают инвойс и ссылку https://bg.buryspb.ru/pay/<id>; нативная форма оплаты в клиенте пока не подключена (это следующий этап).