Перейти до змісту

WebSocket API

9 хв читання Оновлено 21 листопада 2026 API JAAM

Тривоги в реальному часі: одне довге з'єднання, по якому сервер сам надсилає зміни.

RESThttps://jaam.net.ua
WebSocketwss://ws.jaam.net.ua/data_service_v1

Сервіси підключаються лише до /data_service_v1. Він віддає тільки пакети тривог (0xA1) та додаткові тривоги (0xA2) і має власний перший пакет, у якому клієнт називає себе й свого власника.

Перевірте service_id

service_id — постійний ідентифікатор вашого сервісу. Формат: 3–64 символи, лише a-z, 0-9, ., _, -, перший символ — літера чи цифра.

Перевірка лише підказка: id закріплюється за вами, коли ваш клієнт із валідним hello пробуде підключеним хоча б хвилину. Запитом можна не частіше 20 разів на хвилину.

bash
curl -s "https://jaam.net.ua/service_id_check_v1.json?service_id=my-bot"
# {"service_id": "my-bot", "taken": false}

Адреси

ПараметрЗначення
Хостws.jaam.net.ua (порт 80, ws://; також wss:// на 443)
Шлях/data_service_v1
Прикладwss://ws.jaam.net.ua/data_service_v1

Життєвий цикл з'єднання

Клієнт сервісу Сервер loopпостійно WebSocket handshake hello:<JSON> початковий пакет тривог (0xA1) ping pong оновлення тривог (0xA1) додаткові тривоги (0xA2)
Обмін по WebSocket: рукостискання, hello, потім безперервний цикл.
Тримайте з'єднання відкритим

Підключились один раз — і не розривайте його після початкових даних. Схема «підключився → отримав → відключився → через хвилину знову» є зловживанням, за яке блокують. Якщо потрібні дані раз на деякий час, використовуйте REST із дозволеною частотою.

Перший пакет hello

Одразу після з'єднання клієнт сам надсилає одне текстове повідомлення: hello: і JSON-об'єкт.

hello
# одне текстове повідомлення
hello:{"service_id":"my-bot","client_id":"3f9c2a7e-1b4d-4c8e-9a52-7d0e6f1b2c33",
  "name":"Мій бот","website":"https://bot.example","contact":"@owner_tg","version":"1.0.0"}
ПолеОбов'язковеПравила
service_idтакОдин на весь сервіс: усі його клієнти надсилають те саме значення
client_idтакUUID екземпляра (8-4-4-4-12 hex). Згенеруйте один раз і зберігайте
nameтакНазва сервісу, 1–80 символів
websiteтакhttp(s)://…, до 200 символів, без пробілів
contactтакEmail, Telegram, WhatsApp чи Signal, 3–120 символів. Має бути справжнім
versionтакВерсія вашого клієнта, 1–32 символи
10 сЧасу на helloІнакше сервер закриє з'єднання без даних.
1×Лише перший helloПовторні й інші повідомлення клієнта ігноруються.
+Невідомі поляІгноруються. Керуючі символи заборонені.

Коди закриття

Код і причинаЩо означаєЩо робити
1008 bad_hello:<поле>Поле відсутнє або некоректнеВиправте клієнт, не повторюйте в циклі
1008 hello_timeouthello не надійшов за 10 сНадсилайте одразу після з'єднання
4403 service_blockedСервіс заблокованоНе перепідключайтесь у циклі; зв'яжіться з адміністратором
1008 ip_blockedIP заблоковано під час сесіїНе перепідключайтесь у циклі

Як зберігати client_id

client_id ідентифікує один фізичний екземпляр: пристрій, інсталяцію, браузер. Новий id щоразу перетворить один пристрій на сотні «клієнтів». Згенеруйте UUID один раз і надсилайте той самий після перезапусків, перепідключень і оновлень.

Де працює клієнтДе зберігати
Сторінка чи віджет у браузеріlocalStorage. Не sessionStorage і не cookie
Скрипт, бот, Raspberry Pi, Home AssistantФайл у каталозі даних. У Docker — на томі (volume)
Прошивка ESP32NVS (Preferences в Arduino-ESP32)
Мобільний застосунокAndroid: SharedPreferences чи DataStore; iOS: UserDefaults

Окремі випадки:

  • Різні пристрої - різні id. Не копіюйте один client_id у кілька пристроїв чи в образ, з якого їх розгортають: ми побачимо їх як одного клієнта.
  • Не будуйте id з особистих даних (email, IP). MAC-адресу теж не використовуйте як є: вона ідентифікує власника пристрою. Випадковий UUID у сховищі надійніший.
  • Кілька вкладок одного сайту. Кожна вкладка з окремим з'єднанням - це зайве навантаження. Краще одне з'єднання на браузер: тримайте його в SharedWorker або віддавайте керування одній вкладці через Web Locks API, а client_id у всіх вкладок один (з localStorage).
  • Немає постійного сховища (наприклад, одноразовий контейнер): тоді WebSocket-клієнт там не потрібен. Якщо інакше ніяк, виведіть id із чогось стабільного (UUID v5 від імені екземпляра), а не з випадкового числа при кожному запуску.

Браузер:

function getClientId() {
  const KEY = "jaam_client_id";
  try {
    let id = localStorage.getItem(KEY);
    if (!id) {
      id = crypto.randomUUID();
      localStorage.setItem(KEY, id);
    }
    return id;
  } catch (e) {
    // сховище недоступне (заборонене в налаштуваннях): id діє лише поки відкрита сторінка
    window.__jaamClientId = window.__jaamClientId || crypto.randomUUID();
    return window.__jaamClientId;
  }
}

ESP32 (Arduino):

#include <Preferences.h>

String getClientId() {
  Preferences prefs;
  prefs.begin("jaam", false);
  String id = prefs.getString("client_id", "");
  if (id.length() != 36) {  // першого разу: згенерувати й зберегти в NVS
    uint32_t r[4];
    for (auto &x : r) x = esp_random();
    char buf[37];
    snprintf(buf, sizeof buf, "%08x-%04x-%04x-%04x-%04x%08x",
             (unsigned)r[0], (unsigned)(r[1] >> 16), (unsigned)(r[1] & 0xffff),
             (unsigned)(r[2] >> 16), (unsigned)(r[2] & 0xffff), (unsigned)r[3]);
    id = buf;
    prefs.putString("client_id", id);
  }
  prefs.end();
  return id;
}

Приклад для Python (файл біля програми) є нижче.

Що надсилає сервер

Після hello сервер надсилає початковий стан тривог, а далі зміни. Повідомлення бінарні (little-endian), перший байт — тип. Невідомі типи ігноруйте, а не розривайте з'єднання.

Тривоги 0xA1

Заголовок
0xA1типhash_actualu16hash_previousu16
Запис (повторюється)
region_idu16, напр. 31 — м. Київflagsu16, бітова маска

Перший пакет після підключення — повний стан, далі лише змінені регіони. flags — бітова маска:

БітЗначенняБітЗначення
0повітряна тривога7загроза КАБ
1артилерійська небезпека8балістична загроза
2вуличні бої9вибухи (лише в 0xA2)
3хімічна небезпека10розвідувальний дрон
4ядерна небезпека11рівень тривоги: жовтий
5загроза дронів (БПЛА)12рівень тривоги: червоний
6ракетна загроза
Відбій і цілісність

Регіон із flags = 0 означає, що тривога закінчилась: приберіть його зі стану. Якщо hash_previous нового пакета не збігається з hash_actual останнього, ви пропустили пакет. Перепідключіться, щоб отримати повний стан.

Додаткові тривоги 0xA2

Додаткові тривоги (0xA2). Повідомлення: [0xA2], далі записи [region_id u16][flags u16] (без hash_actual/hash_previous). Це сповіщення про події, а не стан: початкового пакета немає, надходять лише нові події. Сервер не надсилає відбою для 0xA2: регіон, що не згадано, ні про що не каже, а flags = 0 тут не «відбій». Клієнт сам вирішує, як довго показувати подію, і сам її вимикає за таймаутом (наприклад, через кілька хвилин після останнього сповіщення; повторне сповіщення для регіону продовжує показ). Не зберігайте події в стані регіонів 0xA1 і не перевіряйте цілісність. Зараз у 0xA2 приходять біти 6 (ракетна загроза) і 9 (вибухи); набір бітів може розширюватись. Розбір такий самий, як у 0xA1: тіло записів має ділитися на 4, інакше пропустіть кадр.

0xA1 — стан0xA2 — сповіщення
Що цепоточний стан регіоніводноразова подія
Після підключенняповний станнічого, лише нові події
Відбійприходить у потоці: flags = 0не приходить, клієнт вимикає подію за таймаутом
Хешіє, перевіряйтенемає
Що робитизберігати стан і показуватипоказати, запустити таймер і забути

Біт 6 може прийти в обох потоках (стан із «хмар небезпеки» та сповіщення): це нормально, показуйте одне з джерел або об'єднуйте самі.

Біти типу небезпеки (1, 5, 6, 7, 8, 10) описують, чим саме загрожує регіон. Сервер виставляє їх за положенням «хмар небезпеки»: де зараз летять цілі відповідного типу (шахеди та нетипізовані цілі - біт 5, бандероль або інша крилата ракета - біт 6, Rak (балістика) - біт 8, КАБ - біт 7, розвідувальні дрони - біт 10, РСЗВ - біт 1; біт 1 також виставляється за типом тривоги ARTILLERY з джерела, обидва джерела об'єднуються). Біт з'являється, коли хмара зайшла в район (або в міста Київ, Харків, Запоріжжя, які мають окремі тривоги), і знімається, коли хмара пішла (з витримкою близько хвилини, щоб не мигтіло). Типи небезпеки можуть надходити і без бітів рівня (11, 12): офіційні прошивки JAAM показують регіон лише тоді, коли виставлено біт 11 або 12, а біти типу використовують, щоб показати, про що ця тривога. Власний клієнт сам вирішує, як показувати регіон, що має лише біти типу небезпеки.

  • (0xA1) Регіон із flags = 0 означає, що тривога там закінчилась: приберіть його зі свого стану.
  • Регіон, якого немає в пакеті, не змінився.
  • Контроль цілісності. Кожен діф-пакет має hash_actual (сума байтів його записів mod 65536) та hash_previous (це hash_actual попереднього пакета). Якщо hash_previous нового пакета не збігається з hash_actual останнього отриманого - ви пропустили пакет: ваш стан недостовірний, перепідключіться (за правилами перепідключення), щоб отримати повний стан. Для найпершого пакета після підключення перевірку не робіть - просто запам'ятайте його hash_actual.

Правила розбору:

  1. Перевіряйте довжину: якщо тіло записів не ділиться на 4, пропустіть кадр (не падайте і не розривайте з'єднання).
  2. Невідомий тип - ігноруйте.
  3. Один регіон може з'явитися в кількох пакетах: пізніший пакет перезаписує попередній стан цього регіону.

Готовий розбір (перевірений на пакетах, які будує сервер):

import struct

ALERT_FLAGS = {
    0: "air", 1: "artillery", 2: "urban_fights", 3: "chemical", 4: "nuclear",
    5: "drones", 6: "missile", 7: "kab", 8: "ballistic", 9: "explosion", 10: "recon_drone",
    11: "level_yellow", 12: "level_red",
}


class AlertState:
    def __init__(self):
        self.alerts = {}       # region_id -> flags (регіони без тривог тут відсутні)
        self.last_hash = None  # hash_actual останнього пакета
        self.events = []       # останні 0xA2: [(region_id, flags)], одноразові події, не стан

    def feed(self, msg: bytes) -> bool:
        """Повертає False, якщо треба перепідключитись (пропущено пакет)."""
        if len(msg) >= 1 and msg[0] == 0xA2:
            if (len(msg) - 1) % 4 == 0:
                self.events = list(struct.iter_unpack("<HH", msg[1:]))
            return True  # 0xA2: без хешів і без стану, лише подія
        if len(msg) < 5 or msg[0] != 0xA1:
            return True  # невідомий тип або надто короткий кадр ігноруємо
        h_actual, h_prev = struct.unpack("<HH", msg[1:5])
        body = msg[5:]
        if len(body) % 4:
            return True  # битий кадр ігноруємо, з'єднання не рвемо
        if self.last_hash is not None and h_prev != self.last_hash:
            return False  # пропущено пакет - стан тривог недостовірний
        for region_id, flags in struct.iter_unpack("<HH", body):
            if flags:
                self.alerts[region_id] = flags
            else:
                self.alerts.pop(region_id, None)
        self.last_hash = h_actual
        return True

Ping/pong

Сервер сам надсилає ping кожні 20 секунд і чекає на pong до 20 секунд. Без відповіді з'єднання закривається. У більшості бібліотек відповідь автоматична, але цикл читання не має блокуватись. Не імітуйте pong текстовим повідомленням.

  • Це стандартні службові кадри WebSocket (control frames). У більшості бібліотек клієнт відповідає на ping автоматично, тож вручну нічого робити не потрібно - переконайтесь, що ваша бібліотека це вміє і що цикл читання повідомлень не заблокований (інакше pong не буде надіслано).
  • Не надсилайте власні ping частіше, ніж раз на 20 секунд - у цьому немає потреби.
  • Якщо ви самі не бачили жодних даних і ping довго - вважайте з'єднання мертвим і перепідключіться за правилами нижче.

Перепідключення

Найчастіша причина блокування

Клієнт, який після розриву одразу підключається знову в циклі без затримки, буде заблокований: спершу сервіс чи пристрій, потім IP. За одним сервісом може стояти багато клієнтів, і блокування б'є по всіх.

Затримка між спробами зростає експоненційно: починайте з 4 с і подвоюйте до стелі 128 с, додаючи випадкове відхилення ±20%. Скидайте її до 4 с лише після сесії, що пропрацювала не менше 60 секунд.

Також:

  • Не відкривайте кілька паралельних з'єднань з одного екземпляра клієнта.
  • Після відмови або закриття з кодом 1008 чи 4403 не повторюйте спробу одразу: збільште затримку до максимуму (а для bad_hello спершу виправте hello).
  • Розрив у момент втрати мережі - нормальна ситуація; чекайте на відновлення мережі, а не підключайтесь у цикл.

Мінімальний клієнт (Python)

import asyncio
import json
import random
import time
import uuid
from pathlib import Path

import websockets

URL = "wss://ws.jaam.net.ua/data_service_v1"
CLIENT_ID_FILE = Path("client_id.txt")  # UUID екземпляра: згенерувати один раз і зберігати

if not CLIENT_ID_FILE.exists():
    CLIENT_ID_FILE.write_text(str(uuid.uuid4()))

HELLO = "hello:" + json.dumps({
    "service_id": "my-bot",            # один на весь ваш сервіс
    "client_id": CLIENT_ID_FILE.read_text().strip(),
    "name": "Мій бот",
    "website": "https://bot.example",
    "contact": "@owner_tg",
    "version": "1.0.0",
}, ensure_ascii=False)


async def run():
    delay = 4
    while True:
        started = time.monotonic()
        try:
            # ping надсилає сервер, pong відповідає бібліотека
            async with websockets.connect(URL, ping_interval=None) as ws:
                await ws.send(HELLO)
                state = AlertState()  # клас AlertState з розділу "Що надсилає сервер"
                async for message in ws:
                    if isinstance(message, bytes) and state.feed(message) is False:
                        break  # пропущено пакет тривог - перепідключення за правилами backoff
        except websockets.ConnectionClosed as e:
            if e.rcvd and e.rcvd.code in (1008, 4403):
                delay = 128  # відмова сервера: не повторюємо одразу
        except OSError:
            pass
        if time.monotonic() - started >= 60:
            delay = 4  # з'єднання трималось, не штрафуємо себе
        # jitter ±20%, кратно 2 с, не вище стелі 128 с
        await asyncio.sleep(min(128, round(delay * random.uniform(0.8, 1.2) / 2) * 2))
        delay = min(delay * 2, 128)


asyncio.run(run())

Чекліст