Python SDK

KarboAI Bot API

Build bots that interact with users in KarboAI chats via a simple REST API and WebSocket events.

Bots are created through the Developer Panel in the KarboAI app settings. Each bot gets a unique token for authentication. Official bots (paid status) can be added to any chat by its creator; non-official bots can only interact in their owner's chats.

This documentation covers every API endpoint and WebSocket event. You can use any language or HTTP library to build a bot — or use our official Python SDK.

KarboAI Bot API

Создавайте ботов, которые взаимодействуют с пользователями в чатах KarboAI через REST API и WebSocket.

Боты создаются в панели разработчика в настройках приложения KarboAI. Каждый бот получает уникальный токен для аутентификации. Официальные боты (платный статус) могут быть добавлены в любой чат его создателем; неофициальные боты работают только в чатах владельца.

Документация описывает все API-эндпоинты и WebSocket-события. Вы можете использовать любой язык программирования — или наш официальный Python SDK.

Authentication

All API requests must include the Bot-Token header with your bot's token.

Аутентификация

Все API-запросы должны содержать заголовок Bot-Token с токеном вашего бота.

// Every request must include this header
Bot-Token: your_bot_token_here
⚠
Keep your token secret. If compromised, regenerate it in the Developer Panel. Never commit tokens to public repositories.
⚠
Храните токен в секрете. Если он скомпрометирован, перегенерируйте его в панели разработчика. Никогда не публикуйте токены.

Base URL

All REST API endpoints use the following base URL:

Базовый URL

Все REST API эндпоинты используют следующий базовый URL:

https://api.karboai.com

WebSocket connections use:

WebSocket-подключения используют:

wss://api.karboai.com/bot/ws

Rate Limits

Rate limits depend on your bot's status:

Лимиты запросов

Лимиты зависят от статуса вашего бота:

50 / min
Not Official
Неофициальный
45 / sec
Official
Официальный

When rate limited, the server returns 429 Too Many Requests with a Retry-After header (seconds).

При превышении лимита сервер вернёт 429 Too Many Requests с заголовком Retry-After (секунды).

Errors

All errors return a JSON object with an error field:

Ошибки

Все ошибки возвращают JSON-объект с полем error:

{
  "error": "not_in_chat"
}
CodeMeaningЗначениеCommon errorsЧастые ошибки
400Bad requestНеверный запросempty_message, content_too_long, too_many_images
401UnauthorizedНе авторизованbot_token_required, invalid_bot_token
403ForbiddenЗапрещеноbot_banned, not_in_chat, not_helper
404Not foundНе найденоuser_not_found, message_not_found
413File too largeФайл слишком большойfile_too_large
429Rate limitedЛимит превышен—

Endpoints

Эндпоинты

GET /bot/me Get bot info Информация о боте

Returns information about the authenticated bot.

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

ResponseОтвет
{
  "bot_id": "uuid",
  "name": "My Bot",
  "status": "official"  // "not_official" | "official" | "banned"
}
cURL
curl -H "Bot-Token: YOUR_TOKEN" \
  https://api.karboai.com/bot/me
POST /bot/send-message Send a message Отправить сообщение

Send a text message and/or images to a chat. The bot must be a member of the chat.

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

Request bodyТело запроса JSON
FieldПолеTypeТипDescriptionОписание
chat_idstringrequiredобяз. Target chat IDID целевого чата
contentstringoptionalопц. Message text (max 5000 chars). Required if no images.Текст сообщения (макс. 5000 символов). Обязательно, если нет изображений.
reply_message_idstring | nulloptionalопц. Message ID to reply toID сообщения для ответа
imagesstring[] | nulloptionalопц. Array of image URLs (max 10). Get URLs from /bot/upload/imageМассив URL изображений (макс. 10). Получите URL через /bot/upload/image
ResponseОтвет
{
  "message_id": "uuid",
  "created_time": 1712070000
}
cURL
curl -X POST https://api.karboai.com/bot/send-message \
  -H "Bot-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "chat-uuid",
    "content": "Hello from bot!",
    "images": ["https://assets.karboai.com/images/abc123.jpg"]
  }'
POST /bot/upload/image Upload an image Загрузить изображение

Upload an image file. Returns a URL you can use in send-message. Maximum file size: 20 MB. Supported formats: .jpg, .png, .webp, .gif.

Загрузите файл изображения. Возвращает URL для использования в send-message. Максимальный размер: 20 МБ. Форматы: .jpg, .png, .webp, .gif.

RequestЗапрос multipart/form-data
FieldПолеTypeТипDescriptionОписание
filefilerequiredобяз. Image fileФайл изображения
ResponseОтвет
{
  "url": "https://assets.karboai.com/images/abc123def.jpg"
}
cURL
curl -X POST https://api.karboai.com/bot/upload/image \
  -H "Bot-Token: YOUR_TOKEN" \
  -F "file=@photo.jpg"
GET /bot/chat/{chat_id}/message/{message_id} Get a message Получить сообщение

Retrieve a specific message from a chat the bot is in.

Получить конкретное сообщение из чата, в котором бот состоит.

ResponseОтвет
{
  "message_id": "uuid",
  "chat_id": "uuid",
  "user_id": "uuid",
  "content": "Hello!",
  "created_time": 1712070000,
  "type": 0,
  "reply_message_id": null,
  "audio": null,
  "sticker": null,
  "images": ["https://assets.karboai.com/images/..."],
  "author": {
    "user_id": "uuid",
    "nickname": "Username",
    "avatar": "https://..."
  }
}
GET /bot/chat/{chat_id}/members Get chat members Список участников чата

List members of a chat. Supports pagination.

Список участников чата. Поддерживает пагинацию.

Query parametersПараметры запроса
ParamПараметрTypeТипDescriptionОписание
limitintoptionalопц. Max results (default 100, max 200)Макс. результатов (по умолчанию 100, макс. 200)
offsetintoptionalопц. Offset for pagination (default 0)Смещение для пагинации (по умолчанию 0)
ResponseОтвет
{
  "items": [
    {
      "user_id": "uuid",
      "nickname": "Username",
      "avatar": "https://...",
      "role": 0
    }
  ]
}
GET /bot/user/{user_id} Get user profile Профиль пользователя

Get the public profile of any user.

Получить публичный профиль любого пользователя.

ResponseОтвет
{
  "user_id": "uuid",
  "nickname": "Username",
  "avatar": "https://...",
  "short_info": "Bio text",
  "role": 0
}
POST /bot/leave-chat/{chat_id} Leave a chat Покинуть чат

Remove the bot from a chat.

Удалить бота из чата.

ResponseОтвет
{ "ok": true }
POST /bot/chat/{chat_id}/kick Kick a user Кикнуть пользователя

Kick a user from a chat. The bot must have the helper role or be the chat organizer.

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

Request bodyТело запроса JSON
FieldПолеTypeТипDescriptionОписание
user_idstringrequiredобяз. User ID to kickID пользователя для кика
ResponseОтвет
{ "ok": true }

WebSocket — Real-time Events

Bots connect to a dedicated Socket.IO WebSocket server to receive real-time messages from chats they are in.

WebSocket — События в реальном времени

Боты подключаются к отдельному Socket.IO WebSocket-серверу для получения сообщений из чатов, в которых они состоят.

Connection

Подключение

Use a Socket.IO client in any language. Protocol: WebSocket transport only (no polling).

Используйте клиент Socket.IO на любом языке. Протокол: только WebSocket транспорт (без polling).

ParameterПараметрValueЗначение
URLhttps://api.karboai.com
path/bot/ws
transports["websocket"]
auth{"bot_token": "YOUR_TOKEN"}
JavaScript
import { io } from "socket.io-client";

const socket = io("https://api.karboai.com", {
  path: "/bot/ws",
  transports: ["websocket"],
  auth: { bot_token: "YOUR_TOKEN" }
});

socket.on("connect", () => console.log("Connected!"));

socket.on("new_message", (data) => {
  console.log(`[${data.chat_id}] ${data.content}`);
});
Python
import socketio

sio = socketio.AsyncClient()

@sio.on("new_message")
async def on_message(data):
    print(f"[{data['chat_id']}] {data['content']}")

await sio.connect(
    "https://api.karboai.com",
    socketio_path="/bot/ws",
    auth={"bot_token": "YOUR_TOKEN"},
    transports=["websocket"],
)

Events

События

EVENT new_message Incoming chat message Входящее сообщение

Emitted when a message is sent to any chat the bot is in (including messages from the bot itself).

Событие при отправке сообщения в чат, где состоит бот (включая сообщения самого бота).

{
  "chat_id": "uuid",
  "message_id": "uuid",
  "user_id": "uuid",
  "content": "Hello!",
  "created_time": 1712070000,
  "type": 0,
  "reply_message_id": null,
  "images": [],
  "author": {
    "user_id": "uuid",
    "nickname": "Username",
    "avatar_url": "https://..."
  }
}
💡
Filter out your own messages by comparing user_id with your bot's bot_id (from /bot/me).
💡
Фильтруйте свои сообщения, сравнивая user_id с bot_id вашего бота (из /bot/me).

Models

Message

A chat message object.

Модели

Message

Объект сообщения в чате.

FieldПолеTypeТипDescriptionОписание
message_idstringUnique message IDУникальный ID сообщения
chat_idstringChat this message belongs toЧат, которому принадлежит сообщение
user_idstringSender's user IDID отправителя
contentstringMessage textТекст сообщения
created_timeintUnix timestampUnix-время
typeint0 = normal text, other = system0 = обычный текст, иначе = системное
reply_message_idstring?ID of the replied messageID сообщения, на которое ответили
audiostring?Voice message URLURL голосового сообщения
stickerstring?Sticker identifierИдентификатор стикера
imagesstring[]Array of image URLsМассив URL изображений
authorAuthorSender infoИнформация об отправителе

User

FieldПолеTypeТипDescriptionОписание
user_idstringUnique user IDУникальный ID
nicknamestringDisplay nameОтображаемое имя
avatarstringAvatar URLURL аватара
short_infostringBio textОписание профиля
roleintUser role (0 = regular)Роль пользователя (0 = обычный)

Member

Same as User but without short_info.

Как User, но без short_info.

Author

Embedded in message objects.

Вложенный объект в сообщениях.

FieldПолеTypeDescriptionОписание
user_idstringSender IDID отправителя
nicknamestringDisplay nameОтображаемое имя
avatar / avatar_urlstringAvatar URLURL аватара

Official Python SDK

We provide an official Python library karbo that wraps the entire Bot API. Install it from PyPI:

Официальный Python SDK

Мы предоставляем официальную Python-библиотеку karbo, которая покрывает весь Bot API. Установите из PyPI:

pip install karbo
Quick exampleБыстрый пример
import asyncio
import karbo

async def main():
    async with karbo.KarboBot("YOUR_TOKEN") as bot:
        ws = karbo.KarboBotWS("YOUR_TOKEN")

        me = await bot.get_me()
        print(f"Bot: {me.name}")

        @ws.on_message
        async def on_message(msg: karbo.Message):
            if msg.user_id == me.bot_id:
                return
            # Echo text
            await bot.send_message(msg.chat_id, f"Echo: {msg.content}")
            # Send an image
            url = await bot.upload_image("photo.jpg")
            await bot.send_message(msg.chat_id, images=[url])

        await ws.run_forever()

asyncio.run(main())
📚
Building your own SDK in another language? This documentation describes every endpoint and data structure you need. Use the raw HTTP API and Socket.IO protocol described above. We welcome community libraries!
📚
Хотите сделать SDK на другом языке? Эта документация описывает все эндпоинты и структуры данных. Используйте HTTP API и протокол Socket.IO. Мы приветствуем библиотеки от сообщества!
KarboAI KarboAI Bot API Documentation Документация KarboAI Bot API