База знаний GetMyBot

Внешний обработчик

Как передать сложную логику бота своему серверу. Подключение по WebSocket, события, команды и поведение при потере связи.

На этой странице

Внешний обработчик позволяет выполнять часть логики бота на вашем сервере. Например, сервер рассчитывает персональное предложение из вашей базы, а GetMyBot получает сообщение клиента и отправляет готовый ответ в Telegram.

Настройка предназначена для разработчика: сервер подключается к GetMyBot по постоянному соединению WebSocket, получает события и возвращает команды в формате Telegram Bot API. Обычные ответы и анкеты можно оставить в визуальном конструкторе.

Что это

Внешний обработчик нужен, если ваша программа должна управлять разговором: выполнять нестандартные расчёты, обращаться к своей базе или выбирать следующий вопрос по сложным правилам. Вы передаёте ей обработку отдельной реакции, сохраняя остальные реакции в конструкторе.

Ваша программа получает событие: сработало правило, пришёл ответ или нажата кнопка. В ответ она указывает, что должен сделать бот. GetMyBot проверяет команды, ставит их в очередь и отправляет своим токеном. Платформа ограничивает частоту отправки, повторяет временно неудачные попытки, защищает от дублей и записывает сообщения в историю диалога.

Модель работы

  • GetMyBot принимает соединение WebSocket. Ваша программа сама подключается к нему; открывать публичный адрес для неё не нужно. GetMyBot не делает исходящих запросов к вашей программе.
  • Аутентификация: токеном интеграции. Сервис предъявляет токен при подключении; GetMyBot сверяет его с хешем и держит соединение.
  • События и команды используют формат Telegram Bot API. Программа получает событие, а отвечает списком вызовов вида «метод + параметры», как при работе с обычным Telegram-ботом.
  • Команды исполняет GetMyBot своим токеном. Программа не обращается к Telegram напрямую: команды проверяются и попадают во внутреннюю очередь отправки GetMyBot (outbox). Там действуют ограничения частоты, повторные попытки, защита от дублей и журнал.

Одного соединения достаточно для всех диалогов этой интеграции. События разных пользователей различаются по session_id, идентификатору диалога.

Настройка интеграции

  1. Откройте раздел Интеграции в меню слева и нажмите Добавить интеграцию.
  2. Выберите сервис Внешний обработчик и задайте название.
  3. После создания карточка покажет:
    • Адрес WebSocket: вида wss://api.mybot.app/ext/ws/<integrationID>. Здесь <integrationID> – уникальный идентификатор этой интеграции (UUID). По адресу подключается ваша программа; без идентификатора в пути соединение не установится.
    • Токен подключения: показывается один раз при создании. Скопируйте и сохраните его в надёжном месте; повторно посмотреть токен нельзя (он хранится только хешем).
    • Перевыпуск токена: кнопка генерирует новый токен и сразу обесценивает старый. После перевыпуска обновите токен в своём сервисе.
    • Индикатор онлайн: показывает, держит ли ваш сервис активное соединение прямо сейчас.

Дополнительные параметры интеграции, влияющие на протокол:

  • session_ttl_seconds: время жизни сессии в секундах (по умолчанию 3600).
  • on_unavailable_reaction_id: запасная реакция, которая запускается, если сервис офлайн в момент срабатывания (см. Надёжность).

Привязка к реакции

Внешний обработчик подключается не отдельным триггером, а действием. В редакторе реакции добавьте действие Передать внешнему обработчику и выберите нужную интеграцию.

Открыть диалог может любой существующий триггер GetMyBot: команда, текст, нажатие кнопки, параметр из ссылки, входящий веб-запрос, расписание. Когда такой триггер срабатывает и доходит до действия, GetMyBot открывает прокси-сессию и шлёт сервису событие session.open.

Если в этот момент ваша программа не подключена, GetMyBot запустит запасную реакцию из настройки интеграции (on_unavailable_reaction_id). Если запасная реакция не задана, клиент не получит ответ или сообщение об ошибке.

Подключение и авторизация

Эндпоинт: GET /ext/ws/{integrationID} поверх WebSocket (wss). integrationID: UUID интеграции типа «Внешний обработчик». Лимит размера кадра: 256 KiB.

Авторизоваться можно одним из двух способов.

1. Заголовок при рукопожатии (предпочтительно). Передайте токен в заголовке Authorization:

Authorization: Bearer <token>

2. Auth-кадром. Если Bearer-заголовок не передан, первым кадром в течение 10 секунд после установления соединения отправьте:

{ "type": "auth", "token": "<token>" }

Если за 10 секунд auth-кадр не пришёл: соединение закрывается с кодом 4401. Неверный токен в любом из способов: тоже close 4401.

Токен генерируется при создании интеграции, показывается один раз и хранится только хешем (sha256), сверка: constant-time. Ротация токена:

POST /api/bots/{botID}/integrations/{integrationID}/rotate-token

Эндпоинт возвращает новый plaintext-токен; старый сразу перестаёт работать.

События: бот → сервис

Каждое событие: JSON-кадр (EventEnvelope). Поле type: одно из: session.open, message, callback, session.cancel, session.expired.

Полный набор полей конверта:

{
  "type": "session.open",
  "session_id": "string",
  "bot_id": "string",
  "user": {
    "tg_user_id": 123456789,
    "first_name": "Иван",
    "username": "ivan",
    "params": { "utm": "promo" }
  },
  "chat": { "id": 123456789, "type": "private" },
  "update": { "...": "сырой Telegram Update (raw JSON)" },
  "event": { "...": "нормализованное событие GetMyBot (raw JSON)" }
}
  • session_id: идентификатор сессии (диалога).
  • bot_id: идентификатор бота.
  • user: данные пользователя: tg_user_id (int64), опциональные first_name, username, а также params: параметры пользователя (в т.ч. из ссылки), map ключ→значение.
  • chat: чат: id (int64) и type (например "private").
  • update: сырой Telegram Update (raw JSON). Присутствует для session.open, message, callback.
  • event: нормализованное событие GetMyBot (raw JSON).

Наполнение по типам различается:

  • session.open: сработал триггер, открыт новый диалог. Есть update (сырой Update) и event (полное нормализованное событие), user.params заполнены.
  • message: приходит, когда сервис «держит ожидание» (expect = text/any) и пользователь прислал сообщение. Наполнение такое же, как у session.open.
  • callback: пользователь нажал кнопку, которую раньше прислал сервис. update сырой; в user заполнен только tg_user_id; event содержит только исходный callback_data, заданный сервисом в кнопке:
{ "callback_data": "<оригинальное значение, заданное сервисом в кнопке>" }
  • session.cancel / session.expired: минимальный конверт: session_id, bot_id, user.tg_user_id, chat.id (для cancel ещё chat.type). Полей update/event нет. Эти события доставляются только если сервис онлайн: в офлайн-очередь они не кладутся.

Команды: сервис → бот

Команда: JSON-кадр (CommandEnvelope). Поле type: одно из: execute, session.close, auth, ping, pong.

{
  "type": "execute",
  "session_id": "string",
  "methods": [
    { "method": "sendMessage", "params": { "text": "Привет" } }
  ],
  "expect": "none"
}
  • session_id: сессия, к которой относится команда.
  • token: только для type: "auth" (см. Подключение и авторизация).
  • methods: массив объектов { "method": "<имя метода Telegram Bot API>", "params": { ... } }. Имя метода: точь-в-точь как в Telegram Bot API (например sendMessage), params: объект параметров этого метода.
  • expect: ждёт ли сервис ответа пользователя: "none", "text" или "any" (пустое значение трактуется как none).
  • session.close: явно закрыть диалог.

Команды не уходят в Telegram напрямую: GetMyBot валидирует их и кладёт в свой outbox, откуда отправляет токеном бота (с rate-limit, ретраями, дедупликацией, журналом).

Как обрабатывается execute

Команда execute целиком игнорируется, если session_id пуст, диалог не найден, уже закрыт, просрочен или принадлежит другой интеграции.

Далее:

  • Частота команд: до 60 execute в минуту на диалог (скользящее окно). Команды сверх лимита игнорируются.
  • До 30 методов в одном execute; лишние молча отбрасываются.
  • На каждый метод проверяется whitelist (см. Разрешённые методы): метод не из списка отклоняется.
  • Защита чата: если в params указан chat_id или from_chat_id со значением, отличным от 0 и chat_id текущего диалога, метод отклоняется: отправлять в чужой чат нельзя. chat_id можно не указывать; GetMyBot сам подставит ID текущего чата.
  • Inline-кнопки с callback_data автоматически токенизируются (внутренний вид x:<token>); время жизни кнопки = до истечения сессии. Кнопки url/webapp/switch_inline не трогаются.

Разрешённые методы

Сервис командует ботом, поэтому набор методов ограничен whitelist: только отправка и работа с сообщениями текущего диалога. Методы не из списка молча игнорируются (это не ошибка).

  • отправка: sendMessage, sendPhoto, sendDocument, sendVideo, sendAudio, sendMediaGroup, sendAnimation, sendVoice, sendLocation, sendChatAction;
  • правка и удаление: editMessageText, editMessageCaption, editMessageReplyMarkup, deleteMessage;
  • ответ на нажатие: answerCallbackQuery;
  • пересылка и копирование: forwardMessage, copyMessage;
  • закрепление: pinChatMessage, unpinChatMessage.

Аккаунт-уровневые методы (setWebhook, getUpdates, logOut, close, setMyCommands и т.п.) не разрешены.

Ожидание и жизненный цикл сессии

После каждого execute судьба сессии зависит от expect и от того, были ли в команде inline-кнопки с callback_data:

  • expect = text или any: следующее сообщение пользователя будет переслано сервису событием message.
  • expect = none И в команде НЕ было inline-кнопок с callback: сессия автоматически закрывается. Это «терминальное» сообщение.
  • expect = none, НО есть callback-кнопки: сессия остаётся открытой: нажатия ловятся, пока живы токены кнопок (до TTL).

Важно: expect не влияет на приём нажатий кнопок. Нажатия токенизированных кнопок ловятся независимо от значения expect: пока жива сессия и токен кнопки. expect управляет только тем, ждёт ли сервис текстового/произвольного ответа.

Границы диалога

Контекст диалога живёт ровно до тех пор, пока сессия открыта:

  • Текстовый ответ при активном ожидании (expect = text/any): уходит сервису событием message, а не запускает обычные реакции бота.
  • Нажатие токенизированной кнопки: уходит сервису событием callback с оригинальным callback_data. GetMyBot всегда сам подтверждает нажатие (answerCallbackQuery); проверяется принадлежность нажатия (бот + пользователь + чат сессии). Кнопкой сессия не закрывается.
  • /cancel (а также /cancel@bot и «отмена») при активной внешней сессии: сессия закрывается, сервису шлётся session.cancel, пользователю отправляется «Отменено.».
  • Один диалог на пользователя. Открытие новой сессии вытесняет прежнюю открытую сессию этого пользователя: ей шлётся session.cancel.
  • Истечение TTL. По таймеру сессия помечается expired и (если сервис онлайн) сервису шлётся session.expired.

Лимиты и таймауты

ОграничениеЗначение
Размер кадра256 KiB.
TTL сессиипо умолчанию 3600 секунд (настраивается параметром session_ttl_seconds интеграции).
Частота команд60 execute в минуту на сессию (скользящее окно).
Методов в одном executeдо 30 (лишние отбрасываются).
Открытых сессий на интеграциюдо 1000.
Офлайн-очередьдо 100 событий на сессию.
Heartbeatping каждые 30 секунд; таймаут отсутствия активности: 60 секунд.
Таймаут auth-кадра10 секунд.

Надёжность (heartbeat, офлайн, очередь, fallback)

Heartbeat означает периодическую проверку связи. Fallback означает запасной ответ, если сервис недоступен. Настройте его заранее: например, сообщите клиенту о задержке и предложите связаться с оператором.

  • Heartbeat. Сервер раз в 30 секунд шлёт кадр {"type":"ping"}. Если от клиента нет активности дольше 60 секунд: соединение закрывается. Клиент может слать свои ping/pong для поддержания активности. Разрыв соединения не убивает диалоги: сессии живут в БД до TTL или переподключения.
  • Переподключение: на стороне сервиса. Если соединение оборвалось, ваш сервис должен подключиться заново. Открытые сессии в БД переживают рестарты до истечения TTL.
  • Fallback при офлайне на старте. Если в момент срабатывания реакции сервис не подключён: запускается запасная реакция из настройки интеграции (on_unavailable_reaction_id). Если она не задана: ничего не происходит (тихо).
  • Очередь при потере связи. Недоставленные события message и callback сохраняются до истечения диалога, не более 100 на диалог, в порядке поступления (FIFO). При переподключении они отправляются вашей программе. События session.open, session.cancel и session.expired в очередь не попадают.
  • Доставка не более одного раза (at-most-once). Повторная доставка не гарантируется. Если очередь переполнена или срок хранения закончился, событие будет потеряно. Программа должна уметь продолжить разговор после такого пропуска.

Индикатор онлайн

Проверить, держит ли сервис активное соединение, можно эндпоинтом:

GET /api/bots/{botID}/integrations/{integrationID}/status

Ответ:

{ "online": true }

Тот же индикатор доступен на карточке интеграции в кабинете. Аналог в MCP: инструмент get_integration_status.

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

GetMyBot исполняет команды стороннего сервиса своим токеном, поэтому защита строгая.

  • Нет SSRF-поверхности. GetMyBot выступает WebSocket-сервером и сам исходящих соединений к сервису не делает: это сервис подключается к GetMyBot. Управляемого извне URL, по которому платформа куда-то ходит, нет.
  • Токен хранится хешем (sha256), сверка constant-time, поддержана ротация.
  • Изоляция аккаунта. Команда жёстко привязана к своей интеграции; сессия: к боту + пользователю + чату. События чужих ботов в ваш сокет не попадают.
  • Whitelist методов + принудительный chat_id не дают превратить бота в рассыльщик в произвольные чаты.
  • Токен бота наружу не передаётся: сервис никогда не общается с Telegram напрямую.
  • Маскирование секретов. Токен интеграции и чувствительные значения скрываются в журнале и логах.

Примеры

Минимальный обработчик: на открытие диалога отправляет сообщение и закрывает сессию (expect: "none"). Подставьте id интеграции и токен. Адрес обязательно содержит <integrationID> в пути.

Node.js

import WebSocket from "ws";

const URL = `wss://api.mybot.app/ext/ws/${process.env.MYBOT_INTEGRATION_ID}`;
const ws = new WebSocket(URL, {
  headers: { Authorization: `Bearer ${process.env.MYBOT_TOKEN}` },
});

ws.on("message", (raw) => {
  const ev = JSON.parse(raw);
  if (ev.type === "session.open") {
    ws.send(JSON.stringify({
      type: "execute",
      session_id: ev.session_id,
      expect: "none",
      methods: [{ method: "sendMessage", params: { text: "Привет от внешнего обработчика!" } }],
    }));
  }
});

Python

import json, os, asyncio, websockets

async def main():
    url = f"wss://api.mybot.app/ext/ws/{os.environ['MYBOT_INTEGRATION_ID']}"
    headers = {"Authorization": f"Bearer {os.environ['MYBOT_TOKEN']}"}
    async with websockets.connect(url, additional_headers=headers) as ws:
        async for raw in ws:
            ev = json.loads(raw)
            if ev["type"] == "session.open":
                await ws.send(json.dumps({
                    "type": "execute",
                    "session_id": ev["session_id"],
                    "expect": "none",
                    "methods": [
                        {"method": "sendMessage", "params": {"text": "Привет от внешнего обработчика!"}}
                    ],
                }))

asyncio.run(main())

Inline-кнопка и обработка callback

Чтобы поймать нажатие, пришлите кнопку с callback_data (GetMyBot токенизирует её автоматически). При expect: "none" с кнопкой сессия остаётся открытой, пока жив токен кнопки: нажатие придёт событием callback, в котором event.callback_data равен исходному значению. Подтверждать нажатие (answerCallbackQuery) не нужно: GetMyBot делает это сам.

if (ev.type === "session.open") {
  ws.send(JSON.stringify({
    type: "execute",
    session_id: ev.session_id,
    expect: "none",
    methods: [{
      method: "sendMessage",
      params: {
        text: "Нажмите кнопку",
        reply_markup: { inline_keyboard: [[{ text: "Поехали", callback_data: "go" }]] },
      },
    }],
  }));
} else if (ev.type === "callback" && ev.event.callback_data === "go") {
  ws.send(JSON.stringify({
    type: "execute",
    session_id: ev.session_id,
    expect: "none",
    methods: [{ method: "sendMessage", params: { text: "Кнопка нажата!" } }],
  }));
}

Что дальше