Для разработчиков

Bot API

КругСвоих Bot API позволяет создавать ботов, которые работают прямо внутри мессенджера. Боты могут отвечать на сообщения, обрабатывать команды, отправлять фото и файлы, управлять участниками групп и многое другое.

24метода API
5готовых SDK
1 файлбез зависимостей

Быстрый старт

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": "Описание ошибки"
}
GET

getMe

GET /bot/{token}/getMe

Возвращает информацию о текущем боте.

{
  "ok": true,
  "result": {
    "id": "uuid",
    "username": "my_bot",
    "displayName": "My Bot",
    "avatarUrl": null,
    "isBot": true
  }
}
POST

sendMessage

POST /bot/{token}/sendMessage

Отправляет текстовое сообщение в чат.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата-получателя
textstringТекст сообщения. Поддерживается Markdown: **жирный**, *курсив*, ~~зачёркнутый~~, `код`
replyToMessageIdstring (UUID)ID сообщения, на которое ответить
replyMarkupInlineKeyboardMarkupInline-клавиатура под сообщением
# Простое сообщение
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"}
      ]]
    }
  }'
POST

sendPhoto

POST /bot/{token}/sendPhoto

Отправляет фото по URL с необязательной подписью и inline-клавиатурой. Тело запроса — JSON. Для прямой загрузки файла используйте sendPhoto/upload.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
photoUrlstring (URL)Прямая ссылка на изображение
captionstringПодпись к фото
replyMarkupInlineKeyboardMarkupInline-клавиатура
POST

sendPhoto/upload

POST /bot/{token}/sendPhoto/upload

Загружает изображение напрямую с устройства бота — без необходимости хостить файл на стороннем сервере. Тело запроса — multipart/form-data. Разрешены форматы: jpeg, png, gif, webp. Максимальный размер — 50 МБ.

ПараметрТипОбяз.Описание
photofile (form-data)Изображение для отправки
chatIdstring (UUID)ID чата (form-field)
captionstringПодпись (form-field)
POST

sendDocument

POST /bot/{token}/sendDocument

Отправляет файл по URL. Тело запроса — JSON.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
documentUrlstring (URL)Прямая ссылка на файл
fileNamestringИмя файла (с расширением)
captionstringПодпись к файлу
replyMarkupInlineKeyboardMarkupInline-клавиатура
POST

sendDocument/upload

POST /bot/{token}/sendDocument/upload

Загружает файл напрямую с устройства бота — без необходимости хостить файл на стороннем сервере. Тело запроса — multipart/form-data. Запрещены исполняемые форматы: .exe, .sh, .js и т.п. Максимальный размер — 50 МБ.

ПараметрТипОбяз.Описание
documentfile (form-data)Файл для отправки
chatIdstring (UUID)ID чата (form-field)
captionstringПодпись (form-field)
POST

forwardMessage

POST /bot/{token}/forwardMessage

Пересылает сообщение из одного чата в другой.

ПараметрТипОбяз.Описание
fromChatIdstring (UUID)Откуда переслать
messageIdstring (UUID)ID пересылаемого сообщения
toChatIdstring (UUID)Куда переслать
POST

editMessageText

POST /bot/{token}/editMessageText

Редактирует текст ранее отправленного сообщения.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
messageIdstring (UUID)ID сообщения
sentAtstring (ISO 8601)Время отправки сообщения
textstringНовый текст
POST

deleteMessage

POST /bot/{token}/deleteMessage

Удаляет сообщение из чата.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
messageIdstring (UUID)ID сообщения
sentAtstring (ISO 8601)Время отправки сообщения
GET

getChat

GET /bot/{token}/getChat?chat_id={uuid}

Возвращает информацию о чате. Работает через GET с query-параметром или через POST с JSON-телом.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
GET

getChatMembers

GET /bot/{token}/getChatMembers?chat_id={uuid}

Возвращает список участников чата. Бот должен быть участником чата.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
GET

getChatMember

GET /bot/{token}/getChatMember?chat_id={uuid}&user_id={uuid}

Возвращает информацию об одном участнике чата.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
userIdstring (UUID)ID пользователя
POST

banChatMember

POST /bot/{token}/banChatMember

Исключает пользователя из чата. Требует прав администратора.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
userIdstring (UUID)ID пользователя
POST

unbanChatMember

POST /bot/{token}/unbanChatMember

Снимает бан с пользователя.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
userIdstring (UUID)ID пользователя
POST

leaveChat

POST /bot/{token}/leaveChat

Бот покидает чат.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
POST

pinChatMessage

POST /bot/{token}/pinChatMessage

Закрепляет сообщение в чате.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
messageIdstring (UUID)ID закрепляемого сообщения
sentAtstring (ISO 8601)Время отправки сообщения
POST

unpinChatMessage

POST /bot/{token}/unpinChatMessage

Снимает закрепление текущего закреплённого сообщения.

ПараметрТипОбяз.Описание
chatIdstring (UUID)ID чата
GET

getUpdates

GET /bot/{token}/getUpdates

Получает входящие обновления методом long polling. Каждое обновление возвращается один раз — сдвигайте offset после обработки.

ПараметрТипПо умолч.Описание
offsetinteger0Исключить обновления с updateId < offset
limitinteger100Максимум обновлений за запрос (1–100)
timeoutinteger0Секунд ждать обновлений на сервере. 0 = short polling, 20–30 = long polling
💡

Используйте timeout: 20 для long polling — это уменьшит нагрузку и задержку.

POST

setWebhook

POST /bot/{token}/setWebhook

Указывает URL, на который будут приходить обновления. После этого getUpdates перестанет возвращать новые данные.

ПараметрТипОбяз.Описание
urlstring (URL)HTTPS URL для получения обновлений
ℹ️

Сервер будет отправлять POST-запрос на указанный URL при каждом новом обновлении. Тело запроса — объект Update в формате JSON.

POST

deleteWebhook

POST /bot/{token}/deleteWebhook

Удаляет webhook и переключает бота обратно на long polling.

GET

getWebhookInfo

GET /bot/{token}/getWebhookInfo

Возвращает текущий статус webhook.

{
  "ok": true,
  "result": {
    "url": "https://example.com/webhook",
    "pendingUpdateCount": 0
  }
}
POST

setMyCommands

POST /bot/{token}/setMyCommands

Задаёт список команд бота. Команды отображаются в меню при нажатии кнопки «/» в чате с ботом.

ПараметрТипОбяз.Описание
commandsBotCommand[]Массив команд. Каждая: {"command": "/start", "description": "..."}
{
  "commands": [
    { "command": "/start",  "description": "Запустить бота" },
    { "command": "/help",   "description": "Помощь" },
    { "command": "/status", "description": "Статус сервиса" }
  ]
}
GET

getMyCommands

GET /bot/{token}/getMyCommands

Возвращает текущий список команд бота.

POST

answerCallbackQuery

POST /bot/{token}/answerCallbackQuery

Отвечает на нажатие inline-кнопки. Вызывайте этот метод после получения callbackQuery в обновлении.

ПараметрТипОбяз.Описание
callbackQueryIdstringID callback query из обновления
textstringТекст уведомления (показывается пользователю)
showAlertbooleanfalseПоказать как диалог вместо 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-парсер.