API Reference

Public Runtime API

This reference contains only endpoints that an external bot server can call with a kcb_live_… bot token. Base URL: https://chat.wokey.pro/_keychat.

Bot creation and editing, token issuance and rotation, webhook configuration, user installation, callback and inline proxies, and administrative operations are performed by the Key Chat client itself. They are intentionally excluded from the public bot-developer API.

One bot token cannot create or modify other bots, read arbitrary chats, or manage users. Never place a bot token in PWA, browser, or mobile code.

Send or update a message

Authentication: current bot token in Authorization: Bearer kcb_live_…

Posts as the authenticated bot only into a direct or group chat assigned to it. Obtain chat_id from a platform webhook event.

content supports plain text, Markdown, attachments, message buttons, and a dynamic menu. reply_to_event_id creates a reply, while replace_event_id updates an earlier message from the same bot.

Provide a stable idempotency_key for safe retries. Reusing the key returns the original result without creating a duplicate message.

Request body

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

Successful response

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

Possible errors

• 401 — invalid or revoked bot token
• 404 — chat is not available to this bot
• 409 — idempotency_key is already being processed
• 422 — invalid message content
• 503 — messaging transport is temporarily unavailable

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()
});

Upload media

Authentication: current bot token in Authorization: Bearer kcb_live_…

Uploads an image, video, or file before sending a message. Submit multipart/form-data with one file field; one upload is limited to 200 MB.

The response is a media descriptor. Copy it unchanged into content.attachments and add type: image, video, or file. The URL belongs to Key Chat media storage and does not expose the bot token.

Do not substitute arbitrary remote URLs for an upload: the platform must control attachment availability, safety, and lifetime.

Successful response

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

Possible errors

• 400 — file field is missing
• 401 — invalid or revoked bot token
• 413 — file exceeds 200 MB
• 502 — media storage is temporarily unavailable

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 }] }
});