Введение

Introduction

Создание бота

Creating a bot

Авторизация

Authorization

Запросы и ответы

Requests & responses

Успех:

Success:

{ "ok": true, "result": { ... } }

Ошибка:

Error:

{ "ok": false, "error_code": 400, "description": "chat_id is required" }

Methods

getMe

Базовая информация о боте. Без параметров.

Basic info about the bot. No parameters.

$ curl https://ix.x2chat.com/api/v1/bot123456789:AAEh…/getMe

{
  "ok": true,
  "result": {
    "id": "uuid",
    "is_bot": true,
    "username": "my_cool_bot",
    "first_name": "My Cool Bot",
    "can_join_groups": true,
    "can_read_all_group_messages": false,
    "supports_inline_queries": false
  }
}

sendMessage

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

Send a text message to a chat. The bot must be a member of the chat.

$ curl -X POST https://ix.x2chat.com/api/v1/bot<TOKEN>/sendMessage \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": 488,
      "text": "Привет! Я бот.",
      "reply_markup": {
        "inline_keyboard": [[
          {"text": "Yes", "callback_data": "yes"},
          {"text": "No",  "callback_data": "no"}
        ]]
      }
    }'

sendPhoto

Отправить картинку в чат (png/jpeg/gif/webp, до 10 МБ). Получатели видят её сразу — как обычное фото в чате.

Send an image to a chat (png/jpeg/gif/webp, up to 10 MB). Recipients see it instantly, like a regular photo.

Ответ: photo: [{file_id, file_size, width, height}] — file_id можно переиспользовать в следующих sendPhoto без повторной загрузки.

Response: photo: [{file_id, file_size, width, height}] — reuse file_id in later sendPhoto calls without re-uploading.

$ curl -X POST https://ix.x2chat.com/api/v1/bot<TOKEN>/sendPhoto \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": 488,
      "photo": "https://example.com/scene.webp",
      "caption": "Маяк в тумане"
    }'

sendChatAction

Показать участникам чата «<имя бота> печатает…». Индикатор гаснет через ~3 с — повторяйте вызов, пока бот готовит ответ.

Show "<bot name> is typing…" to chat members. The indicator fades after ~3 s — repeat the call while the bot prepares its reply.

editMessageText

Заменить текст уже отправленного сообщения.

Replace text of an already-sent message.

{ "chat_id": 488, "message_id": "<uuid>", "text": "Обновлённый текст" }

deleteMessage

{ "chat_id": 488, "message_id": "<uuid>" }

forwardMessage

Бот должен быть участником обоих чатов.

Bot must be a member of both chats.

{ "chat_id": 488, "from_chat_id": 476, "message_id": "<uuid>" }

getUpdates

Long-polling: получить новые updates. Используйте если не настроили webhook.

Long polling: receive new updates. Use this if no webhook is set.

{
  "ok": true,
  "result": [
    { "update_id": 1, "message": { ... } },
    { "update_id": 2, "callback_query": { ... } }
  ]
}

setWebhook

Зарегистрировать URL, на который X2Chat будет POST'ить updates. После регистрации webhook — getUpdates перестаёт получать новые updates.

Register a URL to which X2Chat will POST updates. Once a webhook is set, getUpdates will no longer return new updates.

{
  "url": "https://your-server.com/x2chat-webhook",
  "secret_token": "random_secret_for_x_telegram_header",
  "allowed_updates": ["message", "callback_query"],
  "max_connections": 40
}

setMyCommands

{
  "commands": [
    { "command": "start", "description": "Начать работу" },
    { "command": "help",  "description": "Справка" }
  ]
}

answerCallbackQuery

Подтвердить нажатие на InlineKeyboard-кнопку. text покажется как тост или alert у пользователя.

Acknowledge a tap on an InlineKeyboard button. text is shown as toast or alert to the user.

{
  "callback_query_id": "<id>",
  "text": "Спасибо за ответ!",
  "show_alert": false,
  "effect": "confetti"
}

effect (необязательно): haptic · sound · confetti · shake — отклик на нажатие, клиент воспроизводит его при получении ответа. Неизвестное значение игнорируется.

effect (optional): haptic · sound · confetti · shake — tap feedback played by the client. Unknown values are ignored.

editMessageReplyMarkup

Заменить или убрать клавиатуру у своего сообщения. Без reply_markup (или null) — клавиатура удаляется, старые кнопки перестают быть кликабельными. Все устройства получают обновление сразу. Персонаж и оформление пузыря сохраняются.

Replace or remove the keyboard of your own message. Omitting reply_markup (or null) removes it so stale buttons stop working. All devices update live. Persona and bubble styling are kept.

{
  "chat_id": 123,
  "message_id": "<uuid>",
  "reply_markup": { "inline_keyboard": [[{ "text": "Дальше", "callback_data": "next", "style": "primary" }]] }
}

editMessageText тоже принимает reply_markup, as, bubble; если поле не передано — остаётся прежним (клавиатура не снимается). Редактировать можно только сообщения этого бота.

editMessageText also accepts reply_markup, as, bubble; omitted fields stay unchanged (the keyboard is not removed). Only this bot's own messages can be edited.

setMyTheme · getMyTheme · deleteMyTheme

Тема всего чата с ботом: акцент, фон (цвет, картинка https или градиент из 2–3 цветов), пузыри, кнопки по умолчанию. Не чаще 1 раза в минуту (иначе 429 с parameters.retry_after). getMyTheme возвращает сохранённую тему (или null), deleteMyTheme возвращает тему приложения. Пока хранилище темы не включено на сервере, методы отвечают 503.

Theme for the whole chat with the bot: accent, background (color, https image or 2–3 color gradient), bubbles, default buttons. At most once per minute (otherwise 429 with parameters.retry_after). getMyTheme returns the stored theme (or null), deleteMyTheme restores the app theme. Until theme storage is enabled on the server these methods return 503.

{
  "theme": {
    "accent": "#1E88E5",
    "background": { "gradient": ["#0D1B2A", "#1B263B"] },
    "bubble": { "color": "#1B263B", "text_color": "#E0E1DD" },
    "button_defaults": { "style": "secondary", "shape": "pill" }
  }
}

setMyDescription · setMyShortDescription · getMyDescription · getMyShortDescription

{"description": "…"} (≤ 512) — текст в пустом чате и в профиле бота; {"short_description": "…"} (≤ 120) — «о боте». Пустое значение очищает.

{"description": "…"} (≤ 512) — shown in an empty chat and the bot profile; {"short_description": "…"} (≤ 120) — the "about" line. Empty value clears it.

setMyStartButton · getMyStartButton

Пользователю не нужно набирать /start. Пока он ничего не написал боту, вместо поля ввода приложение показывает большую кнопку; тап отправляет /start (или /start <payload>) обычным сообщением — бот получает его как набранный текст. text ≤ 32 (по умолчанию «Начать» на языке пользователя), payload — до 64 символов A-Z a-z 0-9 _ -. null — сброс.

Users never type /start. Until they send anything, the app shows a big button instead of the composer; a tap sends /start (or /start <payload>) as a normal message — the bot receives it exactly like typed text. text ≤ 32 (default: localized "Start"), payload — up to 64 of A-Z a-z 0-9 _ -. null resets.

{ "start_button": { "text": "Начать квест", "payload": "lighthouse" } }

Меню команд: рядом с полем ввода кнопка «Меню» со списком из setMyCommands (описания на языке пользователя — передайте language_code на верхнем уровне, как в Telegram); тап отправляет команду сообщением.

Commands menu: a "Menu" button next to the composer lists setMyCommands entries (descriptions in the user's language — pass top-level language_code, as in Telegram); a tap sends the command as a message.

setMyMenu · getMyMenu · deleteMyMenu

Своё меню бота вместо простого списка команд и быстрые кнопки у поля ввода (composer_buttons, до 6). Пункт: id, text ≤ 48, description ≤ 96, icon, style/цвета (контраст исправляется), action. Действия: command (отправить /команду), text (отправить текст), callback (callback_query боту с message: null и source: "menu"; принимается, только если data есть в сохранённом меню), url и web_app (только https), submenu, share. До 50 пунктов, вложенность до 3. Варианты по scope ("default" или {"type":"chat","chat_id":…}) и language_code. getMyMenu/deleteMyMenu принимают те же scope/language_code. Пока хранилище меню не включено на сервере — 503.

A custom bot menu instead of the plain commands list, plus quick buttons by the composer (composer_buttons, up to 6). Item: id, text ≤ 48, description ≤ 96, icon, style/colors (contrast auto-corrected), action. Actions: command (send /command), text (send text), callback (callback_query to the bot with message: null and source: "menu"; accepted only if data exists in the saved menu), url and web_app (https only), submenu, share. Up to 50 items, depth up to 3. Variants by scope ("default" or {"type":"chat","chat_id":…}) and language_code. getMyMenu/deleteMyMenu take the same scope/language_code. Until menu storage is enabled on the server — 503.

{
  "language_code": "ru",
  "menu": {
    "button": { "text": "Квест", "icon": { "emoji": "🧭" } },
    "layout": { "type": "grid", "columns": 2 },
    "items": [
      { "id": "restart", "text": "Начать заново", "action": { "type": "command", "command": "restart" } },
      { "id": "inv", "text": "Инвентарь", "action": { "type": "callback", "data": "inv" } }
    ]
  },
  "composer_buttons": [
    { "text": "Осмотреться", "action": { "type": "text", "text": "Осмотреться" } }
  ]
}

Типы updates

Update types

Inline-клавиатура

Inline keyboard

{
  "inline_keyboard": [
    [
      { "text": "👍 Like",    "callback_data": "like" },
      { "text": "👎 Dislike", "callback_data": "dislike" }
    ],
    [
      { "text": "📝 Open page", "url": "https://example.com" }
    ]
  ]
}

Поля кнопки:

Button fields:

Команды

Commands

Examples

Node.js

import fetch from 'node-fetch';

const TOKEN = '123456789:AAEh…';
const BASE = `https://ix.x2chat.com/api/v1/bot${TOKEN}`;

async function sendMessage(chatId, text, replyMarkup) {
  const r = await fetch(`${BASE}/sendMessage`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ chat_id: chatId, text, reply_markup: replyMarkup }),
  });
  return r.json();
}

async function poll() {
  let offset = 0;
  while (true) {
    const resp = await fetch(`${BASE}/getUpdates?offset=${offset}&limit=100`);
    const { result } = await resp.json();
    for (const u of result) {
      offset = Math.max(offset, u.update_id);
      if (u.message?.text === '/start') {
        await sendMessage(u.message.chat.id, 'Hello!');
      }
    }
    if (result.length === 0) await new Promise(r => setTimeout(r, 1000));
  }
}
poll();

Python (requests)

import requests, time

TOKEN = '123456789:AAEh…'
BASE = f'https://ix.x2chat.com/api/v1/bot{TOKEN}'

def send_message(chat_id, text, reply_markup=None):
    return requests.post(f'{BASE}/sendMessage', json={
        'chat_id': chat_id, 'text': text,
        'reply_markup': reply_markup,
    }).json()

offset = 0
while True:
    r = requests.get(f'{BASE}/getUpdates', params={'offset': offset, 'limit': 100}).json()
    for u in r['result']:
        offset = max(offset, u['update_id'])
        if u.get('message', {}).get('text') == '/start':
            send_message(u['message']['chat']['id'], 'Привет!')
    if not r['result']: time.sleep(1)

Простой webhook (Express)

Simple webhook (Express)

import express from 'express';
const app = express();
app.use(express.json());

app.post('/x2chat-webhook', (req, res) => {
  const update = req.body;
  if (update.callback_query) {
    const { id, data } = update.callback_query;
    // answer back
    fetch(`https://ix.x2chat.com/api/v1/bot<TOKEN>/answerCallbackQuery`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ callback_query_id: id, text: `Получено: ${data}` }),
    });
  }
  res.json({ ok: true });
});
app.listen(3000);

Оформление сообщений и кнопок (UI v2)

Message & button styling (UI v2)

POST /api/v1/bot<TOKEN>/sendMessage
{
  "chat_id": 123,
  "text": "Маяк мигает. Что делаем?",
  "as": { "name": "Смотритель", "avatar_emoji": "🧙" },
  "reply_markup": {
    "one_time": true,
    "inline_keyboard": [[
      { "text": "Идти", "callback_data": "go", "color": "#FFFFFF", "text_color": "#FFFFFF" }
    ]]
  }
}
→ {
  "ok": true,
  "result": { "message_id": "…", "as": { "name": "Смотритель", "is_persona": true, … }, "reply_markup": { … } },
  "warnings": [
    "button[0][0]: text_color #FFFFFF → #737373 (contrast < 4.5:1)",
    "button[0][0]: border_color (none) → #CCCCCC (button invisible on chat bubble)"
  ]
}

Лимиты и особенности

Limits & specifics

© X2Chat · Поддержка: bots@x2chat.com

© X2Chat · Support: bots@x2chat.com