QR-подключение бота к вашему сервису

QR connection bot → your service

Покажите QR на странице «Подключить X2Chat». Юзер сканит его в приложении — бот настраивается на ваш webhook одним подтверждением. Ни bot_token, ни secret в QR не попадают.

Show a QR on your "Connect X2Chat" page. The user scans it in the app — the bot is configured to call your webhook with one tap. No bot_token, no secret in the QR.

Как это работает

How it works

Формат QR payload

QR payload format

В QR кодируется plain-JSON. Только 5 полей:

QR encodes plain JSON. Only 5 fields:

{
  "v": 1,
  "type": "x2chat-webhook-setup",
  "webhook_url": "https://my-site.com/x2chat-webhook",
  "site_name": "MyService",
  "expires_at": "2026-05-22T12:05:00Z"
}

Setup confirmation ping

Setup confirmation ping

После confirmation X2Chat делает один HTTP POST на ваш webhook_url:

After confirmation X2Chat makes one HTTP POST to your webhook_url:

POST /your/x2chat-webhook HTTP/1.1
Host: my-site.com
Content-Type: application/json
X-X2Chat-Secret-Token: 9f4e7a2bd9c6f1...  // 32-байт hex
X-X2Chat-Setup-Confirm: true

{
  "setup_confirm": true,
  "bot": {
    "id": "d03bff3b-...uuid",
    "username": "my_info_bot",
    "first_name": "My Info Bot"
  },
  "owner_user_slot": "XI9W4A",
  "issued_at": "2026-05-22T12:00:00Z"
}

Что должен сделать ваш сайт:

What your site must do:

1. Считать X-X2Chat-Secret-Token из header'а
2. Сохранить его в БД, привязав к bot.id и (если есть) к вашему пользователю
3. Ответить 200 OK в течение 5 секунд (любой 2xx без body)
4. На последующих ping'ах сравнивать header с сохранённым значением — если не совпадает, отбрасывать запрос как поддельный

1. Read X-X2Chat-Secret-Token from header
2. Store it in DB, linked to bot.id and (if applicable) your user
3. Respond 200 OK within 5 seconds (any 2xx without body)
4. On subsequent webhook calls, compare the header with the stored value — reject mismatches as spoofed

Live генератор QR

Live QR generator

Заполните форму — QR обновляется автоматически. Скопируйте код в свой сайт.

Fill in the form — QR updates automatically. Copy the code to your site.

Пример: Node.js / Express

Example: Node.js / Express

// 1) Render page with QR
import express from 'express';
import QRCode from 'qrcode';

const app = express();
app.use(express.json());

app.get('/connect-x2chat', async (req, res) => {
  const payload = {
    v: 1,
    type: 'x2chat-webhook-setup',
    webhook_url: 'https://my-site.com/x2chat-webhook',
    site_name: 'MyService',
    expires_at: new Date(Date.now() + 5*60*1000).toISOString(),
  };
  const qrDataUrl = await QRCode.toDataURL(JSON.stringify(payload), { width: 320 });
  res.send(`<h2>Сканируйте в X2Chat:</h2><img src="${qrDataUrl}">`);
});

// 2) Setup confirmation ping
app.post('/x2chat-webhook', (req, res) => {
  const secret = req.headers['x-x2chat-secret-token'];
  if (req.body?.setup_confirm) {
    // First ping — save secret + bot info
    saveX2ChatBot({
      bot_id: req.body.bot.id,
      bot_username: req.body.bot.username,
      secret_token: secret,
    });
    return res.sendStatus(200);
  }
  // Regular update — verify secret
  const stored = lookupSecretByBotId(req.body?.bot?.id);
  if (secret !== stored) return res.sendStatus(401);
  // process update (message/callback_query/...)
  console.log('Update from', req.body);
  res.sendStatus(200);
});

app.listen(3000);

Пример: Python / FastAPI

Example: Python / FastAPI

# requirements: fastapi, qrcode[pil], pydantic
import qrcode, json, io, base64
from datetime import datetime, timedelta, timezone
from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.get('/connect-x2chat', response_class=HTMLResponse)
def connect_page():
    payload = {
        'v': 1,
        'type': 'x2chat-webhook-setup',
        'webhook_url': 'https://my-site.com/x2chat-webhook',
        'site_name': 'MyService',
        'expires_at': (datetime.now(timezone.utc) + timedelta(minutes=5)).isoformat(),
    }
    img = qrcode.make(json.dumps(payload))
    buf = io.BytesIO(); img.save(buf, format='PNG')
    b64 = base64.b64encode(buf.getvalue()).decode()
    return f'<h2>Сканируйте в X2Chat:</h2><img src="data:image/png;base64,{b64}">'

bot_secrets: dict = {}  # bot_id -> secret

@app.post('/x2chat-webhook')
async def webhook(req: Request):
    body = await req.json()
    secret = req.headers.get('x-x2chat-secret-token')

    if body.get('setup_confirm'):
        bot_secrets[body['bot']['id']] = secret
        return {'ok': True}

    bot_id = body.get('message', {}).get('bot', {}).get('id')
    if secret != bot_secrets.get(bot_id):
        raise HTTPException(401)

    print('Update:', body)
    return {'ok': True}

Безопасность

Security

Что защищено

• secret_token никогда не в QR — генерится X2Chat'ом и передаётся вашему сайту через HTTPS-ping. Скриншот QR не даёт доступа к bot pipeline
• TTL — после expires_at X2Chat отказывается даже сканировать payload
• HTTPS-only — webhook_url должен начинаться с https://, иначе ping не пойдёт
• SSRF-protection — LAN IPs (10.x, 172.16-31.x, 192.168.x, 127.x, ::1, fe80) и raw-IP URLs отбрасываются
• Auto-rollback — если первый ping не вернул 2xx за 5 сек, webhook НЕ сохраняется. Никаких «висящих» неработающих интеграций
• Typed confirmation — юзер вводит «Да» (или биометрия), не просто tap
• Audit log — в Bot Manager юзер видит список активных webhook'ов с доменами и временем установки, может revoke'ать любой

Что НЕ защищено (вне нашей зоны)

• Юзер сам сканит чужой QR — социальная инженерия. Митигация: confirmation крупным шрифтом + warning
• Сервер вашего сайта взломан — secret_token утечёт. Митигация: периодически делайте revoke через Bot Manager или setWebhook с новым URL
• TLS-MITM — мы доверяем стандартному HTTPS chain. Используйте сертификат от валидного CA, не self-signed

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

Possible errors

© X2Chat · Bot API docs · bots@x2chat.com

© X2Chat · Bot API docs · bots@x2chat.com