> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Inbox Master Data Reference

Reference for the master data format and the models to be imported




## Master Data Format


**JSON**
```json
{
  "version": "2020-03-12",
  "globalMessages": [
    {
      "name": "[string]Global Message name",
      "metadata": "[string]Metadata",
      "readAcquireActions": [
        {
          "action": "[string]Type of Acquire Action",
          "request": "[string]JSON string of the request used when executing the action"
        }
      ],
      "expiresTimeSpan": {
        "days": "[int]Days",
        "hours": "[int]Hours",
        "minutes": "[int]Minutes"
      },
      "messageReceptionPeriodEventId": "[string?]Message Reception Period Event ID"
    }
  ]
}
```


|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2020-03-12 | | Master data format version |
| globalMessages | [List&lt;GlobalMessage&gt;](#globalmessage) |  |  |  |  ~ 1000 items | Global Message<br>Global Message is a mechanism for delivering messages to all game players.<br><br>Global messages can have an expiration time, and each game player can receive a Global Message by executing the process of receiving a Global Message.<br>Unreceived Global Messages within the validity period are copied to the player's message box. |

## Models

### GlobalMessage

Global Message

Global Message is a mechanism for delivering messages to all game players.

Global messages can have an expiration time, and each game player can receive a Global Message by executing the process of receiving a Global Message.
Unreceived Global Messages within the validity period are copied to the player's message box.

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| globalMessageId | string |  | * |  |  ~ 1024 chars | GRN of the Global Message for all users<br>* Set automatically by the server |
| name | string |  | ✓ |  |  ~ 128 chars | Global Message name<br>Unique Global Message name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| metadata | string |  | ✓ |  |  ~ 4096 chars | Metadata<br>Arbitrary data representing the global message content, such as a JSON string containing the message title, body text, and display parameters. When a user receives this global message, the metadata is copied to the individual message in their inbox. GS2 does not interpret this value. Maximum 4096 characters. |
| readAcquireActions | [List&lt;AcquireAction&gt;](#acquireaction) |  |  | [] | 0 ~ 100 items | Acquire Actions on Open<br>The list of acquire actions to be executed when a user opens the message copied from this global message. These actions are copied along with the metadata to each user's individual message. Up to 100 actions per global message. |
| expiresTimeSpan | [TimeSpan](#timespan) |  |  |  |  | Expiration Time Span<br>The duration from the time a user receives (copies) this global message until the copied message expires and is automatically deleted from their inbox. Specified as a combination of days, hours, and minutes. Messages are deleted regardless of read status when the expiration is reached, including any unclaimed attached rewards. |
| messageReceptionPeriodEventId | string |  |  |  |  ~ 1024 chars | Message Reception Period Event ID<br>The GRN of a GS2-Schedule event that defines the time window during which this global message can be received (copied to users' inboxes). Outside this period, the global message is not delivered even if a user triggers the receive global messages operation. Useful for time-limited event announcements or seasonal campaign rewards. |

---

### TimeSpan

Time Span

Represents a duration of time as a combination of days, hours, and minutes. Used to define the expiration period for messages relative to their reception time. For example, a TimeSpan of 7 days, 0 hours, 0 minutes means the message expires exactly one week after the user receives it.

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| days | int |  |  | 0 | 0 ~ 365 | Days<br>The number of days in this time span. Combined with hours and minutes to calculate the total duration. Maximum 365 days. |
| hours | int |  |  | 0 | 0 ~ 24 | Hours<br>The number of hours in this time span. Combined with days and minutes to calculate the total duration. Maximum 24 hours. |
| minutes | int |  |  | 0 | 0 ~ 60 | Minutes<br>The number of minutes in this time span. Combined with days and hours to calculate the total duration. Maximum 60 minutes. |

---

### AcquireAction

Acquire Action

Represents a single acquire action attached to a message as a reward. Consists of an action type (e.g., add items to inventory, increase currency) and its request parameters. When a message is opened, these actions are assembled into transactions and executed to deliver the rewards to the user.

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| action | string (enum)<br>enum {<br>}<br> |  | ✓ |  |  | Type of Acquire Action |
| request | string |  | ✓ |  |  ~ 524288 chars | JSON string of the request used when executing the action |

---