API и Webhook OmniGate Один REST API и единый формат webhook для WhatsApp, Telegram, MAX, VK, Instagram — и для вашего собственного канала: чата на сайте или мобильного приложения. Подключите канал в кабинете или по API — принимайте и отправляйте сообщения программно.

OmniGate нормализует все мессенджеры к одному формату. Вы создаёте сессию на канал, OmniGate присылает входящие на ваш webhook, а исходящие вы шлёте одним и тем же запросом POST /api/v1/messages — независимо от канала.

Telegram и MAX поддерживают два режима подключения: личный аккаунт и официальный бот по токену (см. параметры каналов). Для салонов есть готовая интеграция с YCLIENTS — уведомления о записи без единой строки кода.

Базовый URL

Все запросы — по HTTPS. Тело запросов и ответы — в формате application/json (UTF-8). Размер тела запроса — до 2 МБ.

Авторизация

Запросы к API авторизуются ключом в заголовке X-API-Key. Поддерживается и форма Authorization: Bearer <ключ>.

Где взять ключ

1. Войдите в личный кабинет → раздел API-ключи.
2. Нажмите Создать ключ. Полный ключ показывается один раз — сразу сохраните его.
3. В списке остаётся только префикс ключа. Потерянный ключ нельзя восстановить — отзовите его и создайте новый.

X-API-Key: og_live_xxxxxxxxxxxxxxxxxxxxxxxx

Если ключ не передан — 401 «нужен X-API-Key». Если ключ неверный или отозван — 401 «неверный или отозванный API-ключ».

Права ключа

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

Если у ключа нет нужного права, приходит 403, а в теле — какое право требуется и какие есть у ключа:

{
  "ok": false,
  "error": "у ключа нет права «messages:send» — выпустите ключ с этим правом в кабинете",
  "scope": "messages:send",
  "scopes": ["sessions:read", "messages:read"]
}

Журнал обращений

Каждый запрос к /api/v1 попадает в журнал: время, ключ, метод и путь, код ответа и длительность. Журнал виден в кабинете рядом со списком ключей — по нему удобно понять, какая интеграция получила 403 или 429 и когда ключ использовался в последний раз. Записи хранятся 30 дней.

Термины и сущности

Быстрый старт за 5 шагов

1. Получите API-ключ в кабинете (раздел «API-ключи»).
2. Подключите канал: в кабинете отсканируйте QR (WhatsApp/Telegram) или введите номер и код (MAX). Дождитесь статуса connected.
3. Укажите webhookUrl сессии — ваш HTTPS-адрес для входящих.
4. Примите тестовое сообщение: напишите на подключённый аккаунт — OmniGate пришлёт его на ваш webhook.
5. Ответьте через POST /api/v1/messages, используя sessionId и chatId из webhook.

curl -X POST https://omnigate.website/api/v1/messages \
  -H "X-API-Key: og_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "1f1d…uuid",
    "chatId": "79991234567",
    "text": "Привет из OmniGate!"
  }'

Подключение каналов

Сессия — это подключённый аккаунт. Создать её можно из кабинета (рекомендуется для входа по QR/коду) или через API.

POSTСоздать сессию

POST /api/v1/sessions
X-API-Key: og_live_xxx

{
  "channel": "max",
  "credentials": { "phone": "79991234567" },
  "webhookUrl": "https://your-crm.ru/hook?token=SECRET"
}

{
  "ok": true,
  "session": {
    "id": "1f1d…uuid",
    "channel": "max",
    "status": "awaiting_code",
    "webhookUrl": "https://your-crm.ru/hook?token=SECRET",
    "hasCredentials": true,
    "createdAt": 1750000000000
  }
}

Дальше действуйте по status: для WhatsApp/Telegram опрашивайте сессию и сканируйте QR, для MAX — отправьте SMS-код (см. вход по коду).

Параметры каналов

Статусы сессии и вход по коду

Узнать текущее состояние и QR можно в любой момент:

Ответ: { ok, session, qr }, где qr — data-URL картинки (для WhatsApp/Telegram, пока требуется скан).

POSTПодтвердить вход по коду

Передайте code (SMS-код) и, если аккаунт защищён двухфакторным паролем, далее — password. Нужно передать code или password.

POST /api/v1/sessions/1f1d…/code
{ "code": "12345" }

// если включена 2FA, ответ вернёт status: "awaiting_password"

POST /api/v1/sessions/1f1d…/code
{ "password": "мой_облачный_пароль" }

// при успехе status станет "connected"

DELETEОстановить и удалить сессию

Останавливает подключение и удаляет сессию. Ответ: { ok: true }.

Отправка сообщений

Единый эндпоинт для всех каналов. Текст или медиа — в одном запросе.

* Нужно передать либо text, либо mediaUrl.

Текст

{
  "sessionId": "1f1d…uuid",
  "chatId": "79991234567",
  "text": "Ваш заказ №1024 готов к выдаче 📦"
}

Медиа (фото / документ)

{
  "sessionId": "1f1d…uuid",
  "chatId": "79991234567",
  "mediaUrl": "https://cdn.your-crm.ru/invoice-1024.pdf",
  "kind": "document",
  "caption": "Счёт на оплату"
}

Ответ

// 200
{ "ok": true, "messageId": "a1b2c3" }

// 502 — провайдер не принял сообщение
{ "ok": false, "error": "описание причины" }

Формат chatId по каналам

Мост своего канала: свой сайт или приложение

Не все диалоги приходят из мессенджеров. Чат на вашем сайте, мобильное приложение, виджет в личном кабинете, форма обратной связи, любая внешняя платформа — всё это можно завести в OmniGate как обычный канал. Тогда переписка с такими собеседниками попадает в ту же историю, в тот же кабинет, в те же вебхуки и в то же зеркало amoCRM, что и WhatsApp или Telegram. Никакого отдельного кода под каждый источник — один и тот же формат входящих и исходящих.

Работает это в три шага: создать канал-контейнер, класть в него входящие и отвечать обычной отправкой.

Шаг 1. Создать канал

Тот же POST /api/v1/sessions, только channel — site (псевдонимы web, custom, widget; каноническое имя канала — webchat). Учётные данные генерирует сервер, передавать нечего. Канал подключается сразу, без QR и кодов: status сразу connected.

POST /api/v1/sessions
X-API-Key: og_live_xxx

{
  "channel": "site",
  "title": "Чат на сайте",
  "webchatEnabled": false,
  "webhookUrl": "https://your-crm.ru/hook?token=SECRET"
}

{
  "ok": true,
  "session": {
    "id": "255a385c…uuid",
    "channel": "webchat",
    "status": "connected",
    "publicKey": "wc_1fb0a677ee9c308ce7cc76da",
    "embed": "<script>…</script>"
  }
}

Шаг 2. Класть входящие

Каждое сообщение вашего пользователя отправляйте на эту ручку — она серверная, авторизуется вашим X-API-Key.

curl -X POST https://omnigate.website/api/v1/messages/inbound \
  -H 'X-API-Key: ВАШ_КЛЮЧ' -H 'Content-Type: application/json' \
  -d '{"sessionId":"<id>","chatId":"client-42","text":"Здравствуйте!","fromName":"Иван"}'

// 200
{ "ok": true, "chatId": "client-42" }

Дальше сообщение идёт по тому же конвейеру, что и входящее из мессенджера: попадает в историю, живьём появляется в кабинете, зеркалится в amoCRM (если у канала включено «Зеркалить в amoCRM» и amoCRM подключён по OAuth) и доставляется на ваш webhookUrl — с подписью, SSRF-проверкой и ретраями (до 6 попыток: 2, 4, 8, 16, 32 секунды).

Шаг 3. Отвечать

Ответ оператора или вашего бота — обычный POST /api/v1/messages с тем же sessionId и chatId. Исходящее тоже логируется и зеркалится в amoCRM, и — если посетитель сидит в виджете — мгновенно доезжает до него по SSE. Всю переписку можно поднять через GET /api/v1/messages.

Полный двусторонний мост: ответы менеджера из amoCRM → в ваш канал

Чтобы ответы, написанные менеджером внутри amoCRM, доходили до вашего получателя, задайте у канала Webhook доставки (кабинет → карточка канала → «Вебхук и детали» → «Webhook доставки», либо PATCH /api/v1/sessions/:id { "deliveryWebhookUrl": "https://..." }). OmniGate будет POST-ить туда каждый ответ менеджера — с подписью и ретраями (до 6 попыток) — а вы доставите его своему пользователю.

POST https://ваш-адрес/delivery   // подпись: X-OmniGate-Signature (как у входящих)
{
  "event": "outgoing", "direction": "out", "source": "amocrm",
  "sessionId": "<id>", "chatId": "client-42",
  "text": "Ответ менеджера", "timestamp": 1789300000000
}

Итого полный цикл кастомного канала: входящее → POST /api/v1/messages/inbound (в amoCRM); ваш ответ → POST /api/v1/messages (в amoCRM); ответ менеджера из amoCRM → на ваш Webhook доставки. Обе стороны видны в amoCRM, и переписка ходит в обе стороны.

Приём сообщений (Webhook)

Если у сессии задан webhookUrl, каждое входящее сообщение OmniGate доставляет на этот адрес POST-запросом с телом application/json. Формат единый для всех каналов.

Формат входящего

POST https://your-crm.ru/hook?token=SECRET
Content-Type: application/json

{
  "channel": "whatsapp",
  "sessionId": "1f1d…uuid",
  "chatId": "79991234567",
  "from": "79991234567",
  "text": "Здравствуйте! Заказ ещё актуален?",
  "attachments": [],
  "timestamp": 1750000000000,
  "raw": { /* исходные данные канала */ }
}

Требования к вашему эндпоинту

• Принимайте POST с телом JSON, отвечайте кодом 2xx (например, 200).
• Отвечайте быстро — таймаут запроса 10 секунд. Тяжёлую обработку выносите в очередь, а webhook просто подтверждайте.
• Эндпоинт должен быть доступен по HTTPS.

Повторные попытки

Если ваш сервер ответил не-2xx или не ответил за 10 с, OmniGate повторит доставку с нарастающей задержкой — до 6 попыток: через 2, 4, 8, 16 и 32 секунды. После исчерпания попыток сообщение остаётся в истории (его можно забрать через GET /api/v1/messages).

Подпись запроса (проверка подлинности)

Каждая доставка подписана. Заголовки запроса:

const crypto = require('crypto');

function verify(req, rawBody, secret) {
  const ts = req.headers['x-omnigate-timestamp'];
  const sig = req.headers['x-omnigate-signature'] || '';
  const want = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(ts + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}

Как обновить webhookUrl

Адрес задаётся при создании сессии (webhookUrl) или меняется в кабинете в настройках канала.

История сообщений

{
  "ok": true,
  "messages": [
    {
      "id": 9012,
      "session_id": "1f1d…uuid",
      "direction": "in",        // in — входящее, out — исходящее
      "chat_id": "79991234567",
      "body": "Заказ ещё актуален?",
      "created_at": 1750000000000
    }
  ]
}

Все эндпоинты

База: https://omnigate.website. Авторизация — X-API-Key (кроме служебных webhook-приёмников).

MCP для ИИ-агентов

Тот же API открыт по Model Context Protocol: если ваш агент или ИИ-ассистент умеет подключать MCP-серверы, писать обёртки над curl не нужно — он сам увидит список инструментов, их параметры и подсказки, когда какой применять.

Три точки входа для агента

Агенту достаточно один раз показать одну из трёх машиночитаемых точек входа. Дальше вы пишете обычными словами — «отправь Анне, что заказ собран», — а он сам решает, какой запрос сделать.

Подключение клиента

Имена полей у разных клиентов немного отличаются, но смысл один — адрес и заголовок с ключом:

{
  "mcpServers": {
    "omnigate": {
      "type": "http",
      "url": "https://omnigate.website/mcp",
      "headers": { "X-API-Key": "og_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Инструменты

22 инструмента — по одному на каждый эндпоинт /api/v1:

POST /mcp
X-API-Key: og_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "message_send",
    "arguments": {
      "sessionId": "3f2b8c1e-0f4a-4b7d-9a2e-1c5d6e7f8a90",
      "chatId": "79991234567",
      "text": "Здравствуйте! Заказ уже в пути."
    }
  }
}

Обычные команды вместо технических

Перезапустите клиент и проверьте подключение первой же фразой — «покажи, какие инструменты OmniGate тебе доступны». Агент ответит списком (channels_list, message_send, messages_history и остальные), и дальше технические слова не нужны:

• Какие у меня подключены каналы и все ли в порядке?
• Напиши в WhatsApp на 79991234567: «Заказ собран, привезём завтра до 12».
• Покажи последние 20 сообщений из телеграм-канала поддержки.
• Куда сейчас уходят входящие? Переключи вебхук на https://мой-сервис.ru/hook.
• Сколько сообщений я израсходовал в этом месяце и сколько каналов оплачено?
• Создай виджет чата для сайта с заголовком «Чем помочь?» и синим цветом.

Две вещи стоит сказать агенту заранее — это экономит круг переписки. chatId не выдумывать: это идентификатор собеседника внутри канала, и брать его нужно из истории сообщений, из входящего вебхука или через channel_resolve_username. Канал должен быть connected: если статус другой, пусть агент сначала посмотрит канал — там может ждать QR-код на пересканирование.

Агент без MCP — одна стартовая фраза

Если ваш клиент MCP не умеет, но умеет ходить в интернет и делать HTTP-запросы, хватит одного стартового сообщения. Скопируйте его целиком и подставьте свой ключ:

Прочитай https://omnigate.website/llms.txt — это описание API сервиса OmniGate,
через который у меня подключены мессенджеры. Мой ключ: og_live_xxxxxxxxxxxxxxxxxxxxxxxx,
передавай его заголовком X-API-Key. Дальше выполняй мои просьбы про сообщения
и каналы через этот API. Если запрос вернёт ошибку — прочитай текст ошибки,
там по-русски написано, что делать. chatId не выдумывай: бери его из истории
сообщений или из входящего вебхука.

/llms.txt — короткая выжимка того же, что на этой странице: с чего начать, что такое канал и chatId, все эндпоинты, лимиты, права ключа и формат входящего вебхука. Агент прочитает её один раз и дальше будет составлять запросы сам; команды ему пишутся те же, что выше.

Чего агент сделать не сможет

И это намеренно: выпускать новые API-ключи (ключ, выпускающий ключи, обходит любые ограничения прав), менять тариф и платить, заходить в админку, проходить OAuth amoCRM и YCLIENTS. Всё это остаётся за человеком в кабинете. Ещё два ограничения — секрет подписи вебхука и поток событий — описаны ниже.

Что стоит учесть

• Права работают точно так же. Инструмент выполняется от лица владельца ключа тем же кодом, что и REST, поэтому права ключа, лимиты тарифа и рейт-лимит действуют идентично. Обойти их через MCP нельзя.
• tools/list уже отфильтрован по правам вашего ключа: чего в списке нет — того ключу не разрешили. Вызовы попадают в тот же журнал обращений с пометкой mcp: перед путём.
• Отказ сервиса — не ошибка протокола. Нехватка прав, лимит тарифа, недоступный мессенджер приходят как обычный результат с isError: true и текстом на русском, в котором сказано, что делать. Ошибкой JSON-RPC отвечают только нарушения протокола: -32602 — неизвестный инструмент, -32601 — неизвестный метод, -32700 — не разобрать тело.
• Секрет подписи вебхука через MCP не выдаётся. webhook_get возвращает hasSecret и последние 4 символа — контекст агента слишком легко утекает. Полный секрет — в кабинете или запросом GET /api/v1/webhook.
• SSE-потока среди инструментов нет — поток не укладывается в один вызов. Вместо /api/v1/events опрашивайте messages_history.

Коды ошибок

Тело ответа при ошибке всегда содержит { "ok": false, "error": "…" }.

Готовая интеграция: amoCRM

OmniGate подключается к amoCRM как чат-канал: входящие из мессенджеров появляются в чатах amoCRM (раздел «Беседы» / «Неразобранное»), ответы менеджеров уходят клиенту обратно в тот же мессенджер. Программировать ничего не нужно — интеграция включается из кабинета.

Подключение

• Кабинет → раздел amoCRM → кнопка «Подключить через amoCRM» → войдите в свой amoCRM и нажмите «Разрешить».
• Подключение выполняется под администратором аккаунта amoCRM и занимает меньше минуты.

Воронки: куда падают заявки

Для каждого канала (номера) можно выбрать свою воронку — новые обращения будут создавать «Неразобранное» именно в ней:

• в разделе amoCRM кабинета — блок «Куда падают заявки» со списком всех каналов;
• или в карточке канала: «Вебхук и детали» → «Воронка amoCRM».

Если воронка не выбрана — обращения идут в воронку по умолчанию.

Что зеркалится

• Входящие текстовые сообщения клиентов — в чат amoCRM.
• Ответы встроенного ИИ-агента — тоже видны в чате amoCRM (как исходящие).
• Ответ менеджера из карточки amoCRM — доставляется клиенту в мессенджер.
• Зеркалирование можно выключить для отдельного канала (галочка в карточке канала).

Готовая интеграция: YCLIENTS

Для салонов и студий, работающих в YCLIENTS, подключение делается без кода — прямо в кабинете. OmniGate сам ловит события записи и рассылает клиентам уведомления и напоминания через любой ваш подключённый канал (WhatsApp, Telegram, MAX, VK).

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

1. Устанавливаете приложение OmniGate из маркетплейса YCLIENTS (или привязываете филиал вручную по его ID и user-токену).
2. В кабинете выбираете, через какой канал (сессию) отправлять сообщения клиентам филиала.
3. Включаете нужные типы уведомлений и задаёте свои шаблоны текста. Готово — сообщения уходят автоматически.

Типы уведомлений

Шаблоны

Каждый тип уведомления — это свой шаблон с подстановками. Доступные переменные:

{client}, вы записаны на «{service}» к мастеру {master}
{date} в {time}. Ждём вас в «{company}»!

Примеры интеграции

Node.js — webhook-приёмник и авто-ответ

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

const API = 'https://omnigate.website';
const KEY = process.env.OMNIGATE_KEY;

app.post('/hook', async (req, res) => {
  // 1) проверяем секрет из query-строки
  if (req.query.token !== process.env.HOOK_SECRET) return res.sendStatus(403);

  // 2) сразу подтверждаем приём (важно — до тяжёлой логики)
  res.sendStatus(200);

  const { sessionId, chatId, text } = req.body;
  if (!text) return;

  // 3) отвечаем тем же диалогом
  await fetch(`${API}/api/v1/messages`, {
    method: 'POST',
    headers: { 'X-API-Key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ sessionId, chatId, text: `Вы написали: ${text}` })
  });
});

app.listen(8080);

Python — отправка сообщения

import requests

requests.post(
    "https://omnigate.website/api/v1/messages",
    headers={"X-API-Key": "og_live_xxx"},
    json={
        "sessionId": "1f1d…uuid",
        "chatId": "79991234567",
        "text": "Заявка принята, менеджер свяжется с вами.",
    },
    timeout=30,
)

Сценарий для CRM

Типовая интеграция с amoCRM / Битрикс24 / YCLIENTS:

1. Входящее с webhook создаёт/находит сделку или клиента по from / chatId.
2. Текст сообщения добавляется в карточку как примечание.
3. Ответ менеджера из CRM уходит обратно через POST /api/v1/messages с тем же sessionId и chatId.
4. Шаблонные уведомления (статус заказа, запись на услугу) шлются тем же эндпоинтом по событию в CRM.