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"
}

Code	Meaning	Значение	Common errors
400	Bad request	Неверный запрос	`empty_message`, `content_too_long`, `too_many_images`
401	Unauthorized	Не авторизован	`bot_token_required`, `invalid_bot_token`
403	Forbidden	Запрещено	`bot_banned`, `not_in_chat`, `not_helper`
404	Not found	Не найдено	`user_not_found`, `message_not_found`
413	File too large	Файл слишком большой	`file_too_large`
429	Rate 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
chat_id	string	requiredобяз. Target chat IDID целевого чата
content	string	optionalопц. Message text (max 5000 chars). Required if no images.Текст сообщения (макс. 5000 символов). Обязательно, если нет изображений.
reply_message_id	string \| null	optionalопц. Message ID to reply toID сообщения для ответа
images	string[] \| null	optionalопц. 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	Описание
file	file	requiredобяз. 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,
   "audio_duration_ms": null,
   "waveform": null,
   "video_note": null,
   "video_note_duration_ms": null,
   "sticker": null,
   "images": ["https://assets.karboai.com/images/..."],
   "transparent": false,
   "bubble_id": "bubble-uuid",
   "bubble_version": 1,
   "reactions": [
    {
      "reaction": "🔥",
      "is_sticker": false,
      "count": 3,
      "me": false
    }
  ],
  "author": {
    "user_id": "uuid",
    "nickname": "Username",
    "avatar_url": "https://...",
    "avatar_frame": {
      "frame_id": "frame-uuid",
      "file": "https://assets.karboai.com/frames/..."
    },
    "role": 0,
    "app_role": 0,
    "panel_color": "#1f2937",
    "level": 12,
    "nickname_color": "#ff7a00",
    "nickname_emoji": "✨",
    "is_api_bot": false
  }
}

GET /bot/chat/{chat_id}/members Get chat members Список участников чата

List members of a chat. Supports pagination.

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

Query parametersПараметры запроса

Param	Параметр	Type
limit	int	optionalопц. Max results (default 100, max 200)Макс. результатов (по умолчанию 100, макс. 200)
offset	int	optionalопц. Offset for pagination (default 0)Смещение для пагинации (по умолчанию 0)
community_id	int	optionalопц. Community ID to resolve member profiles from (nickname, avatar, role, level). If omitted, the chat's own community is used automatically.ID сообщества для получения профилей участников (ник, аватар, роль, уровень). Если не указан, используется сообщество чата автоматически.

ResponseОтвет

{
  "items": [
    {
      "user_id": "uuid",
      "nickname": "Username",
      "avatar_url": "https://...",
      "role": 0,
      "app_role": 0,
      "panel_color": "#1f2937",
      "member_status": "joined",
      "avatar_frame": {
        "frame_id": "frame-uuid",
        "file": "https://assets.karboai.com/frames/..."
      },
      "level": 12,
      "nickname_color": "#ff7a00",
      "nickname_emoji": "✨",
      "is_api_bot": false
    }
  ]
}

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,
  "app_role": 0,
  "panel_color": "#1f2937",
  "level": 12,
  "nickname_color": "#ff7a00",
  "nickname_emoji": "✨",
  "avatar_frame": {
    "frame_id": "frame-uuid",
    "file": "https://assets.karboai.com/frames/..."
  },
  "bubble_id": "bubble-uuid"
}

GET /bot/user/{user_id}/community/{community_id} Get user profile in community Профиль пользователя в сообществе

Get a user's profile within a specific community. Returns community-specific data such as nickname, avatar, role, and level. Falls back to the global profile if the user has no community-specific data. No sensitive data (email, token) is returned.

Получить профиль пользователя в конкретном сообществе. Возвращает данные, специфичные для сообщества: никнейм, аватар, роль, уровень. Если у пользователя нет данных в этом сообществе, возвращается глобальный профиль. Конфиденциальные данные (email, токен) не возвращаются.

Path parametersПараметры пути

Parameter	Параметр	Type	Тип	Description	Описание
user_id	string	Target user UUIDUUID пользователя
community_id	integer	Community IDID сообщества

ResponseОтвет

{
  "user_id": "uuid",
  "community_id": 42,
  "nickname": "CommunityNick",
  "avatar": "https://...",
  "short_info": "Bio text",
  "role": 1,
  "app_role": 0,
  "panel_color": "#1f2937",
  "level": 5,
  "nickname_color": "#ff7a00",
  "nickname_emoji": "✨",
  "avatar_frame": {
    "frame_id": "frame-uuid",
    "file": "https://assets.karboai.com/frames/..."
  },
  "bubble_id": "bubble-uuid"
}

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_id	string	requiredобяз. 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	Значение
URL	`https://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,
  "community_id": 42,
  "reply_message_id": null,
  "audio": null,
  "audio_duration_ms": null,
  "waveform": null,
  "video_note": null,
  "video_note_duration_ms": null,
  "sticker": null,
  "images": [],
  "transparent": false,
  "bubble_id": "bubble-uuid",
  "bubble_version": 1,
  "reactions": [],
  "author": {
    "user_id": "uuid",
    "nickname": "Username",
    "avatar_url": "https://...",
    "avatar_frame": {
      "frame_id": "frame-uuid",
      "file": "https://assets.karboai.com/frames/..."
    },
    "role": 0,
    "app_role": 0,
    "panel_color": "#1f2937",
    "level": 12,
    "nickname_color": "#ff7a00",
    "nickname_emoji": "✨",
    "is_api_bot": false
  }
}

💡

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	Тип
message_id	string	Unique message ID	Уникальный ID сообщения
chat_id	string	Chat this message belongs to	Чат, которому принадлежит сообщение
user_id	string	Sender's user ID	ID отправителя
content	string	Message text	Текст сообщения
created_time	int	Unix timestamp	Unix-время
type	int	`0` = normal text, other = system	`0` = обычный текст, иначе = системное
community_id	int	Community ID of the chat (`0` = global / no community). Only present in WebSocket events.	ID сообщества чата (`0` = глобальный / без сообщества). Присутствует только в WebSocket-событиях.
reply_message_id	string?	ID of the replied message	ID сообщения, на которое ответили
audio	string?	Voice message URL	URL голосового сообщения
audio_duration_ms	int?	Voice message duration in ms	Длительность голосового в мс
waveform	float[]?	Audio waveform data	Данные формы волны аудио
video_note	string?	Video note URL	URL видеозаметки
video_note_duration_ms	int?	Video note duration in ms	Длительность видеозаметки в мс
sticker	string?	Sticker identifier	Идентификатор стикера
images	string[]	Array of image URLs	Массив URL изображений
transparent	bool	Whether message has transparent background	Прозрачный ли фон сообщения
bubble_id	string?	Sender bubble style ID	ID пузыря отправителя
bubble_version	int	Bubble asset version	Версия ассета пузыря
reactions	MessageReaction[]	Aggregated reactions for the message	Агрегированные реакции на сообщение
author	Author	Sender info	Информация об отправителе

User

Field	Поле	Type	Тип
user_id	string	Unique user ID	Уникальный ID
nickname	string	Display name	Отображаемое имя
avatar	string	Avatar URL	URL аватара
short_info	string	Bio text	Описание профиля
role	int	User role (0 = regular)	Роль пользователя (0 = обычный)
app_role	int	Global app role	Глобальная роль в приложении
panel_color	string?	Profile panel color	Цвет панели профиля
level	int	Current user level	Текущий уровень пользователя
nickname_color	string?	Premium nickname color	Премиум-цвет ника
nickname_emoji	string?	Premium nickname emoji	Премиум-эмодзи ника
avatar_frame	AvatarFrame?	Selected avatar frame	Выбранная рамка аватара
bubble_id	string?	Selected bubble ID	ID выбранного пузыря

Member

Chat member object. Similar to User but includes member_status and is_api_bot.

Объект участника чата. Похож на User, но включает member_status и is_api_bot.

Field	Поле	Type	Description
user_id	string	User ID	ID пользователя
nickname	string	Display name	Отображаемое имя
avatar_url	string	Avatar URL	URL аватара
role	int	Community role	Роль в сообществе
app_role	int	Global app role	Глобальная роль
panel_color	string?	Profile panel color	Цвет панели
level	int	User level	Уровень
nickname_color	string?	Premium nickname color	Цвет ника
nickname_emoji	string?	Premium nickname emoji	Эмодзи ника
avatar_frame	AvatarFrame?	Avatar frame	Рамка аватара
member_status	string	"joined" or "invited"	"joined" или "invited"
is_api_bot	bool	Whether this member is an API bot	Является ли участник API-ботом

Author

Embedded in message objects.

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

Field	Поле	Type	Description
user_id	string	Sender ID	ID отправителя
nickname	string	Display name	Отображаемое имя
avatar / avatar_url	string	Avatar URL	URL аватара
avatar_frame	AvatarFrame?	Selected avatar frame	Выбранная рамка аватара
role / app_role	int	Community and app roles	Роль в сообществе и глобальная роль
panel_color	string?	Profile panel color	Цвет панели профиля
level	int	Current level	Текущий уровень
nickname_color	string?	Premium nickname color	Премиум-цвет ника
nickname_emoji	string?	Premium nickname emoji	Премиум-эмодзи ника
is_api_bot	bool	Whether the author is an API bot	Является ли автор API-ботом

AvatarFrame

Compact avatar frame object used by users, members, and message authors.

Компактный объект рамки аватара, используется у пользователей, участников и авторов сообщений.

Field	Поле	Type	Description	Описание
frame_id	string?	Avatar frame ID	ID рамки аватара
file	string?	Frame image URL	URL изображения рамки

MessageReaction

Aggregated reaction entry attached to a message.

Агрегированная реакция, прикреплённая к сообщению.

Field	Поле	Type	Description
reaction	string	Emoji or sticker reaction key	Эмодзи или ключ стикер-реакции
is_sticker	bool	Whether this reaction is a sticker	Является ли реакция стикером
count	int	Total number of this reaction	Общее количество этой реакции
me	bool	Whether the current bot reacted with it	Реагировал ли этим текущий бот

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. Мы приветствуем библиотеки от сообщества!

Known Libraries

If you prefer another language, here are known community packages for the KarboAI Bot API.

Известные библиотеки

Если вам нужен другой язык, вот известные пакеты сообщества для KarboAI Bot API.

NODE karboai Node.js package on npm Пакет Node.js на npm

Package: npmjs.com/package/karboai

Install:

Пакет: npmjs.com/package/karboai

Установка:

npm install karboai

Language/runtime: Node.js

Язык/рантайм: Node.js