Key ChatDocs
EnglishРусский
В чат

API Reference

Публичный Runtime API

Этот справочник содержит только endpoint, которые внешний сервер бота может вызывать с токеном вида kcb_live_…. Базовый URL: https://chat.wokey.pro/_keychat.

Создание и редактирование бота, выпуск и ротация токенов, настройка webhook, установка бота пользователем, callback proxy, inline proxy и административные операции выполняются самим интерфейсом Key Chat. Они намеренно не входят в публичный API разработчика бота.

Токен одного бота не может создавать или изменять других ботов, читать произвольные чаты либо управлять пользователями. Никогда не помещайте bot token в PWA, браузерный или мобильный код.

Отправить или обновить сообщение

POST/v1/bot/messages

Авторизация: токен текущего бота в Authorization: Bearer kcb_live_…

Публикует сообщение от имени авторизованного бота только в доступном ему личном или групповом чате. chat_id нужно брать из webhook-события платформы.

content поддерживает обычный текст, Markdown, вложения, кнопки под сообщением и динамическое меню. reply_to_event_id создаёт ответ, а replace_event_id обновляет ранее отправленное сообщение этого же бота.

Для безопасных повторов передавайте стабильный idempotency_key. Повтор с тем же ключом возвращает исходный результат и не создаёт второе сообщение.

Тело запроса

{
  "chat_id": "<chat_uuid>",
  "content": {
    "text": "Готово",
    "format": "markdown",
    "attachments": [],
    "keyboard": {
      "rows": [
        [
          {
            "id": "details",
            "text": "Подробнее",
            "action": {
              "type": "callback",
              "data": "job-42"
            }
          }
        ]
      ]
    }
  },
  "idempotency_key": "job-42-result",
  "reply_to_event_id": null,
  "replace_event_id": null
}

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

{
  "event_id": "$event_id",
  "chat_id": "<chat_uuid>",
  "duplicate": false
}

Возможные ошибки

  • 401 — неверный или отозванный токен бота
  • 404 — чат не доступен этому боту
  • 409 — idempotency_key уже обрабатывается
  • 422 — неверное содержимое сообщения
  • 503 — транспорт сообщений временно недоступен

Примеры использования

import { KeyChatBot, callbackButton } from '@keychat/bots';

const bot = new KeyChatBot(process.env.KEYCHAT_BOT_TOKEN!);
const result = await bot.sendMessage({
  chat_id: chatId,
  content: {
    text: '**Ready**',
    format: 'markdown',
    keyboard: { rows: [[callbackButton('details', 'Details', 'job-42')]] }
  },
  idempotency_key: crypto.randomUUID()
});

Загрузить медиа

POST/v1/bot/media

Авторизация: токен текущего бота в Authorization: Bearer kcb_live_…

Загружает изображение, видео или файл перед отправкой сообщения. Передайте multipart/form-data с единственным полем file; максимальный размер одного файла — 200 МБ.

Ответ содержит media descriptor. Передайте его без изменений в content.attachments и добавьте type: image, video или file. URL принадлежит медиа-хранилищу Key Chat и не раскрывает bot token.

Не используйте произвольные внешние URL вместо загрузки: платформа должна контролировать доступность, безопасность и срок жизни вложения.

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

{
  "url": "mxc://wokey.pro/media_id",
  "name": "photo.jpg",
  "mime_type": "image/jpeg",
  "size": 482013
}

Возможные ошибки

  • 400 — поле file отсутствует
  • 401 — неверный или отозванный токен бота
  • 413 — файл больше 200 МБ
  • 502 — медиа-хранилище временно недоступно

Примеры использования

import { readFile } from 'node:fs/promises';

const bytes = await readFile('photo.jpg');
const media = await bot.uploadMedia(new Blob([bytes], { type: 'image/jpeg' }), 'photo.jpg');
await bot.sendMessage({
  chat_id: chatId,
  content: { attachments: [{ type: 'image', ...media }] }
});
© 2026. Key Chat.