WebSocket API¶
Тривоги в реальному часі: одне довге з'єднання, по якому сервер сам надсилає зміни.
https://jaam.net.uawss://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 разів на хвилину.
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 |
Життєвий цикл з'єднання¶
hello, потім безперервний цикл.Підключились один раз — і не розривайте його після початкових даних. Схема «підключився → отримав → відключився → через хвилину знову» є зловживанням, за яке блокують. Якщо потрібні дані раз на деякий час, використовуйте REST із дозволеною частотою.
Перший пакет hello¶
Одразу після з'єднання клієнт сам надсилає одне текстове повідомлення: hello: і JSON-об'єкт.
# одне текстове повідомлення 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 символи |
Коди закриття¶
| Код і причина | Що означає | Що робити |
|---|---|---|
1008 bad_hello:<поле> | Поле відсутнє або некоректне | Виправте клієнт, не повторюйте в циклі |
1008 hello_timeout | hello не надійшов за 10 с | Надсилайте одразу після з'єднання |
4403 service_blocked | Сервіс заблоковано | Не перепідключайтесь у циклі; зв'яжіться з адміністратором |
1008 ip_blocked | IP заблоковано під час сесії | Не перепідключайтесь у циклі |
Як зберігати client_id¶
client_id ідентифікує один фізичний екземпляр: пристрій, інсталяцію, браузер. Новий id щоразу перетворить один пристрій на сотні «клієнтів». Згенеруйте UUID один раз і надсилайте той самий після перезапусків, перепідключень і оновлень.
| Де працює клієнт | Де зберігати |
|---|---|
| Сторінка чи віджет у браузері | localStorage. Не sessionStorage і не cookie |
| Скрипт, бот, Raspberry Pi, Home Assistant | Файл у каталозі даних. У Docker — на томі (volume) |
| Прошивка ESP32 | NVS (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¶
Перший пакет після підключення — повний стан, далі лише змінені регіони. 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.
Правила розбору:
- Перевіряйте довжину: якщо тіло записів не ділиться на 4, пропустіть кадр (не падайте і не розривайте з'єднання).
- Невідомий тип - ігноруйте.
- Один регіон може з'явитися в кількох пакетах: пізніший пакет перезаписує попередній стан цього регіону.
Готовий розбір (перевірений на пакетах, які будує сервер):
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())