# OmniGate

> Шлюз сообщений: один REST API к WhatsApp, Telegram, VK, MAX, Instagram и чату
> на своём сайте. Входящие приходят на ваш вебхук единым форматом, исходящие
> отправляются одним и тем же запросом в любой канал. Есть готовая интеграция с
> amoCRM — переписка из всех мессенджеров попадает в карточки сделок без кода.

Сервис коммерческий, российский, работает по адресу https://omnigate.website.
Оплата в рублях, тариф считается по числу подключённых каналов, сообщения не
тарифицируются.

## Как начать

1. Зарегистрируйтесь в кабинете: https://omnigate.website/app
2. Выпустите API-ключ в разделе «API». Ключ выглядит как `og_live_…`.
3. Передавайте его в каждом запросе заголовком `X-API-Key` (принимается и
   `Authorization: Bearer og_live_…`).

Минимальный сценарий «принять и ответить» целиком:

```bash
# 1. создать канал — чат на своём сайте
curl -X POST https://omnigate.website/api/v1/sessions \
  -H "X-API-Key: og_live_…" -H "Content-Type: application/json" \
  -d '{"channel":"webchat","title":"Чат с нами"}'
# в ответе: session.id, session.publicKey и готовый session.embed для вставки на сайт

# 2. сказать, куда доставлять входящие
curl -X PATCH https://omnigate.website/api/v1/sessions/<id> \
  -H "X-API-Key: og_live_…" -H "Content-Type: application/json" \
  -d '{"webhookUrl":"https://ваш-сервис/hook"}'

# 3. ответить собеседнику (chatId берётся из вебхука)
curl -X POST https://omnigate.website/api/v1/messages \
  -H "X-API-Key: og_live_…" -H "Content-Type: application/json" \
  -d '{"sessionId":"<id>","chatId":"<chatId>","text":"Здравствуйте!"}'
```

## Что нужно знать перед первым запросом

- **Канал** (в API — `session`) — это подключённый аккаунт мессенджера или виджет
  на сайте. У него есть `id` (UUID) и `status`; работать можно, когда статус
  `connected`.
- **`chatId`** — собеседник внутри канала. Формат зависит от канала: телефон для
  WhatsApp, числовой id для Telegram и VK, ваш собственный идентификатор
  посетителя для своего канала. Не выдумывайте `chatId` — берите его из
  входящего вебхука или из `POST /api/v1/sessions/{id}/resolve`.
- **WhatsApp и личный Telegram подключаются по QR**: после создания канала
  опрашивайте `GET /api/v1/sessions/{id}`, пока в ответе есть поле `qr`
  (data-URL картинки), и покажите его человеку для сканирования.
- **Лимиты**: 120 запросов в минуту на аккаунт (429 с полем `retryAfter`), текст
  входящего до 4000 символов, файл до 25 МБ, число каналов и сообщений в месяц —
  по тарифу (402).
- **Права ключа**: при выпуске ключа можно отметить только нужные права —
  `sessions:read`, `sessions:write`, `messages:read`, `messages:send`,
  `messages:inbound`, `events:read`, `webhook:read`, `webhook:write`,
  `webchat:read`, `webchat:write`, `account:read`, `booking:read`,
  `booking:write`. Ключ без ограничений может
  всё, включая эндпоинты, которые появятся позже. Если права не хватает,
  приходит 403 с полями `scope` (какое право нужно) и `scopes` (какие есть);
  права меняются в кабинете, сам ключ при этом остаётся прежним.
- **Ошибки** всегда в виде `{"ok": false, "error": "текст на русском"}`.
  Успешный ответ всегда содержит `"ok": true`.
- **История хранится ограниченное время** и периодически чистится. Если нужна
  переписка навсегда — сохраняйте её у себя при получении на вебхук.

## Эндпоинты

Все — относительно `https://omnigate.website`, все требуют `X-API-Key`.

- `POST /api/v1/sessions` — создать и запустить канал
- `GET /api/v1/sessions` — список каналов со статистикой
- `GET /api/v1/sessions/{id}` — статус канала и QR-код
- `PATCH /api/v1/sessions/{id}` — вебхуки канала, зеркалирование в amoCRM, ИИ-агент
- `POST /api/v1/sessions/{id}/code` — подтвердить вход кодом или паролем 2FA
- `POST /api/v1/sessions/{id}/resolve` — найти `chatId` по `@username` (только личный Telegram)
- `DELETE /api/v1/sessions/{id}` — остановить и удалить канал
- `POST /api/v1/messages` — отправить текст или медиа
- `GET /api/v1/messages` — история сообщений
- `POST /api/v1/messages/inbound` — принять входящее из своего канала (мост)
- `POST /api/v1/messages/upload` — загрузить файл в base64 и сразу отправить
- `GET /api/v1/events` — поток новых сообщений в реальном времени (SSE, `text/event-stream`)
- `GET /api/v1/webhook` — адрес вебхука и секрет подписи
- `PUT /api/v1/webhook` — задать или очистить адрес: `{"url": "https://…"}`
- `POST /api/v1/webhook/rotate` — перевыпустить секрет подписи
- `POST /api/v1/webhook/test` — отправить тестовый подписанный запрос
- `GET /api/v1/webhook/deliveries` — журнал последних доставок
- `POST /api/v1/webhook/deliveries/{id}/retry` — повторить доставку
- `GET /api/v1/webchat` — виджеты чата на сайте и готовый код вставки
- `POST /api/v1/webchat` — создать виджет
- `PATCH /api/v1/webchat/{id}` — заголовок, цвет, приветствие, вкл/выкл
- `DELETE /api/v1/webchat/{id}` — удалить виджет
- `GET /api/v1/account` — тариф, лимиты и расход за текущий месяц
- `GET /api/v1/booking/branches` — филиалы, подключённые к аккаунту
- `GET /api/v1/booking/services` — услуги филиала: id, цена, длительность
- `GET /api/v1/booking/staff` — мастера, к которым принимают онлайн-запись
- `GET /api/v1/booking/dates` — дни, в которые есть свободное время
- `GET /api/v1/booking/slots` — свободное время мастера на день
- `POST /api/v1/booking/check` — свободно ли время; ничего не создаёт
- `POST /api/v1/booking/create` — записать клиента
- `POST /api/v1/booking/cancel` — отменить запись, созданную через API
- `POST /api/v1/booking/reschedule` — перенести её на другое время
- `GET /health` — проверка доступности, без ключа

Ручки `/webhook`, `/webchat`, `/events`, `/account` и `/booking` работают от лица
владельца ключа и возвращают данные того аккаунта, которому ключ выдан.

## Запись клиентов

Платная опция поверх тарифа. Владелец подключает свой салон (YCLIENTS) в
кабинете, после чего агент может показать клиенту свободное время и записать
его. Пока опция не подключена, все ручки `/api/v1/booking/*` отвечают 402.

Порядок вызовов — сверху вниз, без пропусков:

```bash
# 1. филиал (если он один, branchId дальше можно не передавать)
curl https://omnigate.website/api/v1/booking/branches -H "X-API-Key: og_live_…"

# 2. что делаем и у кого
curl "https://omnigate.website/api/v1/booking/services" -H "X-API-Key: og_live_…"
curl "https://omnigate.website/api/v1/booking/staff?serviceId=30759483" -H "X-API-Key: og_live_…"

# 3. когда: сначала дни, потом время внутри дня
curl "https://omnigate.website/api/v1/booking/dates?staffId=5813061&serviceId=30759483" -H "X-API-Key: og_live_…"
curl "https://omnigate.website/api/v1/booking/slots?staffId=5813061&date=2026-08-07" -H "X-API-Key: og_live_…"

# 4. записать
curl -X POST https://omnigate.website/api/v1/booking/create \
  -H "X-API-Key: og_live_…" -H "Content-Type: application/json" \
  -d '{"serviceId":30759483,"staffId":5813061,
       "datetime":"2026-08-07T13:00:00+05:00",
       "phone":"+7 916 123-45-67","name":"Анна"}'

# 5. перенести или отменить; recordId — из ответа шага 4
curl -X POST https://omnigate.website/api/v1/booking/reschedule \
  -H "X-API-Key: og_live_…" -H "Content-Type: application/json" \
  -d '{"recordId":"1886753778","datetime":"2026-08-08T10:00:00+05:00"}'

curl -X POST https://omnigate.website/api/v1/booking/cancel \
  -H "X-API-Key: og_live_…" -H "Content-Type: application/json" \
  -d '{"recordId":"1886753778"}'
```

Что важно знать:

- **`datetime` возвращайте из `/slots` байт в байт**, вместе со смещением
  часового пояса. Смещение принадлежит филиалу, а не вам и не UTC. Строка
  сверяется целиком: собранная вручную получит отказ 409, даже если время
  свободно, а пересчёт в свой пояс сдвинет запись на час.
- **Чужой салон недоступен физически.** `branchId` берётся из подключений
  владельца ключа, номер подобрать нельзя — незнакомый даёт 404.
- **`/check` перед `/create` не обязателен**: `/create` сам заново берёт
  `/slots` и сам прогоняет проверку на стороне салона. `/check` нужен, только
  если хочется подтвердить время клиенту, ещё не спросив имя и телефон.
- **Имя и мобильный телефон спрашивайте до вызова `/create`** — без них записи
  не будет. Телефон принимается в любом формате и приводится к `79161234567`;
  годится только мобильный, начинающийся на `+79`.
- **Повтор безопасен.** Ключ повтора по умолчанию — филиал + мастер + время +
  телефон, живёт час. Тот же запрос вернёт первую запись с `duplicate: true` и
  тем же `recordId`, а не заведёт второго клиента на тот же слот. Повтор не
  тратит лимит и не ходит в салон.
- **409 — время заняли**, пока вы разговаривали с клиентом. В ответе `freeTimes`
  с ближайшим свободным временем того же дня: предложите его, а не перебирайте
  время вслепую по одному запросу на попытку.
- **429 — сработал предохранитель записи**: не больше 3 записей в час с одного
  номера и 20 в час по филиалу. Считаются попытки, а не успехи. Это отдельный
  лимит, помимо общих 120 запросов в минуту.
- **422 с текстом «Не передан обязательный параметр email.»** — этот салон
  требует почту в настройках онлайн-записи. Спросите адрес у клиента и
  повторите вызов с полем `email`. Свой адрес не подставляйте: он попадёт в
  карточку клиента в CRM салона.
- **Отменить и перенести можно только свои записи** — те, что создал `/create`.
  Код отмены YCLIENTS отдаёт ровно один раз, в ответе на создание, и больше
  нигде; записи, сделанные администратором салона или через сайт салона, для
  API не существуют. В этом случае направьте клиента звонить в салон.
- **Переноса в YCLIENTS нет вовсе**, поэтому `/reschedule` создаёт новую запись
  и снимает старую. Не удалось создать новую — старая осталась на месте, клиент
  ничего не заметил. Создали новую, но не сняли старую — придёт 409, а салону
  уйдёт уведомление: молча две записи на одного клиента не остаются.
- **Повтор отмены — это успех.** Уже отменённая запись отвечает 200 с
  `already: true`, а не ошибкой: агент, потерявший ответ, обязан иметь право
  переспросить.
- Слот свободен на момент ответа, а не навсегда: между показом и записью его
  может занять живой человек через сайт салона или администратор по телефону.
- Мастера и услуги, закрытые для онлайн-записи, не отдаются вовсе — если их нет
  в ответе, предлагать их клиенту нельзя.
- Владельцу салона уходит уведомление о каждой записи, сделанной через API.

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

Если вы агент с поддержкой Model Context Protocol, подключайтесь напрямую —
писать обёртки над curl не нужно:

- адрес: `https://omnigate.website/mcp`
- транспорт: Streamable HTTP, одно JSON-RPC 2.0 сообщение в теле POST
- авторизация: тот же заголовок `X-API-Key: og_live_…`
- версии протокола: `2025-11-25`, `2025-06-18`, `2025-03-26`
- методы: `initialize`, `ping`, `tools/list`, `tools/call`

Типовая настройка клиента (имена полей у разных клиентов отличаются):

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

Инструменты повторяют REST один в один, 31 штука: `channels_list`,
`channel_get`, `channel_create`, `channel_update`, `channel_delete`,
`channel_resolve_username`, `channel_submit_login_code`, `messages_history`,
`message_send`, `message_receive`, `message_send_file`, `webhook_get`,
`webhook_set`, `webhook_rotate_secret`, `webhook_test`, `webhook_deliveries`,
`webhook_delivery_retry`, `webchat_widgets_list`, `webchat_widget_create`,
`webchat_widget_update`, `webchat_widget_delete`, `account_get`,
`booking_branches`, `booking_services`, `booking_staff`, `booking_dates`,
`booking_slots`, `booking_check`, `booking_create`, `booking_cancel`,
`booking_reschedule`.

Что важно знать:

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

## Входящий вебхук

OmniGate POST-ит на ваш адрес каждое входящее сообщение — одинаково для всех
каналов:

```json
{
  "channel": "whatsapp",
  "sessionId": "3f2b8c1e-0f4a-4b7d-9a2e-1c5d6e7f8a90",
  "chatId": "79991234567",
  "from": "79991234567",
  "fromName": "Анна",
  "text": "Здравствуйте, когда доставите?",
  "attachments": [],
  "timestamp": 1785348000000,
  "raw": {}
}
```

Отвечайте `2xx` как можно быстрее. Любой другой код, редирект или таймаут
считается неуспехом — доставка повторится с задержкой 1, 2, 4, 8… до 32 секунд.
Заголовок `X-OmniGate-Delivery` одинаков у повторов: используйте его, чтобы не
обработать одно сообщение дважды.

Если в кабинете задан секрет вебхука, приходит подпись
`X-OmniGate-Signature: sha256=<hex>`, где hex — это
`HMAC-SHA256(секрет, "<X-OmniGate-Timestamp>.<сырое тело запроса>")`. Считайте её
по сырому телу, до разбора JSON.

## Ссылки

- [OpenAPI 3.1](https://omnigate.website/openapi.json): машиночитаемое описание всех эндпоинтов, схем и вебхука
- [MCP-сервер](https://omnigate.website/mcp): тот же API для ИИ-агентов по Model Context Protocol, 31 инструмент
- [Документация](https://omnigate.website/docs): подключение каналов, примеры curl, коды ошибок, интеграция с amoCRM
- [Личный кабинет](https://omnigate.website/app): выпуск API-ключей, подключение каналов, подписка
- [Тарифы и оплата](https://omnigate.website/payments): цена за канал, скидки за период предоплаты
- [Контакты](https://omnigate.website/contact): связь с поддержкой
- [Оферта](https://omnigate.website/oferta) и [политика конфиденциальности](https://omnigate.website/privacy)