Bot API
КругСвоих Bot API позволяет создавать ботов, которые работают прямо внутри мессенджера. Боты могут отвечать на сообщения, обрабатывать команды, отправлять фото и файлы, управлять участниками групп и многое другое.
Быстрый старт
1. Откройте КругСвоих и найдите @botfatherbot.
2. Отправьте команду /newbot и следуйте инструкциям. Вы получите токен — секретный ключ для управления ботом.
3. Используйте токен для вызова методов API:
# pip install — не нужен, только стандартная библиотека from ks_bot import KSBot bot = KSBot("ВАШ_ТОКЕН") @bot.on_command("start") def on_start(msg): bot.send_message(msg["chatId"], "Привет! Команды: /photo, /doc") @bot.on_command("photo") def on_photo(msg): # Загрузить файл напрямую с диска — без внешнего хостинга bot.upload_photo(msg["chatId"], "banner.png", caption="Вот картинка!") @bot.on_command("doc") def on_doc(msg): bot.upload_document(msg["chatId"], "report.pdf", caption="Отчёт") @bot.on_message def echo(msg): bot.send_message(msg["chatId"], f"Вы написали: {msg['content']}") bot.run_polling()
const { KSBot } = require('./ks_bot'); const fs = require('fs/promises'); const bot = new KSBot('ВАШ_ТОКЕН'); bot.onCommand('start', async (msg) => { await bot.sendMessage(msg.chatId, 'Привет! Команды: /photo, /doc'); }); bot.onCommand('photo', async (msg) => { // Загрузить файл с диска — без внешнего хостинга const data = await fs.readFile('banner.png'); await bot.uploadPhoto(msg.chatId, new Blob([data], { type: 'image/png' }), { caption: 'Вот картинка!' }); }); bot.onCommand('doc', async (msg) => { const data = await fs.readFile('report.pdf'); await bot.uploadDocument(msg.chatId, new Blob([data], { type: 'application/pdf' }), { caption: 'Отчёт' }); }); bot.onMessage(async (msg) => { await bot.sendMessage(msg.chatId, `Вы написали: ${msg.content}`); }); bot.runPolling();
package main import ( "context" "fmt" "log" ksbot "./ks_bot" ) func main() { bot := ksbot.New("ВАШ_ТОКЕН") bot.OnCommand("start", func(msg *ksbot.Message) { bot.SendMessage(context.Background(), msg.ChatID, "Привет! 👋", nil) }) bot.OnMessage(func(msg *ksbot.Message) { bot.SendMessage(context.Background(), msg.ChatID, fmt.Sprintf("Вы написали: %s", msg.Content), nil) }) log.Fatal(bot.RunPolling(context.Background(), 30)) }
using KrugsvoihBot; var bot = new KsBot("ВАШ_ТОКЕН"); bot.OnCommand("start", async msg => await bot.SendMessageAsync(msg.ChatId, "Привет! 👋")); bot.OnMessage(async msg => await bot.SendMessageAsync(msg.ChatId, $"Вы написали: {msg.Content}")); await bot.RunPollingAsync(CancellationToken.None);
import 'ks_bot.dart'; void main() async { final bot = KSBot('ВАШ_ТОКЕН'); bot.onCommand('start', (msg) async { await bot.sendMessage(msg.chatId, 'Привет! 👋'); }); await bot.runPolling(); }
# Получить информацию о боте curl https://v.krugsvoih.ru/bot/ВАШ_ТОКЕН/getMe # Отправить сообщение curl -X POST https://v.krugsvoih.ru/bot/ВАШ_ТОКЕН/sendMessage \ -H "Content-Type: application/json" \ -d '{"chatId":"uuid-чата","text":"Привет!"}' # Отправить фото по URL curl -X POST https://v.krugsvoih.ru/bot/ВАШ_ТОКЕН/sendPhoto \ -H "Content-Type: application/json" \ -d '{"chatId":"uuid-чата","photoUrl":"https://example.com/img.jpg","caption":"Подпись"}' # Загрузить фото с диска напрямую curl -X POST https://v.krugsvoih.ru/bot/ВАШ_ТОКЕН/sendPhoto/upload \ -F "chatId=uuid-чата" \ -F "caption=Подпись" \ -F "photo=@/path/to/image.jpg" # Загрузить файл с диска напрямую curl -X POST https://v.krugsvoih.ru/bot/ВАШ_ТОКЕН/sendDocument/upload \ -F "chatId=uuid-чата" \ -F "document=@/path/to/report.pdf"
Авторизация
Все запросы к Bot API содержат токен прямо в URL:
https://v.krugsvoih.ru/bot/{token}/методТокен выдаётся при создании бота через @botfatherbot. Храните его в секрете — он даёт полный доступ к управлению вашим ботом.
Никогда не публикуйте токен в открытых репозиториях. Если токен скомпрометирован — пересоздайте бота через BotFather.
Формат запросов
Методы, принимающие параметры, ожидают тело запроса в формате JSON с заголовком Content-Type: application/json. Методы без параметров принимают GET-запросы, но также работают с POST.
Все идентификаторы (chatId, messageId, userId) — UUID-строки в формате xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
Даты (sentAt) — строки в формате ISO 8601: 2026-05-12T12:34:56.789Z.
Формат ответов
Все ответы имеют одинаковую обёртку:
{
"ok": true,
"result": { /* данные */ }
}
// При ошибке:
{
"ok": false,
"description": "Описание ошибки"
}
getMe
Возвращает информацию о текущем боте.
{
"ok": true,
"result": {
"id": "uuid",
"username": "my_bot",
"displayName": "My Bot",
"avatarUrl": null,
"isBot": true
}
}sendMessage
Отправляет текстовое сообщение в чат.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата-получателя |
| text | string | ✓ | Текст сообщения. Поддерживается Markdown: **жирный**, *курсив*, ~~зачёркнутый~~, `код` |
| replyToMessageId | string (UUID) | – | ID сообщения, на которое ответить |
| replyMarkup | InlineKeyboardMarkup | – | Inline-клавиатура под сообщением |
# Простое сообщение bot.send_message(chat_id, "Привет, **мир**!") # С inline-клавиатурой markup = KSBot.inline_keyboard( [KSBot.button("✅ Да", callback_data="yes"), KSBot.button("❌ Нет", callback_data="no")], ) bot.send_message(chat_id, "Нравится?", reply_markup=markup)
const markup = KSBot.inlineKeyboard( [KSBot.button('✅ Да', { callbackData: 'yes' }), KSBot.button('❌ Нет', { callbackData: 'no' })], ); await bot.sendMessage(chatId, 'Нравится?', { replyMarkup: markup });
curl -X POST https://v.krugsvoih.ru/bot/TOKEN/sendMessage \ -H "Content-Type: application/json" \ -d '{ "chatId": "uuid-чата", "text": "Привет! **Это жирный текст**", "replyMarkup": { "inlineKeyboard": [[ {"text": "✅ Да", "callbackData": "yes"}, {"text": "❌ Нет", "callbackData": "no"} ]] } }'
sendPhoto
Отправляет фото по URL с необязательной подписью и inline-клавиатурой. Тело запроса — JSON. Для прямой загрузки файла используйте sendPhoto/upload.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
| photoUrl | string (URL) | ✓ | Прямая ссылка на изображение |
| caption | string | – | Подпись к фото |
| replyMarkup | InlineKeyboardMarkup | – | Inline-клавиатура |
sendPhoto/upload
Загружает изображение напрямую с устройства бота — без необходимости хостить файл на стороннем сервере. Тело запроса — multipart/form-data. Разрешены форматы: jpeg, png, gif, webp. Максимальный размер — 50 МБ.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| photo | file (form-data) | ✓ | Изображение для отправки |
| chatId | string (UUID) | ✓ | ID чата (form-field) |
| caption | string | – | Подпись (form-field) |
sendDocument
Отправляет файл по URL. Тело запроса — JSON.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
| documentUrl | string (URL) | ✓ | Прямая ссылка на файл |
| fileName | string | ✓ | Имя файла (с расширением) |
| caption | string | – | Подпись к файлу |
| replyMarkup | InlineKeyboardMarkup | – | Inline-клавиатура |
sendDocument/upload
Загружает файл напрямую с устройства бота — без необходимости хостить файл на стороннем сервере. Тело запроса — multipart/form-data. Запрещены исполняемые форматы: .exe, .sh, .js и т.п. Максимальный размер — 50 МБ.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| document | file (form-data) | ✓ | Файл для отправки |
| chatId | string (UUID) | ✓ | ID чата (form-field) |
| caption | string | – | Подпись (form-field) |
forwardMessage
Пересылает сообщение из одного чата в другой.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| fromChatId | string (UUID) | ✓ | Откуда переслать |
| messageId | string (UUID) | ✓ | ID пересылаемого сообщения |
| toChatId | string (UUID) | ✓ | Куда переслать |
editMessageText
Редактирует текст ранее отправленного сообщения.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
| messageId | string (UUID) | ✓ | ID сообщения |
| sentAt | string (ISO 8601) | ✓ | Время отправки сообщения |
| text | string | ✓ | Новый текст |
deleteMessage
Удаляет сообщение из чата.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
| messageId | string (UUID) | ✓ | ID сообщения |
| sentAt | string (ISO 8601) | ✓ | Время отправки сообщения |
getChat
Возвращает информацию о чате. Работает через GET с query-параметром или через POST с JSON-телом.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
getChatMembers
Возвращает список участников чата. Бот должен быть участником чата.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
getChatMember
Возвращает информацию об одном участнике чата.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
| userId | string (UUID) | ✓ | ID пользователя |
banChatMember
Исключает пользователя из чата. Требует прав администратора.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
| userId | string (UUID) | ✓ | ID пользователя |
unbanChatMember
Снимает бан с пользователя.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
| userId | string (UUID) | ✓ | ID пользователя |
leaveChat
Бот покидает чат.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
pinChatMessage
Закрепляет сообщение в чате.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
| messageId | string (UUID) | ✓ | ID закрепляемого сообщения |
| sentAt | string (ISO 8601) | ✓ | Время отправки сообщения |
unpinChatMessage
Снимает закрепление текущего закреплённого сообщения.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| chatId | string (UUID) | ✓ | ID чата |
getUpdates
Получает входящие обновления методом long polling. Каждое обновление возвращается один раз — сдвигайте offset после обработки.
| Параметр | Тип | По умолч. | Описание |
|---|---|---|---|
| offset | integer | 0 | Исключить обновления с updateId < offset |
| limit | integer | 100 | Максимум обновлений за запрос (1–100) |
| timeout | integer | 0 | Секунд ждать обновлений на сервере. 0 = short polling, 20–30 = long polling |
Используйте timeout: 20 для long polling — это уменьшит нагрузку и задержку.
setWebhook
Указывает URL, на который будут приходить обновления. После этого getUpdates перестанет возвращать новые данные.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| url | string (URL) | ✓ | HTTPS URL для получения обновлений |
Сервер будет отправлять POST-запрос на указанный URL при каждом новом обновлении. Тело запроса — объект Update в формате JSON.
deleteWebhook
Удаляет webhook и переключает бота обратно на long polling.
getWebhookInfo
Возвращает текущий статус webhook.
{
"ok": true,
"result": {
"url": "https://example.com/webhook",
"pendingUpdateCount": 0
}
}setMyCommands
Задаёт список команд бота. Команды отображаются в меню при нажатии кнопки «/» в чате с ботом.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| commands | BotCommand[] | ✓ | Массив команд. Каждая: {"command": "/start", "description": "..."} |
{
"commands": [
{ "command": "/start", "description": "Запустить бота" },
{ "command": "/help", "description": "Помощь" },
{ "command": "/status", "description": "Статус сервиса" }
]
}
getMyCommands
Возвращает текущий список команд бота.
answerCallbackQuery
Отвечает на нажатие inline-кнопки. Вызывайте этот метод после получения callbackQuery в обновлении.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| callbackQueryId | string | ✓ | ID callback query из обновления |
| text | string | – | Текст уведомления (показывается пользователю) |
| showAlert | boolean | false | Показать как диалог вместо toast |
Тип Update
Каждое обновление содержит:
{
"updateId": 42, // уникальный порядковый номер
"type": "message", // "message" | "callbackQuery"
"message": { ... }, // если type = "message"
"callbackQuery": { ... } // если type = "callbackQuery"
}
Тип Message
{
"id": "uuid",
"chatId": "uuid",
"senderId": "uuid",
"senderUsername": "username",
"content": "текст сообщения",
"sentAt": "2026-05-12T12:00:00Z",
"isEdited": false
}
Тип CallbackQuery
{
"id": "string", // передаётся в answerCallbackQuery
"fromUserId": "uuid",
"fromUsername": "username",
"chatId": "uuid",
"messageId": "uuid",
"data": "yes" // callbackData кнопки
}
InlineKeyboardMarkup
Inline-клавиатура — массив рядов кнопок. Каждая кнопка — объект с обязательным text и одним из полей: callbackData или url.
{
"inlineKeyboard": [
// ряд 1
[
{ "text": "✅ Да", "callbackData": "yes" },
{ "text": "❌ Нет", "callbackData": "no" }
],
// ряд 2 — кнопка-ссылка
[
{ "text": "🌐 Сайт", "url": "https://krugsvoih.ru" }
]
]
}
markup = KSBot.inline_keyboard( [# ряд 1 KSBot.button("✅ Да", callback_data="yes"), KSBot.button("❌ Нет", callback_data="no")], [# ряд 2 KSBot.button("🌐 Сайт", url="https://krugsvoih.ru")], ) @bot.on_callback def handle_callback(cb): bot.answer_callback_query(cb["id"], text=f"Вы нажали: {cb['data']}") bot.send_message(cb["chatId"], f"Ваш выбор: **{cb['data']}**")
const markup = KSBot.inlineKeyboard( [KSBot.button('✅ Да', { callbackData: 'yes' }), KSBot.button('❌ Нет', { callbackData: 'no' })], [KSBot.button('🌐 Сайт', { url: 'https://krugsvoih.ru' })], ); bot.onCallback(async (cb) => { await bot.answerCallbackQuery(cb.id, { text: `Вы выбрали: ${cb.data}` }); });
markup := ksbot.NewInlineKeyboard( []ksbot.InlineKeyboardButton{ ksbot.CallbackButton("✅ Да", "yes"), ksbot.CallbackButton("❌ Нет", "no"), }, []ksbot.InlineKeyboardButton{ ksbot.URLButton("🌐 Сайт", "https://krugsvoih.ru"), }, ) bot.OnCallback(func(cb *ksbot.CallbackQuery) { bot.AnswerCallbackQuery(ctx, cb.ID, "Выбрано!", false) })
var markup = KsBot.InlineKeyboard( new[] { KsBot.CallbackButton("✅ Да", "yes"), KsBot.CallbackButton("❌ Нет", "no") }, new[] { KsBot.UrlButton("🌐 Сайт", "https://krugsvoih.ru") } ); bot.OnCallback(async cb => await bot.AnswerCallbackQueryAsync(cb.Id, text: $"Выбрано: {cb.Data}"));
Скачать SDK
Готовые клиенты для самых популярных языков. Каждый SDK — один файл, никаких сторонних зависимостей (кроме стандартной библиотеки).
Хотите SDK на другом языке? Создайте issue или PR на GitHub. Реализовать просто — нужен только HTTP-клиент и JSON-парсер.