@smartico/public-api 0.0.343 → 0.0.345

package/docs/native/PROTOCOL.md

@@ -8,6 +8,14 @@ This document describes the low-level protocol for communicating with Smartico b
 
 ## Table of Contents
 
+- [Connection Lifecycle](#connection-lifecycle)
+  - [Ping / Pong](#ping--pong)
+  - [Init](#init)
+  - [Identify](#identify)
+  - [Login](#login)
+  - [Logout](#logout)
+- [Common Message Fields](#common-message-fields)
+
 ### Server Initiated Messages
 - [Overview](#server-initiated-messages)
 - [CLIENT_PUBLIC_PROPERTIES_CHANGED_EVENT](#client_public_properties_changed_event)
@@ -16,13 +24,17 @@ This document describes the low-level protocol for communicating with Smartico b
 - [SAW_SPINS_COUNT_PUSH](#saw_spins_count_push)
 - [SAW_SHOW_SPIN_PUSH](#saw_show_spin_push)
 - [JP_WIN_PUSH](#jp_win_push)
+- [SAW_PRIZE_DROP_WIN_PUSH](#saw_prize_drop_win_push)
+- [CLIENT_EXECUTE_DEEPLINK_EVENT](#client_execute_deeplink_event)
+- [CLIENT_EXECUTE_JS_EVENT](#client_execute_js_event)
 
 ### API Methods
 
 #### User
 - [getUserGamificationInfo](#getusergamificationinfo)
-- [checkSegmentMatch](#checksegmentmatch)
 - [checkSegmentListMatch](#checksegmentlistmatch)
+- [setAvatar](#setavatar)
+- [setCustomUsername](#setcustomusername)
 
 #### Levels
 - [getLevels](#getlevels)
@@ -52,6 +64,9 @@ This document describes the low-level protocol for communicating with Smartico b
 - [playMiniGameBatch](#playminigamebatch)
 - [miniGameWinAcknowledge](#minigamewinacknowledge)
 - [getMiniGamesHistory](#getminigameshistory)
+- [acknowledgeMiniGameSpinPush](#acknowledgeminigamespinpush)
+- [miniGameWinAcknowledgeBatch](#minigamewinacknowledgebatch)
+- [prizeDropWinAcknowledge](#prizedropwinacknowledge)
 
 #### Tournaments
 - [getTournamentsList](#gettournamentslist)
@@ -77,6 +92,16 @@ This document describes the low-level protocol for communicating with Smartico b
 - [jackpotOptOut](#jackpotoptout)
 - [getJackpotWinners](#getjackpotwinners)
 - [getJackpotEligibleGames](#getjackpoteligiblegames)
+- [getJackpotLatestPots](#getjackpotlatestpots)
+
+#### Engagement Tracking
+- [reportEngagementImpression](#reportengagementimpression)
+- [reportEngagementAction](#reportengagementaction)
+- [reportEngagementFailed](#reportengagementfailed)
+- [trackActivity](#trackactivity)
+
+#### Push Notifications
+- [registerPushNotificationsToken](#registerpushnotificationstoken)
 
 #### Other
 - [getTranslations](#gettranslations)
@@ -92,6 +117,269 @@ This document describes the low-level protocol for communicating with Smartico b
 
 ---
 
+# Connection Lifecycle
+
+This section describes the mandatory sequence of messages required to establish a session with the Smartico backend. Native clients **must** implement this flow before calling any API methods.
+
+**Connection flow:**
+
+```
+1. Connect to WebSocket
+2. Send INIT (cid: 3)       → Receive INIT_RESPONSE (cid: 4)
+3. Send IDENTIFY (cid: 5)   → Receive IDENTIFY_RESPONSE (cid: 6)
+4. Send LOGIN (cid: 7)      → Receive LOGIN_RESPONSE (cid: 11)
+5. Session is now active — API methods can be called
+6. Maintain connection with PING/PONG keepalive
+7. When user logs out: Send LOGOUT (cid: 8) → Receive LOGOUT_RESPONSE (cid: 12)
+```
+
+---
+
+## Ping / Pong
+
+WebSocket keepalive mechanism. The server sends `PING` (cid: 1), the client must respond with `PONG` (cid: 2). Additionally, the client should send a proactive `PING` if no messages are received within **29 seconds** to prevent the connection from being dropped.
+
+**Server → Client:**
+
+```json
+{"cid": 1}
+```
+
+**Client → Server (response):**
+
+```json
+{"cid": 2}
+```
+
+> **Implementation note:** When any message is received from the server, reset the keepalive timer. If no messages arrive within 29 seconds, send `{"cid": 1}` proactively.
+
+---
+
+## Init
+
+First message after WebSocket connection is established. Identifies the label (operator) and brand.
+
+### Request
+
+**ClassId:** `3` (INIT)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `label_key` | `string` | Public API key for the label |
+| `brand_key` | `string` | Brand key (optional, `null` if not used) |
+| `device_id` | `string` | Unique device identifier (persisted across sessions) |
+
+**Example:**
+
+```json
+{
+  "cid": 3,
+  "label_key": "your_label_api_key",
+  "brand_key": null,
+  "device_id": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+### Response
+
+**ClassId:** `4` (INIT_RESPONSE)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `errCode` | `number` | Error code (`0` = success) |
+| `errMsg` | `string` | Error message (optional) |
+| `settings` | `object` | Label settings (key-value map) |
+| `products` | `number[]` | Enabled product types for this label |
+| `label_id` | `number` | Internal label ID |
+
+**Example:**
+
+```json
+{
+  "cid": 4,
+  "errCode": 0,
+  "settings": {
+    "PUBLIC_API_URL": "https://api.smartico.ai"
+  },
+  "products": [1, 2],
+  "label_id": 123
+}
+```
+
+> **Important:** Wait for a successful `INIT_RESPONSE` (errCode: 0) before sending `IDENTIFY`.
+
+---
+
+## Identify
+
+Identifies (authenticates) the user. Must be sent after a successful `INIT`.
+
+### Request
+
+**ClassId:** `5` (IDENTIFY)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ext_user_id` | `string` | External user ID (your system's user identifier) |
+| `hash` | `string` | HMAC authentication hash |
+| `ua` | `object` | User agent / device information (optional) |
+
+**Example:**
+
+```json
+{
+  "cid": 5,
+  "ext_user_id": "user_12345",
+  "hash": "a1b2c3d4e5f6..."
+}
+```
+
+### Response
+
+**ClassId:** `6` (IDENTIFY_RESPONSE)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `errCode` | `number` | Error code (`0` = success) |
+| `errMsg` | `string` | Error message (optional) |
+| `user_id` | `number` | Smartico internal user ID |
+| `ext_user_id` | `string` | External user ID (echoed back) |
+| `public_username` | `string` | User's display name |
+| `avatar_id` | `string` | User's current avatar ID |
+| `props` | `object` | User's public properties (points, level, balances) |
+| `pubic_username_set` | `boolean` | Whether the user has set a custom username |
+
+**Example:**
+
+```json
+{
+  "cid": 6,
+  "errCode": 0,
+  "user_id": 98765,
+  "ext_user_id": "user_12345",
+  "public_username": "Player123",
+  "avatar_id": "av_001",
+  "props": {
+    "ach_points_balance": 1500,
+    "ach_level_current": "Silver",
+    "ach_points_ever": 5000
+  },
+  "pubic_username_set": false
+}
+```
+
+> **Important:** Wait for a successful `IDENTIFY_RESPONSE` (errCode: 0) before sending `LOGIN` or any API methods.
+
+---
+
+## Login
+
+Sent after a successful `IDENTIFY` to report a user login event. Contains optional user-agent metadata.
+
+### Request
+
+**ClassId:** `7` (LOGIN)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `payload` | `object` | Optional metadata (user agent info, custom data) |
+
+**Example:**
+
+```json
+{
+  "cid": 7,
+  "payload": {
+    "ua_os_name": "iOS",
+    "ua_device_type": "mobile",
+    "ua_browser": "native"
+  }
+}
+```
+
+### Response
+
+**ClassId:** `11` (LOGIN_RESPONSE)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `errCode` | `number` | Error code (`0` = success) |
+| `errMsg` | `string` | Error message (optional) |
+
+**Example:**
+
+```json
+{
+  "cid": 11,
+  "errCode": 0
+}
+```
+
+---
+
+## Logout
+
+Logs the user out. After receiving a successful response, the client should forget user data and reconnect if needed.
+
+### Request
+
+**ClassId:** `8` (LOGOUT)
+
+No method-specific fields required.
+
+**Example:**
+
+```json
+{
+  "cid": 8
+}
+```
+
+### Response
+
+**ClassId:** `12` (LOGOUT_RESPONSE)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `errCode` | `number` | Error code (`0` = success) |
+| `errMsg` | `string` | Error message (optional) |
+
+**Example:**
+
+```json
+{
+  "cid": 12,
+  "errCode": 0
+}
+```
+
+> **Recommended action:** On successful logout, clear cached user data and reconnect the WebSocket to start a fresh session.
+
+---
+
+## Common Message Fields
+
+All **request** messages must include the following base fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cid` | `number` | ClassId — message type identifier |
+| `uuid` | `string` | Unique request identifier (used to match request with response) |
+| `ts` | `number` | Timestamp in milliseconds |
+
+All **response** messages include the following base fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cid` | `number` | ClassId — message type identifier |
+| `uuid` | `string` | Same identifier from the request |
+| `errCode` | `number` | Error code (`0` = success) |
+| `errMsg` | `string` | Error message (optional, present when `errCode` != 0) |
+
+> **Note:** These common fields are omitted from individual method descriptions below to avoid duplication. Only method-specific fields are listed.
+
+---
+
 # Server Initiated Messages
 
 Server initiated messages are sent by the server to the client without a prior request. The client should listen for these ClassIds and react accordingly (update UI, show notification, re-fetch data).
@@ -108,6 +396,9 @@ Unlike request/response methods, server initiated messages can arrive at any tim
 | `706` | SAW_SPINS_COUNT_PUSH | Spin count updated |
 | `707` | SAW_SHOW_SPIN_PUSH | Trigger to show mini-game |
 | `808` | JP_WIN_PUSH | Jackpot win notification |
+| `708` | SAW_PRIZE_DROP_WIN_PUSH | Prize drop win notification |
+| `105` | CLIENT_EXECUTE_DEEPLINK_EVENT | Execute deep link on client |
+| `107` | CLIENT_EXECUTE_JS_EVENT | Execute JavaScript on client |
 
 ---
 
@@ -223,25 +514,31 @@ Sent when the user's available spin count changes.
 
 ## SAW_SHOW_SPIN_PUSH
 
-Sent as a trigger to display a mini-game to the user (Spin-A-Wheel, Scratch Card, Slot, etc.).
+Sent as a trigger to display a mini-game to the user (Spin-A-Wheel, Scratch Card, Gift Box, etc.).
 
 **ClassId:** `707`
 
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cid` | `number` | Message type identifier |
+| `pending_message_id` | `number` | ID of the pending message that triggered this push |
+| `saw_template_id` | `number` | ID of the mini-game template to display |
+| `saw_game_type_id` | `number` | Game type: `1` = SpinAWheel, `2` = ScratchCard, `3` = MatchX, `4` = GiftBox, `5` = PrizeDrop, `6` = Quiz, `7` = LootboxWeekdays, `8` = LootboxCalendarDays, `9` = TreasureHunt, `10` = Voyager, `11` = Plinko, `12` = CoinFlip |
+
 **Example:**
 
 ```json
 {
-  "cid": 707
+  "cid": 707,
+  "pending_message_id": 456,
+  "saw_template_id": 123,
+  "saw_game_type_id": 1
 }
 ```
 
-**Fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | Message type identifier |
-
-**Recommended action:** Fetch mini-game templates and display the appropriate game modal/screen.
+**Recommended action:** Use `saw_template_id` and `saw_game_type_id` to display the appropriate mini-game UI to the user.
 
 ---
 
@@ -283,6 +580,104 @@ Sent when a jackpot is won (can be the current user or another player).
 
 ---
 
+## SAW_PRIZE_DROP_WIN_PUSH
+
+Sent when a prize drop is won by the user.
+
+**ClassId:** `708`
+
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cid` | `number` | Message type identifier |
+| `request_id` | `string` | Unique request ID (GUID) |
+| `saw_template_id` | `number` | Mini-game template ID |
+| `saw_prize` | `object` | Prize details (SAWPrize object) |
+| `saw_template` | `object` | Template details (SAWTemplate object) |
+| `pending_message_id` | `number` | ID of the pending message |
+
+**Example:**
+
+```json
+{
+  "cid": 708,
+  "request_id": "550e8400-e29b-41d4-a716-446655440000",
+  "saw_template_id": 123,
+  "saw_prize": { "saw_prize_id": 1, "prize_value": 100 },
+  "saw_template": { "saw_template_id": 123, "saw_game_type_id": 5 },
+  "pending_message_id": 456
+}
+```
+
+**Recommended action:** Display prize drop win notification and call `prizeDropWinAcknowledge` to acknowledge.
+
+---
+
+## CLIENT_EXECUTE_DEEPLINK_EVENT
+
+Server-initiated event to execute a deep link on the client.
+
+**ClassId:** `105`
+
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cid` | `number` | Message type identifier |
+| `engagement_uid` | `string` | Engagement unique ID |
+| `engagement_id` | `number` | Engagement ID |
+| `root_audience_id` | `number` | Root audience ID |
+| `payload` | `object` | Contains `dp` field with the deep link URL |
+
+**Example:**
+
+```json
+{
+  "cid": 105,
+  "engagement_uid": "eng-001",
+  "engagement_id": 1,
+  "root_audience_id": 1,
+  "payload": { "dp": "myapp://promotions/summer" }
+}
+```
+
+**Recommended action:** Report impression via ClassId 103, then navigate to the deep link URL.
+
+---
+
+## CLIENT_EXECUTE_JS_EVENT
+
+Server-initiated event to execute JavaScript code on the client. Native clients should handle this appropriately or ignore.
+
+**ClassId:** `107`
+
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cid` | `number` | Message type identifier |
+| `engagement_uid` | `string` | Engagement unique ID |
+| `engagement_id` | `number` | Engagement ID |
+| `root_audience_id` | `number` | Root audience ID |
+| `script` | `string` | JavaScript code to execute |
+
+**Example:**
+
+```json
+{
+  "cid": 107,
+  "engagement_uid": "eng-001",
+  "engagement_id": 1,
+  "root_audience_id": 1,
+  "script": "console.log('hello')"
+}
+```
+
+**Recommended action:** Report impression via ClassId 103. For native clients, evaluate if the script can be handled natively or ignore.
+
+---
+
 # API Methods
 
 ## User
@@ -295,11 +690,7 @@ Get user's gamification data including points, level, balances and counters.
 
 **ClassId:** `527` (GET_ACHIEVEMENT_USER_REQUEST)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `527` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+No method-specific fields. Send only the common fields (see [Common Message Fields](#common-message-fields)).
 
 **Example:**
 
@@ -317,10 +708,6 @@ Get user's gamification data including points, level, balances and counters.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `528` |
-| `uuid` | `string` | Request identifier (matches request) |
-| `errCode` | `number` | Error code (`0` = success) |
-| `errMsg` | `string` | Error message (if any) |
 | `points_balance` | `number` | Current points balance |
 | `gems_balance` | `number` | Current gems balance |
 | `diamonds_balance` | `number` | Current diamonds balance |
@@ -354,14 +741,18 @@ Get user's gamification data including points, level, balances and counters.
 
 ---
 
-### checkSegmentMatch
+### checkSegmentListMatch
 
-Check if the current user belongs to a specific segment.
+Check if the current user belongs to one or more segments. Pass a single ID or multiple IDs in the array.
 
 #### Request
 
 **ClassId:** `161`
 
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `segment_id` | `number[]` | ✓ | Array of segment IDs to check |
+
 **Example:**
 
 ```json
@@ -369,25 +760,18 @@ Check if the current user belongs to a specific segment.
   "cid": 161,
   "uuid": "550e8400-e29b-41d4-a716-446655440000",
   "ts": 1704067200000,
-  "segment_id": [42]
+  "segment_id": [1, 2, 3]
 }
 ```
 
-**Fields:**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `cid` | `number` | ✓ | Message type identifier |
-| `uuid` | `string` | ✓ | Unique request identifier |
-| `ts` | `number` | ✓ | Timestamp in milliseconds |
-| `segment_id` | `number[]` | ✓ | Array with single segment ID |
-
----
-
 #### Response
 
 **ClassId:** `162`
 
+| Field | Type | Description |
+|-------|------|-------------|
+| `segments` | [`TSegmentCheckResult[]`](../api/interfaces/TSegmentCheckResult.md) | Array of segment check results |
+
 **Example:**
 
 ```json
@@ -396,79 +780,101 @@ Check if the current user belongs to a specific segment.
   "errCode": 0,
   "errMsg": null,
   "segments": [
-    { "segment_id": 42, "is_matching": true }
+    { "segment_id": 1, "is_matching": true },
+    { "segment_id": 2, "is_matching": false },
+    { "segment_id": 3, "is_matching": true }
   ]
 }
 ```
 
-**Fields:**
+---
+
+### setAvatar
+
+Set user's avatar.
+
+#### Request
+
+**ClassId:** `157`
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | Message type identifier |
-| `errCode` | `number` | Error code. `0` = success |
-| `errMsg` | `string` | Error message (if any) |
-| `segments` | [`TSegmentCheckResult[]`](../api/interfaces/TSegmentCheckResult.md) | Array of segment check results |
+| `avatar_id` | `string` | Avatar ID to set |
+| `skip_change_event` | `boolean` | If true, skips the avatar changed event (optional) |
 
----
+**Example:**
 
-### checkSegmentListMatch
+```json
+{
+  "cid": 157,
+  "uuid": "abc-123",
+  "ts": 1699999999999,
+  "avatar_id": "av_001"
+}
+```
 
-Check if the current user belongs to multiple segments.
+#### Response
 
-#### Request
+**ClassId:** `158`
 
-**ClassId:** `161`
+| Field | Type | Description |
+|-------|------|-------------|
+| `avatar_id` | `string` | Updated avatar ID |
 
 **Example:**
 
 ```json
 {
-  "cid": 161,
-  "uuid": "550e8400-e29b-41d4-a716-446655440000",
-  "ts": 1704067200000,
-  "segment_id": [1, 2, 3]
+  "cid": 158,
+  "uuid": "abc-123",
+  "errCode": 0,
+  "avatar_id": "av_001"
 }
 ```
 
-**Fields:**
+---
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `cid` | `number` | ✓ | Message type identifier |
-| `uuid` | `string` | ✓ | Unique request identifier |
-| `ts` | `number` | ✓ | Timestamp in milliseconds |
-| `segment_id` | `number[]` | ✓ | Array of segment IDs to check |
+### setCustomUsername
 
----
+Set user's custom display name.
 
-#### Response
+#### Request
 
-**ClassId:** `162`
+**ClassId:** `159`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `public_username_custom` | `string` | Custom username to set |
 
 **Example:**
 
 ```json
 {
-  "cid": 162,
-  "errCode": 0,
-  "errMsg": null,
-  "segments": [
-    { "segment_id": 1, "is_matching": true },
-    { "segment_id": 2, "is_matching": false },
-    { "segment_id": 3, "is_matching": true }
-  ]
+  "cid": 159,
+  "uuid": "abc-123",
+  "ts": 1699999999999,
+  "public_username_custom": "SuperPlayer"
 }
 ```
 
-**Fields:**
+#### Response
+
+**ClassId:** `160`
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | Message type identifier |
-| `errCode` | `number` | Error code. `0` = success |
-| `errMsg` | `string` | Error message (if any) |
-| `segments` | [`TSegmentCheckResult[]`](../api/interfaces/TSegmentCheckResult.md) | Array of segment check results |
+| `public_username_custom` | `string` | Updated custom username |
+
+**Example:**
+
+```json
+{
+  "cid": 160,
+  "uuid": "abc-123",
+  "errCode": 0,
+  "public_username_custom": "SuperPlayer"
+}
+```
 
 ---
 
@@ -494,11 +900,7 @@ Get list of all levels defined in the system.
 
 **Fields:**
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `cid` | `number` | ✓ | Message type identifier |
-| `uuid` | `string` | ✓ | Unique request identifier |
-| `ts` | `number` | ✓ | Timestamp in milliseconds |
+No method-specific fields. Send only the common fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -548,9 +950,6 @@ Get list of all levels defined in the system.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | Message type identifier |
-| `errCode` | `number` | Error code. `0` = success |
-| `errMsg` | `string` | Error message (if any) |
 | `levels` | [`Level[]`](../api/interfaces/Level.md) | Array of level objects |
 
 ---
@@ -567,11 +966,7 @@ Get all missions and badges for the current user.
 
 **ClassId:** `502` (GET_ACHIEVEMENT_MAP_REQUEST)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `502` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+No method-specific fields. Send only the common fields (see [Common Message Fields](#common-message-fields)).
 
 **Example:**
 
@@ -589,10 +984,6 @@ Get all missions and badges for the current user.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `503` |
-| `uuid` | `string` | Request identifier (matches request) |
-| `errCode` | `number` | Error code (`0` = success) |
-| `errMsg` | `string` | Error message (if any) |
 | `achievements` | [`UserAchievement[]`](../api/interfaces/UserAchievement.md) | Array of achievements (missions + badges) |
 
 **Example:**
@@ -632,6 +1023,7 @@ Get all missions and badges for the current user.
     }
   ]
 }
+```
 
 ---
 
@@ -645,21 +1037,13 @@ Opt-in to a mission that requires opt-in.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `525` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
-| `ach_id` | `number` | Mission ID |
+| `achievementId` | `number` | Mission ID |
 
 #### Response
 
 **ClassId:** `526` (MISSION_OPTIN_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `526` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
-| `errMsg` | `string` | Error message (if any) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -673,9 +1057,6 @@ Claim reward for a completed mission.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `539` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `ach_id` | `number` | Mission ID |
 | `ach_completed_id` | `number` | Completion record ID |
 
@@ -683,12 +1064,7 @@ Claim reward for a completed mission.
 
 **ClassId:** `540` (ACHIEVEMENT_CLAIM_PRIZE_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `540` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
-| `errMsg` | `string` | Error message (if any) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -700,11 +1076,7 @@ Get mission and badge categories.
 
 **ClassId:** `537` (GET_ACH_CATEGORIES_REQUEST)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `537` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+No method-specific fields. Send only the common fields (see [Common Message Fields](#common-message-fields)).
 
 #### Response
 
@@ -712,9 +1084,6 @@ Get mission and badge categories.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `538` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `categories` | [`AchCategory[]`](../api/interfaces/AchCategory.md) | Array of categories |
 
 ---
@@ -729,11 +1098,7 @@ Get custom UI sections.
 
 **ClassId:** `523` (GET_CUSTOM_SECTIONS_REQUEST)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `523` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+No method-specific fields. Send only the common fields (see [Common Message Fields](#common-message-fields)).
 
 #### Response
 
@@ -741,9 +1106,6 @@ Get custom UI sections.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `524` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `customSections` | `object` | Map of section ID to [`UICustomSection`](../api/interfaces/UICustomSection.md) |
 
 ---
@@ -758,11 +1120,7 @@ Get all bonuses for the current user.
 
 **ClassId:** `600` (GET_BONUSES_REQUEST)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `600` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+No method-specific fields. Send only the common fields (see [Common Message Fields](#common-message-fields)).
 
 **Example:**
 
@@ -780,10 +1138,6 @@ Get all bonuses for the current user.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `601` |
-| `uuid` | `string` | Request identifier (matches request) |
-| `errCode` | `number` | Error code (`0` = success) |
-| `errMsg` | `string` | Error message (if any) |
 | `bonuses` | [`Bonus[]`](../api/interfaces/Bonus.md) | Array of bonus objects |
 
 **Example:**
@@ -824,9 +1178,6 @@ Claim a bonus by its ID.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `602` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `bonusId` | `number` | ID of the bonus to claim |
 
 **Example:**
@@ -846,10 +1197,6 @@ Claim a bonus by its ID.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `603` |
-| `uuid` | `string` | Request identifier (matches request) |
-| `errCode` | `number` | Error code (`0` = success) |
-| `errMsg` | `string` | Error message (if any) |
 | `success` | `boolean` | Whether the claim was successful |
 
 **Example:**
@@ -875,11 +1222,7 @@ Get all available store items.
 
 **ClassId:** `509` (GET_SHOP_ITEMS_REQUEST)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `509` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+No method-specific fields. Send only the common fields (see [Common Message Fields](#common-message-fields)).
 
 #### Response
 
@@ -887,9 +1230,6 @@ Get all available store items.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `510` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `items` | [`StoreItem[]`](../api/interfaces/StoreItem.md) | Array of store items |
 
 ---
@@ -904,21 +1244,13 @@ Purchase a store item.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `511` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `itemId` | `number` | ID of the item to buy |
 
 #### Response
 
 **ClassId:** `512` (BUY_SHOP_ITEM_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `512` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
-| `errMsg` | `string` | Error message (if any) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -930,11 +1262,7 @@ Get store categories.
 
 **ClassId:** `515` (GET_SHOP_CATEGORIES_REQUEST)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `515` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+No method-specific fields. Send only the common fields (see [Common Message Fields](#common-message-fields)).
 
 #### Response
 
@@ -942,9 +1270,6 @@ Get store categories.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `516` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `categories` | [`StoreCategory[]`](../api/interfaces/StoreCategory.md) | Array of categories |
 
 ---
@@ -959,9 +1284,6 @@ Get user's purchase history.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `541` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `limit` | `number` | Max items to return (default 20) |
 | `offset` | `number` | Offset for pagination |
 
@@ -971,9 +1293,6 @@ Get user's purchase history.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `542` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `items` | [`StoreItem[]`](../api/interfaces/StoreItem.md) | Array of purchased items |
 
 ---
@@ -988,11 +1307,7 @@ Get all available mini-games (spin wheels, scratch cards, etc.).
 
 **ClassId:** `700` (SAW_GET_SPINS_REQUEST)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `700` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+No method-specific fields. Send only the common fields (see [Common Message Fields](#common-message-fields)).
 
 #### Response
 
@@ -1000,9 +1315,6 @@ Get all available mini-games (spin wheels, scratch cards, etc.).
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `701` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `templates` | [`SAWTemplate[]`](../api/interfaces/SAWTemplate.md) | Array of mini-game templates |
 
 ---
@@ -1017,20 +1329,27 @@ Play a mini-game and get prize.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `702` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+| `request_id` | `string` | Client-generated unique request ID (GUID) |
 | `saw_template_id` | `number` | Mini-game template ID |
 
+**Example:**
+
+```json
+{
+  "cid": 702,
+  "uuid": "abc-123",
+  "ts": 1699999999999,
+  "request_id": "550e8400-e29b-41d4-a716-446655440000",
+  "saw_template_id": 123
+}
+```
+
 #### Response
 
 **ClassId:** `703` (SAW_DO_SPIN_RESPONSE)
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `703` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `saw_prize_id` | `number` | Won prize ID |
 | `request_id` | `string` | Request ID for acknowledgement |
 
@@ -1046,9 +1365,6 @@ Play a mini-game multiple times in a single request.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `712` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `spins` | `array` | Array of spin objects with `request_id` (string) and `saw_template_id` (number) |
 
 #### Response
@@ -1057,10 +1373,18 @@ Play a mini-game multiple times in a single request.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `713` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
-| `spins` | `array` | Array of spin results, each containing prize information |
+| `results` | `SAWDoSpinResponse[]` | Array of spin results |
+
+Each item in `results`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `request_id` | `string` | Request ID matching the request |
+| `saw_prize_id` | `number` | Won prize ID |
+| `errCode` | `number` | Error code for this spin (`0` = success) |
+| `errMsg` | `string` | Error message (if any) |
+| `jackpot_amount` | `number` | Jackpot amount if won jackpot prize (optional) |
+| `first_spin_in_period` | `number` | Whether this is the first spin in the period |
 
 #### Example
 
@@ -1078,76 +1402,182 @@ Play a mini-game multiple times in a single request.
 }
 ```
 
-**Response:**
+**Response:**
+```json
+{
+  "cid": 713,
+  "uuid": "batch-123",
+  "errCode": 0,
+  "results": [
+    { "request_id": "spin-1", "saw_prize_id": 10, "errCode": 0, "first_spin_in_period": 1 },
+    { "request_id": "spin-2", "saw_prize_id": 5, "errCode": 0, "first_spin_in_period": 0 },
+    { "request_id": "spin-3", "saw_prize_id": 10, "errCode": 0, "first_spin_in_period": 0 }
+  ]
+}
+```
+
+---
+
+### miniGameWinAcknowledge
+
+Acknowledge a mini-game win. Should be called after displaying the win result to the user.
+
+#### Request
+
+**ClassId:** `704` (SAW_AKNOWLEDGE_REQUEST)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `request_id` | `string` | Request ID from the spin response |
+
+#### Response
+
+**ClassId:** `705` (SAW_AKNOWLEDGE_RESPONSE)
+
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
+
+---
+
+### getMiniGamesHistory
+
+Get mini-game play history.
+
+#### Request
+
+**ClassId:** `716` (GET_SAW_HISTORY_REQUEST)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `limit` | `number` | Max items to return |
+| `offset` | `number` | Offset for pagination |
+| `saw_template_id` | `number` | Filter by template ID (optional) |
+
+#### Response
+
+**ClassId:** `717` (GET_SAW_HISTORY_RESPONSE)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `prizes` | [`SAWPrizesHistory[]`](../api/interfaces/SAWPrizesHistory.md) | Array of history items |
+| `hasMore` | `boolean` | Whether more items are available for pagination |
+
+---
+
+### acknowledgeMiniGameSpinPush
+
+Acknowledge a mini-game spin push. Sent after handling `SAW_SHOW_SPIN_PUSH` (707) to confirm the spin push was processed. Fire-and-forget, no response expected.
+
+#### Request
+
+**ClassId:** `711`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `saw_template_id` | `number` | Mini-game template ID |
+| `pending_message_id` | `number` | Pending message ID from the push |
+
+**Example:**
+
 ```json
 {
-  "cid": 713,
-  "uuid": "batch-123",
-  "errCode": 0,
-  "spins": [
-    { "request_id": "spin-1", "prize_type": 1, "prize_value": 100 },
-    { "request_id": "spin-2", "prize_type": 2, "prize_value": 50 },
-    { "request_id": "spin-3", "prize_type": 1, "prize_value": 200 }
-  ]
+  "cid": 711,
+  "uuid": "abc-123",
+  "ts": 1699999999999,
+  "saw_template_id": 123,
+  "pending_message_id": 456
 }
 ```
 
 ---
 
-### miniGameWinAcknowledge
+### miniGameWinAcknowledgeBatch
 
-Acknowledge a mini-game win. Should be called after displaying the win result to the user.
+Acknowledge multiple mini-game wins at once. Used after `playMiniGameBatch`.
 
 #### Request
 
-**ClassId:** `704` (SAW_AKNOWLEDGE_REQUEST)
+**ClassId:** `714`
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `704` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
-| `request_id` | `string` | Request ID from the spin response |
+| `request_ids` | `string[]` | Array of request IDs to acknowledge |
+
+**Example:**
+
+```json
+{
+  "cid": 714,
+  "uuid": "ack-batch-123",
+  "ts": 1699999999999,
+  "request_ids": ["spin-1", "spin-2", "spin-3"]
+}
+```
 
 #### Response
 
-**ClassId:** `705` (SAW_AKNOWLEDGE_RESPONSE)
+**ClassId:** `715`
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `705` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
+| `results` | `array` | Array of acknowledgement results |
+
+Each item in `results`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `request_id` | `string` | Request ID |
+| `errCode` | `number` | Error code for this acknowledgement |
+| `errMessage` | `string` | Error message (optional) |
+
+**Example:**
+
+```json
+{
+  "cid": 715,
+  "uuid": "ack-batch-123",
+  "errCode": 0,
+  "results": [
+    { "request_id": "spin-1", "errCode": 0 },
+    { "request_id": "spin-2", "errCode": 0 },
+    { "request_id": "spin-3", "errCode": 0 }
+  ]
+}
+```
 
 ---
 
-### getMiniGamesHistory
+### prizeDropWinAcknowledge
 
-Get mini-game play history.
+Acknowledge a prize drop win. Should be called after receiving `SAW_PRIZE_DROP_WIN_PUSH` (708).
 
 #### Request
 
-**ClassId:** `716` (GET_SAW_HISTORY_REQUEST)
+**ClassId:** `709`
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `716` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
-| `limit` | `number` | Max items to return |
-| `offset` | `number` | Offset for pagination |
-| `saw_template_id` | `number` | Filter by template ID (optional) |
+| `request_id` | `string` | Request ID from the prize drop push (GUID) |
+| `pending_message_id` | `number` | Pending message ID from the push |
+| `claim_required` | `boolean` | Whether claim is required |
+
+**Example:**
+
+```json
+{
+  "cid": 709,
+  "uuid": "abc-123",
+  "ts": 1699999999999,
+  "request_id": "550e8400-e29b-41d4-a716-446655440000",
+  "pending_message_id": 456,
+  "claim_required": false
+}
+```
 
 #### Response
 
-**ClassId:** `717` (GET_SAW_HISTORY_RESPONSE)
+**ClassId:** `710`
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `717` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
-| `history` | [`SAWPrizesHistory[]`](../api/interfaces/SAWPrizesHistory.md) | Array of history items |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -1161,11 +1591,7 @@ Get all active tournament instances.
 
 **ClassId:** `517` (GET_TOURNAMENT_LOBBY_REQUEST)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `517` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+No method-specific fields. Send only the common fields (see [Common Message Fields](#common-message-fields)).
 
 #### Response
 
@@ -1173,9 +1599,6 @@ Get all active tournament instances.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `518` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `tournaments` | [`Tournament[]`](../api/interfaces/Tournament.md) | Array of tournaments |
 
 ---
@@ -1190,10 +1613,7 @@ Get detailed information about a tournament instance including leaderboard.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `519` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
-| `tournament_instance_id` | `number` | Tournament instance ID |
+| `tournamentInstanceId` | `number` | Tournament instance ID |
 
 #### Response
 
@@ -1201,9 +1621,6 @@ Get detailed information about a tournament instance including leaderboard.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `520` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `tournamentInfo` | [`GetTournamentInfoResponse.tournamentInfo`](../api/interfaces/GetTournamentInfoResponse.md) | Tournament info with players |
 | `userPosition` | [`TournamentPlayer`](../api/interfaces/TournamentPlayer.md) | Current user's position |
 | `prizeStructure` | `object` | Prize structure with `prizes` array |
@@ -1220,21 +1637,13 @@ Register user in a tournament.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `521` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
-| `tournament_instance_id` | `number` | Tournament instance ID |
+| `tournamentInstanceId` | `number` | Tournament instance ID |
 
 #### Response
 
 **ClassId:** `522` (TOURNAMENT_REGISTER_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `522` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
-| `errMsg` | `string` | Error message (if any) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -1250,11 +1659,9 @@ Get leaderboard for a specific period type.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `505` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
-| `period_type` | `number` | Period type: `1` = Daily, `2` = Weekly, `3` = Monthly |
-| `get_previous_period` | `boolean` | Get previous period instead of current |
+| `period_type_id` | `number` | Period type: `1` = Daily, `2` = Weekly, `3` = Monthly (optional, if not set returns all boards) |
+| `snapshot_offset` | `number` | `0` = current period, `1` = previous period, `2` = period before previous, etc. |
+| `include_users` | `boolean` | Whether to include user details (optional) |
 
 #### Response
 
@@ -1262,9 +1669,6 @@ Get leaderboard for a specific period type.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `506` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `leaders` | [`LeaderBoardUserT[]`](../api/interfaces/LeaderBoardUserT.md) | Array of leaderboard entries |
 | `user_position` | `number` | Current user's position |
 | `user_points` | `number` | Current user's points |
@@ -1283,12 +1687,9 @@ Get user's inbox messages.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `513` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
-| `from` | `number` | Start index (default 0) |
-| `to` | `number` | End index (default 20) |
-| `only_favorite` | `boolean` | Filter favorites only |
+| `limit` | `number` | Max messages to return (default 20) |
+| `offset` | `number` | Offset for pagination (default 0) |
+| `starred_only` | `boolean` | Filter favorites only |
 | `category_id` | `number` | Filter by category |
 | `read_status` | `number` | Filter by read status |
 
@@ -1298,10 +1699,7 @@ Get user's inbox messages.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `514` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
-| `messages` | [`InboxMessage[]`](../api/interfaces/InboxMessage.md) | Array of messages |
+| `log` | [`InboxMessage[]`](../api/interfaces/InboxMessage.md) | Array of messages |
 | `unread_count` | `number` | Total unread count |
 
 ---
@@ -1316,20 +1714,13 @@ Mark an inbox message as read.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `529` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
-| `message_guid` | `string` | Message GUID |
+| `engagement_uid` | `string` | Message engagement UID |
 
 #### Response
 
 **ClassId:** `530` (MARK_INBOX_READ_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `530` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -1343,21 +1734,14 @@ Mark/unmark an inbox message as favorite.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `531` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
-| `message_guid` | `string` | Message GUID |
-| `mark` | `boolean` | `true` to add, `false` to remove |
+| `engagement_uid` | `string` | Message engagement UID |
+| `is_starred` | `boolean` | `true` to add, `false` to remove |
 
 #### Response
 
 **ClassId:** `532` (MARK_INBOX_STARRED_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `532` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -1371,20 +1755,13 @@ Delete an inbox message.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `535` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
-| `message_guid` | `string` | Message GUID |
+| `engagement_uid` | `string` | Message engagement UID |
 
 #### Response
 
 **ClassId:** `536` (MARK_INBOX_DELETED_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `536` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -1392,7 +1769,7 @@ Delete an inbox message.
 
 Get unread inbox message count.
 
-> **Note:** This uses the same ClassId as `getInboxMessages`. The unread count is returned in the `unread_count` field of the response.
+> **Note:** This uses the same ClassId as `getInboxMessages`. The unread count is returned in the `unread_count` field of the response. Send a minimal request with `limit: 1` to get the count without fetching all messages.
 
 #### Request
 
@@ -1400,9 +1777,6 @@ Get unread inbox message count.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `513` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `limit` | `number` | Set to `1` (minimal fetch) |
 | `offset` | `number` | Set to `0` |
 
@@ -1412,9 +1786,6 @@ Get unread inbox message count.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `514` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `unread_count` | `number` | Number of unread messages |
 
 ---
@@ -1447,20 +1818,13 @@ Mark all inbox messages as read.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `529` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `all_read` | `boolean` | Set to `true` |
 
 #### Response
 
 **ClassId:** `530` (MARK_INBOX_READ_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `530` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -1474,20 +1838,13 @@ Delete all inbox messages.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `535` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `all_deleted` | `boolean` | Set to `true` |
 
 #### Response
 
 **ClassId:** `536` (MARK_INBOX_DELETED_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `536` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -1503,9 +1860,6 @@ Get all available jackpots.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `800` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `jp_template_id` | `number` | Filter by template ID (optional) |
 
 #### Response
@@ -1514,9 +1868,6 @@ Get all available jackpots.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `801` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `items` | [`JackpotDetails[]`](../api/interfaces/JackpotDetails.md) | Array of jackpots |
 
 ---
@@ -1531,20 +1882,13 @@ Opt-in to a jackpot.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `804` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `jp_template_id` | `number` | Jackpot template ID |
 
 #### Response
 
 **ClassId:** `805` (JP_OPTIN_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `805` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -1558,20 +1902,13 @@ Opt-out from a jackpot.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `806` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `jp_template_id` | `number` | Jackpot template ID |
 
 #### Response
 
 **ClassId:** `807` (JP_OPTOUT_RESPONSE)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | `807` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -1585,9 +1922,6 @@ Get jackpot winners history.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `809` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `jp_template_id` | `number` | Jackpot template ID |
 | `limit` | `number` | Max items to return |
 | `offset` | `number` | Offset for pagination |
@@ -1598,9 +1932,6 @@ Get jackpot winners history.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `810` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `winners` | [`JackpotWinnerHistory[]`](../api/interfaces/JackpotWinnerHistory.md) | Array of winners |
 
 ---
@@ -1615,9 +1946,6 @@ Get games eligible for a specific jackpot.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `811` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `jp_template_id` | `number` | Jackpot template ID |
 
 #### Response
@@ -1626,10 +1954,71 @@ Get games eligible for a specific jackpot.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `812` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
-| `games` | `array` | Array of eligible game IDs |
+| `eligible_games` | [`AchRelatedGame[]`](../api/interfaces/AchRelatedGame.md) | Array of eligible games |
+
+---
+
+### getJackpotLatestPots
+
+Get latest jackpot pot values for specified templates.
+
+#### Request
+
+**ClassId:** `802`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `jp_template_ids` | `number[]` | Array of jackpot template IDs |
+
+**Example:**
+
+```json
+{
+  "cid": 802,
+  "uuid": "pot-123",
+  "ts": 1699999999999,
+  "jp_template_ids": [1, 2, 3]
+}
+```
+
+#### Response
+
+**ClassId:** `803`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `items` | `JackpotPot[]` | Array of jackpot pot objects |
+
+Each `JackpotPot`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `jp_template_id` | `number` | Jackpot template ID |
+| `jp_pot_id` | `number` | Jackpot pot ID |
+| `current_pot_amount` | `number` | Current pot amount in base currency |
+| `current_pot_amount_user_currency` | `number` | Current pot amount in user's currency |
+| `explode_date_ts` | `number` | Timestamp when pot exploded (0 if not yet) |
+| `current_pot_temperature` | `number` | Temperature: 0=Cold, 1=Warm, 2=Hot, 3=Burning |
+
+**Example:**
+
+```json
+{
+  "cid": 803,
+  "uuid": "pot-123",
+  "errCode": 0,
+  "items": [
+    {
+      "jp_template_id": 1,
+      "jp_pot_id": 100,
+      "current_pot_amount": 50000,
+      "current_pot_amount_user_currency": 50000,
+      "explode_date_ts": 0,
+      "current_pot_temperature": 2
+    }
+  ]
+}
+```
 
 ---
 
@@ -1658,9 +2047,6 @@ Get list of Raffles available for user.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `cid` | `number` | ✓ | Message type identifier |
-| `uuid` | `string` | ✓ | Unique request identifier |
-| `ts` | `number` | ✓ | Timestamp in milliseconds |
 | `skip_public_meta` | `boolean` | - | If `true`, response will not include `public_meta` objects (reduces payload size) |
 
 ---
@@ -1745,9 +2131,6 @@ Get list of Raffles available for user.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | Message type identifier |
-| `errCode` | `number` | Error code. `0` = success |
-| `errMsg` | `string` | Error message (if any) |
 | `items` | [`Raffle[]`](../api/interfaces/Raffle.md) | Array of raffles |
 
 ---
@@ -1786,9 +2169,6 @@ Get detailed information about a specific draw run, including winners.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `cid` | `number` | ✓ | Message type identifier |
-| `uuid` | `string` | ✓ | Unique request identifier |
-| `ts` | `number` | ✓ | Timestamp in milliseconds |
 | `raffle_id` | `number` | ✓ | ID of the raffle |
 | `run_id` | `number` | ✓ | ID of the specific draw run |
 | `winners_limit` | `number` | - | Maximum number of winners to return |
@@ -1866,9 +2246,6 @@ Get detailed information about a specific draw run, including winners.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | Message type identifier |
-| `errCode` | `number` | Error code. `0` = success |
-| `errMsg` | `string` | Error message (if any) |
 | `draw` | [`RaffleDraw`](../api/interfaces/RaffleDraw.md) | Draw run details with winners |
 
 ---
@@ -1905,9 +2282,6 @@ Get history of completed draw runs for a specific raffle. Useful for displaying
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `cid` | `number` | ✓ | Message type identifier |
-| `uuid` | `string` | ✓ | Unique request identifier |
-| `ts` | `number` | ✓ | Timestamp in milliseconds |
 | `raffle_id` | `number` | ✓ | ID of the raffle |
 | `draw_id` | `number` | - | ID of specific draw. If not passed, all draw runs for the raffle will be returned |
 
@@ -1963,9 +2337,6 @@ Get history of completed draw runs for a specific raffle. Useful for displaying
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | Message type identifier |
-| `errCode` | `number` | Error code. `0` = success |
-| `errMsg` | `string` | Error message (if any) |
 | `draw_runs` | [`RaffleDrawRun[]`](../api/interfaces/RaffleDrawRun.md) | Array of historical draw runs |
 
 ---
@@ -2001,9 +2372,6 @@ Claim a prize won in a raffle draw.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `cid` | `number` | ✓ | Message type identifier |
-| `uuid` | `string` | ✓ | Unique request identifier |
-| `ts` | `number` | ✓ | Timestamp in milliseconds |
 | `won_id` | `number` | ✓ | ID of the won prize (from `raf_won_id` in RafflePrizeWinner) |
 
 ---
@@ -2024,11 +2392,7 @@ Claim a prize won in a raffle draw.
 
 **Fields:**
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `cid` | `number` | Message type identifier |
-| `errCode` | `number` | Error code. `0` = success |
-| `errMsg` | `string` | Error message (if any) |
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -2065,9 +2429,6 @@ Request opt-in for a specific raffle draw run. Used when a raffle requires expli
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `cid` | `number` | ✓ | Message type identifier |
-| `uuid` | `string` | ✓ | Unique request identifier |
-| `ts` | `number` | ✓ | Timestamp in milliseconds |
 | `raffle_id` | `number` | ✓ | ID of the raffle |
 | `draw_id` | `number` | ✓ | ID of the draw |
 | `raffle_run_id` | `number` | ✓ | ID of the specific draw run |
@@ -2090,11 +2451,161 @@ Request opt-in for a specific raffle draw run. Used when a raffle requires expli
 
 **Fields:**
 
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
+
+---
+
+## Engagement Tracking
+
+### reportEngagementImpression
+
+Report that an engagement message was displayed to the user (impression event). Fire-and-forget, no response expected.
+
+#### Request
+
+**ClassId:** `103`
+
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | Message type identifier |
-| `errCode` | `number` | Error code. `0` = success |
-| `errMsg` | `string` | Error message (if any) |
+| `engagement_uid` | `string` | Engagement unique ID |
+| `activityType` | `number` | Activity type from CJMActivityType enum: `20`=Banner, `30`=Popup, `31`=Inbox, `40`=Push |
+
+**Example:**
+
+```json
+{
+  "cid": 103,
+  "uuid": "abc-123",
+  "ts": 1699999999999,
+  "engagement_uid": "eng-001",
+  "activityType": 30
+}
+```
+
+---
+
+### reportEngagementAction
+
+Report that a user interacted with an engagement message (click/action event). Fire-and-forget, no response expected.
+
+#### Request
+
+**ClassId:** `104`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `engagement_uid` | `string` | Engagement unique ID |
+| `activityType` | `number` | Activity type from CJMActivityType enum |
+| `action` | `string` | Action identifier (optional) |
+
+**Example:**
+
+```json
+{
+  "cid": 104,
+  "uuid": "abc-123",
+  "ts": 1699999999999,
+  "engagement_uid": "eng-001",
+  "activityType": 30,
+  "action": "cta_click"
+}
+```
+
+---
+
+### reportEngagementFailed
+
+Report that an engagement message failed to display. Fire-and-forget, no response expected.
+
+#### Request
+
+**ClassId:** `106`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `engagement_uid` | `string` | Engagement unique ID |
+| `activityType` | `number` | Activity type from CJMActivityType enum |
+| `action` | `string` | Action that failed (optional) |
+| `reason` | `string` | Failure reason (optional) |
+
+**Example:**
+
+```json
+{
+  "cid": 106,
+  "uuid": "abc-123",
+  "ts": 1699999999999,
+  "engagement_uid": "eng-001",
+  "activityType": 30,
+  "reason": "render_error"
+}
+```
+
+---
+
+### trackActivity
+
+Track a client-side analytics activity. Fire-and-forget, no response expected.
+
+#### Request
+
+**ClassId:** `155`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `activity_id` | `number` | Activity identifier |
+| `view_time_sec` | `number` | View time in seconds (optional) |
+
+**Example:**
+
+```json
+{
+  "cid": 155,
+  "uuid": "abc-123",
+  "ts": 1699999999999,
+  "activity_id": 1,
+  "view_time_sec": 30
+}
+```
+
+---
+
+## Push Notifications
+
+### registerPushNotificationsToken
+
+Register a push notifications token for the current user. Required for receiving push notifications on native platforms.
+
+#### Request
+
+**ClassId:** `1003`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `token` | `string` | Push notification token (FCM token for Android, APNs token for iOS). Set to `null` to unregister. |
+| `platform` | `number` | Platform: `6`=NATIVE_IOS, `7`=NATIVE_ANDROID |
+| `pushNotificationUserStatus` | `number` | Status: `0`=ALLOWED, `1`=ASK, `2`=BLOCKED, `3`=SUSPENDED |
+| `app_package_id` | `string` | Application package ID (e.g. "com.example.app") |
+
+**Example:**
+
+```json
+{
+  "cid": 1003,
+  "uuid": "push-123",
+  "ts": 1699999999999,
+  "token": "fMI-qkT3...",
+  "platform": 7,
+  "pushNotificationUserStatus": 0,
+  "app_package_id": "com.example.app"
+}
+```
+
+#### Response
+
+**ClassId:** `2003`
+
+No method-specific fields. Returns only the common response fields (see [Common Message Fields](#common-message-fields)).
 
 ---
 
@@ -2110,9 +2621,8 @@ Get UI translations for a specific language.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `13` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
+| `hash_code` | `number` | Hash code for caching (send `0` on first request) |
+| `areas` | `number[]` | Translation areas to fetch (send `[]` for all) |
 | `lang_code` | `string` | Language code (e.g., "en", "de", "fr") |
 
 #### Response
@@ -2121,9 +2631,7 @@ Get UI translations for a specific language.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `14` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
+| `hash_code` | `number` | Hash code (use for subsequent requests to enable caching) |
 | `translations` | `object` | Key-value map of translation strings |
 
 #### Example
@@ -2134,6 +2642,8 @@ Get UI translations for a specific language.
   "cid": 13,
   "uuid": "trans-123",
   "ts": 1699999999999,
+  "hash_code": 0,
+  "areas": [],
   "lang_code": "en"
 }
 ```
@@ -2144,6 +2654,7 @@ Get UI translations for a specific language.
   "cid": 14,
   "uuid": "trans-123",
   "errCode": 0,
+  "hash_code": 12345,
   "translations": {
     "button.spin": "Spin Now",
     "label.points": "Points",
@@ -2164,11 +2675,10 @@ Get user's points history.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `545` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `startTimeSeconds` | `number` | Start time (Unix timestamp in seconds) |
 | `endTimeSeconds` | `number` | End time (Unix timestamp in seconds) |
+| `limit` | `number` | Max items to return |
+| `offset` | `number` | Offset for pagination |
 
 #### Response
 
@@ -2176,9 +2686,6 @@ Get user's points history.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `546` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `logHistory` | [`PointsLog[]`](../api/interfaces/PointsLog.md) \| [`GemsDiamondsLog[]`](../api/interfaces/GemsDiamondsLog.md) | Array of points history entries |
 
 #### Example
@@ -2226,9 +2733,6 @@ Get missions and tournaments related to a specific game.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `543` |
-| `uuid` | `string` | Unique request identifier |
-| `ts` | `number` | Timestamp (ms) |
 | `related_game_id` | `string` | Game ID to find related items for |
 
 #### Response
@@ -2237,9 +2741,6 @@ Get missions and tournaments related to a specific game.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `cid` | `number` | `544` |
-| `uuid` | `string` | Request identifier |
-| `errCode` | `number` | Error code (`0` = success) |
 | `achievements` | `array` | Related missions/achievements |
 | `tournaments` | `array` | Related tournaments |