GS2-Inbox SDK for Game Engine API Reference

Specifications of models and API references for GS2-Inbox SDK for Game Engine

Model

EzMessage

Message

Message data delivered to a message box prepared for each game player.

Messages have an open state, and you can set an Acquire Action to be executed when opened. Messages can be set to expire, and messages that expire are automatically deleted regardless of whether they are unread or read after opening. Messages will be deleted even if you have not received the attached reward.

TypeConditionRequiredDefaultValue LimitsDescription
messageIdstring
*
~ 1024 charsMessage GRN
* Set automatically by the server
namestring
UUID~ 36 charsMessage Name
Maintains a unique name for each message.
Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message.
metadatastring
~ 4096 charsMetadata
Arbitrary data representing the message content, such as a JSON string containing the message title, body text, sender information, and display parameters. GS2 does not interpret this value; it is passed through to the game client for rendering the message UI. Maximum 4096 characters.
isReadboolfalseRead Status
Indicates whether the message has been opened by the user. When a message is opened, this flag is set to true, the readAcquireActions are executed to deliver attached rewards, and the readAt timestamp is recorded. If isAutomaticDeletingEnabled is set on the namespace, the message is deleted after being read.
readAcquireActionsList<EzAcquireAction>[]0 ~ 100 itemsRead Acquire Actions
The list of acquire actions executed when the user opens this message. Used to attach rewards such as items, currency, or resources to messages. Multiple actions can be combined to grant different reward types simultaneously. Up to 100 actions per message.
receivedAtlong
*
NowDatetime of creation
Unix time, milliseconds
* Set automatically by the server
readAtlong0Datetime of read
Unix time, milliseconds
expiresAtlongDatetime of ttl
Unix time, milliseconds

EzConfig

Configuration

Configuration values applied to transaction variables

TypeConditionRequiredDefaultValue LimitsDescription
keystring
~ 64 charsName
valuestring~ 51200 charsValue

EzAcquireAction

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.

TypeConditionRequiredDefaultValue LimitsDescription
actionString Enum
enum {
"Gs2AdReward:AcquirePointByUserId",
"Gs2Dictionary:AddEntriesByUserId",
"Gs2Enchant:ReDrawBalanceParameterStatusByUserId",
"Gs2Enchant:SetBalanceParameterStatusByUserId",
"Gs2Enchant:ReDrawRarityParameterStatusByUserId",
"Gs2Enchant:AddRarityParameterStatusByUserId",
"Gs2Enchant:SetRarityParameterStatusByUserId",
"Gs2Enhance:DirectEnhanceByUserId",
"Gs2Enhance:UnleashByUserId",
"Gs2Enhance:CreateProgressByUserId",
"Gs2Exchange:ExchangeByUserId",
"Gs2Exchange:IncrementalExchangeByUserId",
"Gs2Exchange:CreateAwaitByUserId",
"Gs2Exchange:AcquireForceByUserId",
"Gs2Exchange:SkipByUserId",
"Gs2Experience:AddExperienceByUserId",
"Gs2Experience:SetExperienceByUserId",
"Gs2Experience:AddRankCapByUserId",
"Gs2Experience:SetRankCapByUserId",
"Gs2Experience:MultiplyAcquireActionsByUserId",
"Gs2Formation:AddMoldCapacityByUserId",
"Gs2Formation:SetMoldCapacityByUserId",
"Gs2Formation:AcquireActionsToFormProperties",
"Gs2Formation:SetFormByUserId",
"Gs2Formation:AcquireActionsToPropertyFormProperties",
"Gs2Friend:UpdateProfileByUserId",
"Gs2Grade:AddGradeByUserId",
"Gs2Grade:ApplyRankCapByUserId",
"Gs2Grade:MultiplyAcquireActionsByUserId",
"Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Idle:IncreaseMaximumIdleMinutesByUserId",
"Gs2Idle:SetMaximumIdleMinutesByUserId",
"Gs2Idle:ReceiveByUserId",
"Gs2Inbox:SendMessageByUserId",
"Gs2Inventory:AddCapacityByUserId",
"Gs2Inventory:SetCapacityByUserId",
"Gs2Inventory:AcquireItemSetByUserId",
"Gs2Inventory:AcquireItemSetWithGradeByUserId",
"Gs2Inventory:AddReferenceOfByUserId",
"Gs2Inventory:DeleteReferenceOfByUserId",
"Gs2Inventory:AcquireSimpleItemsByUserId",
"Gs2Inventory:SetSimpleItemsByUserId",
"Gs2Inventory:AcquireBigItemByUserId",
"Gs2Inventory:SetBigItemByUserId",
"Gs2JobQueue:PushByUserId",
"Gs2Limit:CountDownByUserId",
"Gs2Limit:DeleteCounterByUserId",
"Gs2LoginReward:DeleteReceiveStatusByUserId",
"Gs2LoginReward:UnmarkReceivedByUserId",
"Gs2Lottery:DrawByUserId",
"Gs2Lottery:ResetBoxByUserId",
"Gs2Mission:RevertReceiveByUserId",
"Gs2Mission:IncreaseCounterByUserId",
"Gs2Mission:SetCounterByUserId",
"Gs2Money:DepositByUserId",
"Gs2Money:RevertRecordReceipt",
"Gs2Money2:DepositByUserId",
"Gs2Quest:CreateProgressByUserId",
"Gs2Schedule:TriggerByUserId",
"Gs2Schedule:ExtendTriggerByUserId",
"Gs2Script:InvokeScript",
"Gs2SerialKey:RevertUseByUserId",
"Gs2SerialKey:IssueOnce",
"Gs2Showcase:DecrementPurchaseCountByUserId",
"Gs2Showcase:ForceReDrawByUserId",
"Gs2SkillTree:MarkReleaseByUserId",
"Gs2Stamina:RecoverStaminaByUserId",
"Gs2Stamina:RaiseMaxValueByUserId",
"Gs2Stamina:SetMaxValueByUserId",
"Gs2Stamina:SetRecoverIntervalByUserId",
"Gs2Stamina:SetRecoverValueByUserId",
"Gs2StateMachine:StartStateMachineByUserId",
}
Type of action to be executed in the Acquire Action
requeststring
~ 524288 charsJSON string of the request used when executing the action

EzVerifyActionResult

Verify Action execution result

TypeConditionRequiredDefaultValue LimitsDescription
actionString Enum
enum {
"Gs2Dictionary:VerifyEntryByUserId",
"Gs2Distributor:IfExpressionByUserId",
"Gs2Distributor:AndExpressionByUserId",
"Gs2Distributor:OrExpressionByUserId",
"Gs2Enchant:VerifyRarityParameterStatusByUserId",
"Gs2Experience:VerifyRankByUserId",
"Gs2Experience:VerifyRankCapByUserId",
"Gs2Grade:VerifyGradeByUserId",
"Gs2Grade:VerifyGradeUpMaterialByUserId",
"Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName",
"Gs2Guild:VerifyIncludeMemberByUserId",
"Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId",
"Gs2Inventory:VerifyItemSetByUserId",
"Gs2Inventory:VerifyReferenceOfByUserId",
"Gs2Inventory:VerifySimpleItemByUserId",
"Gs2Inventory:VerifyBigItemByUserId",
"Gs2Limit:VerifyCounterByUserId",
"Gs2Matchmaking:VerifyIncludeParticipantByUserId",
"Gs2Mission:VerifyCompleteByUserId",
"Gs2Mission:VerifyCounterValueByUserId",
"Gs2Ranking2:VerifyGlobalRankingScoreByUserId",
"Gs2Ranking2:VerifyClusterRankingScoreByUserId",
"Gs2Ranking2:VerifySubscribeRankingScoreByUserId",
"Gs2Schedule:VerifyTriggerByUserId",
"Gs2Schedule:VerifyEventByUserId",
"Gs2SerialKey:VerifyCodeByUserId",
"Gs2Stamina:VerifyStaminaValueByUserId",
"Gs2Stamina:VerifyStaminaMaxValueByUserId",
"Gs2Stamina:VerifyStaminaRecoverIntervalMinutesByUserId",
"Gs2Stamina:VerifyStaminaRecoverValueByUserId",
"Gs2Stamina:VerifyStaminaOverflowValueByUserId",
}
Type of action to be executed in the Verify Action
verifyRequeststring
~ 524288 charsJSON string of the request used when executing the action
statusCodeint0 ~ 999Status code
verifyResultstring~ 1048576 charsResult payload

EzConsumeActionResult

Consume Action execution result

TypeConditionRequiredDefaultValue LimitsDescription
actionString Enum
enum {
"Gs2AdReward:ConsumePointByUserId",
"Gs2Dictionary:DeleteEntriesByUserId",
"Gs2Enhance:DeleteProgressByUserId",
"Gs2Exchange:DeleteAwaitByUserId",
"Gs2Experience:SubExperienceByUserId",
"Gs2Experience:SubRankCapByUserId",
"Gs2Formation:SubMoldCapacityByUserId",
"Gs2Grade:SubGradeByUserId",
"Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Idle:DecreaseMaximumIdleMinutesByUserId",
"Gs2Inbox:OpenMessageByUserId",
"Gs2Inbox:DeleteMessageByUserId",
"Gs2Inventory:ConsumeItemSetByUserId",
"Gs2Inventory:ConsumeSimpleItemsByUserId",
"Gs2Inventory:ConsumeBigItemByUserId",
"Gs2JobQueue:DeleteJobByUserId",
"Gs2Limit:CountUpByUserId",
"Gs2LoginReward:MarkReceivedByUserId",
"Gs2Mission:ReceiveByUserId",
"Gs2Mission:BatchReceiveByUserId",
"Gs2Mission:DecreaseCounterByUserId",
"Gs2Mission:ResetCounterByUserId",
"Gs2Money:WithdrawByUserId",
"Gs2Money:RecordReceipt",
"Gs2Money2:WithdrawByUserId",
"Gs2Money2:VerifyReceiptByUserId",
"Gs2Quest:DeleteProgressByUserId",
"Gs2Ranking2:CreateGlobalRankingReceivedRewardByUserId",
"Gs2Ranking2:CreateClusterRankingReceivedRewardByUserId",
"Gs2Schedule:DeleteTriggerByUserId",
"Gs2SerialKey:UseByUserId",
"Gs2Showcase:IncrementPurchaseCountByUserId",
"Gs2SkillTree:MarkRestrainByUserId",
"Gs2Stamina:DecreaseMaxValueByUserId",
"Gs2Stamina:ConsumeStaminaByUserId",
}
Type of action to be executed in the Consume Action
consumeRequeststring
~ 524288 charsJSON string of the request used when executing the action
statusCodeint0 ~ 999Status code
consumeResultstring~ 1048576 charsResult payload

EzAcquireActionResult

Acquire Action execution result

TypeConditionRequiredDefaultValue LimitsDescription
actionString Enum
enum {
"Gs2AdReward:AcquirePointByUserId",
"Gs2Dictionary:AddEntriesByUserId",
"Gs2Enchant:ReDrawBalanceParameterStatusByUserId",
"Gs2Enchant:SetBalanceParameterStatusByUserId",
"Gs2Enchant:ReDrawRarityParameterStatusByUserId",
"Gs2Enchant:AddRarityParameterStatusByUserId",
"Gs2Enchant:SetRarityParameterStatusByUserId",
"Gs2Enhance:DirectEnhanceByUserId",
"Gs2Enhance:UnleashByUserId",
"Gs2Enhance:CreateProgressByUserId",
"Gs2Exchange:ExchangeByUserId",
"Gs2Exchange:IncrementalExchangeByUserId",
"Gs2Exchange:CreateAwaitByUserId",
"Gs2Exchange:AcquireForceByUserId",
"Gs2Exchange:SkipByUserId",
"Gs2Experience:AddExperienceByUserId",
"Gs2Experience:SetExperienceByUserId",
"Gs2Experience:AddRankCapByUserId",
"Gs2Experience:SetRankCapByUserId",
"Gs2Experience:MultiplyAcquireActionsByUserId",
"Gs2Formation:AddMoldCapacityByUserId",
"Gs2Formation:SetMoldCapacityByUserId",
"Gs2Formation:AcquireActionsToFormProperties",
"Gs2Formation:SetFormByUserId",
"Gs2Formation:AcquireActionsToPropertyFormProperties",
"Gs2Friend:UpdateProfileByUserId",
"Gs2Grade:AddGradeByUserId",
"Gs2Grade:ApplyRankCapByUserId",
"Gs2Grade:MultiplyAcquireActionsByUserId",
"Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Idle:IncreaseMaximumIdleMinutesByUserId",
"Gs2Idle:SetMaximumIdleMinutesByUserId",
"Gs2Idle:ReceiveByUserId",
"Gs2Inbox:SendMessageByUserId",
"Gs2Inventory:AddCapacityByUserId",
"Gs2Inventory:SetCapacityByUserId",
"Gs2Inventory:AcquireItemSetByUserId",
"Gs2Inventory:AcquireItemSetWithGradeByUserId",
"Gs2Inventory:AddReferenceOfByUserId",
"Gs2Inventory:DeleteReferenceOfByUserId",
"Gs2Inventory:AcquireSimpleItemsByUserId",
"Gs2Inventory:SetSimpleItemsByUserId",
"Gs2Inventory:AcquireBigItemByUserId",
"Gs2Inventory:SetBigItemByUserId",
"Gs2JobQueue:PushByUserId",
"Gs2Limit:CountDownByUserId",
"Gs2Limit:DeleteCounterByUserId",
"Gs2LoginReward:DeleteReceiveStatusByUserId",
"Gs2LoginReward:UnmarkReceivedByUserId",
"Gs2Lottery:DrawByUserId",
"Gs2Lottery:ResetBoxByUserId",
"Gs2Mission:RevertReceiveByUserId",
"Gs2Mission:IncreaseCounterByUserId",
"Gs2Mission:SetCounterByUserId",
"Gs2Money:DepositByUserId",
"Gs2Money:RevertRecordReceipt",
"Gs2Money2:DepositByUserId",
"Gs2Quest:CreateProgressByUserId",
"Gs2Schedule:TriggerByUserId",
"Gs2Schedule:ExtendTriggerByUserId",
"Gs2Script:InvokeScript",
"Gs2SerialKey:RevertUseByUserId",
"Gs2SerialKey:IssueOnce",
"Gs2Showcase:DecrementPurchaseCountByUserId",
"Gs2Showcase:ForceReDrawByUserId",
"Gs2SkillTree:MarkReleaseByUserId",
"Gs2Stamina:RecoverStaminaByUserId",
"Gs2Stamina:RaiseMaxValueByUserId",
"Gs2Stamina:SetMaxValueByUserId",
"Gs2Stamina:SetRecoverIntervalByUserId",
"Gs2Stamina:SetRecoverValueByUserId",
"Gs2StateMachine:StartStateMachineByUserId",
}
Type of action to be executed in the Acquire Action
acquireRequeststring
~ 524288 charsJSON string of the request used when executing the action
statusCodeint0 ~ 999Status code
acquireResultstring~ 1048576 charsResult payload

EzTransactionResult

Transaction execution results

Result of a transaction executed using the server-side automatic transaction execution feature

TypeConditionRequiredDefaultValue LimitsDescription
transactionIdstring
36 ~ 36 charsTransaction ID
verifyResultsList<EzVerifyActionResult>0 ~ 10 itemsList of verify action execution results
consumeResultsList<EzConsumeActionResult>[]0 ~ 10 itemsList of Consume Action execution results
acquireResultsList<EzAcquireActionResult>[]0 ~ 100 itemsList of Acquire Action execution results

Methods

batchRead

Open multiple messages and claim all rewards at once

Opens up to 10 messages at once and grants all their attached rewards in a single operation. If any of the specified messages has already been opened, an error is returned and none of the messages are processed — this ensures rewards are never claimed twice. Use this for an “Open All” or “Claim All” button on the gift box screen — the player taps one button and receives all pending rewards at once.

Request

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
messageNamesList<string>
1 ~ 10 itemsList of message names
gameSessionGameSession
GameSession

Result

TypeDescription
itemsList<EzMessage>List of Message
transactionIdstringIssued transaction ID
stampSheetstringStamp sheet
stampSheetEncryptionKeyIdstringCryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheetboolWhether automatic transaction execution is enabled
atomicCommitboolWhether to commit the transaction atomically
transactionstringIssued transaction
transactionResultEzTransactionResultTransaction execution result

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

TypeBase TypeDescription
MessageExpiredExceptionNotFoundExceptionMessage has expired

Implementation Example

try {
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.BatchReadAsync(
        messageNames: new List<string> {
            "message-0001",
            "message-0002",
        }
    );
} catch(Gs2.Gs2Inbox.Exception.MessageExpiredException e) {
    // Message has expired
}
    // In New Experience, stamp sheets are automatically executed at the SDK level.
    // If an error occurs, a TransactionException is thrown.
    // you can retry with TransactionException::Retry().
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.BatchReadFuture(
        messageNames: new List<string> {
            "message-0001",
            "message-0002",
        }
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Inbox.Exception.MessageExpiredException)
        {
            // Message has expired
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    // In New Experience, stamp sheets are automatically executed at the SDK level.
    // If an error occurs, a TransactionException is thrown.
    // you can retry with TransactionException::Retry().
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->BatchRead(
        []
        {
            auto v = TOptional<TArray<FString>>();
            v->Add("message-0001");
            v->Add("message-0002");
            return v;
        }() // messageNames
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Inbox::Error::FMessageExpiredError::Class))
        {
            // Message has expired
        }
        return false;
    }

delete

Delete a message from the gift box

Permanently removes a message from the player’s gift box, regardless of whether it has been opened or not. If your gift box is configured to automatically delete messages when they are opened, you don’t need to call this manually. But if auto-delete is disabled (so that opened messages remain visible in the gift box), use this API to let players clean up their inbox. Use this for a “Delete” or “Dismiss” button on individual messages — for example, letting players remove old opened messages they no longer need.

Request

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
messageNamestring
UUID~ 36 charsMessage Name
Maintains a unique name for each message.
Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message.

Result

TypeDescription
itemEzMessageMessage deleted

Implementation Example

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var result = await domain.DeleteAsync(
    );
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var future = domain.DeleteFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Message(
        "message-0001" // messageName
    );
    const auto Future = Domain->Delete(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

get

Get the details of a specific message

Retrieves the full details of a specific message in the player’s gift box, including its metadata (title, body, etc.), read status, attached rewards, and expiration time. Use this to show a message detail screen — for example, “Maintenance Compensation — Sorry for the inconvenience! Here are 100 Gems as compensation. [Open]”.

Request

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
messageNamestring
UUID~ 36 charsMessage Name
Maintains a unique name for each message.
Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message.
gameSessionGameSession
GameSession

Result

TypeDescription
itemEzMessageMessage

Implementation Example

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Message(
        "message-0001" // messageName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
Value change event handling
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Message(
        "message-0001" // messageName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Inbox::Model::FMessage> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

list

Get a list of messages in the player’s gift box

Retrieves all messages in the player’s gift box (present box / inbox), ordered from newest to oldest. Each message can contain rewards (items, currency, etc.) that the player can claim by opening it. You can filter by read status — for example, showing only unopened messages or only opened ones. Use this to build a “Gift Box” or “Presents” screen — for example, showing a list like “Maintenance Compensation (Gems x100)”, “Daily Login Bonus (Gold x500)”, with an “Open” button for each.

Request

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession
isReadboolRead status
pageTokenstring~ 1024 charsToken specifying the position from which to start acquiring data
limitint301 ~ 1000Number of data items to retrieve

Result

TypeDescription
itemsList<EzMessage>List of Message
nextPageTokenstringPage token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.MessagesAsync(
    ).ToListAsync();
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Messages(
    );
    List<EzMessage> items = new List<EzMessage>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Messages(
    );
    TArray<Gs2::UE5::Inbox::Model::FEzMessagePtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
Value change event handling
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeMessages(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeMessages(callbackId);
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeMessages(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeMessages(callbackId);
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeMessages(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeMessages(CallbackId);

read

Open a message and claim its rewards

Opens the specified message and grants any attached rewards (items, currency, etc.) to the player. The message is marked as read and the rewards are delivered in a single operation. If the message has already been opened, an error is returned to prevent claiming rewards twice. If the message has no rewards attached, it is simply marked as read. Use this for the “Open” or “Claim” button on each message in the gift box — for example, the player taps “Open” and receives “Gems x100”.

Request

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
messageNamestring
UUID~ 36 charsMessage Name
Maintains a unique name for each message.
Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message.
gameSessionGameSession
GameSession

Result

TypeDescription
itemEzMessageMessage
transactionIdstringIssued transaction ID
stampSheetstringStamp sheet
stampSheetEncryptionKeyIdstringCryptographic key GRN used for stamp sheet signature calculations
autoRunStampSheetboolWhether automatic transaction execution is enabled
atomicCommitboolWhether to commit the transaction atomically
transactionstringIssued transaction
transactionResultEzTransactionResultTransaction execution result

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

TypeBase TypeDescription
MessageExpiredExceptionNotFoundExceptionMessage has expired

Implementation Example

try {
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var result = await domain.ReadAsync(
    );
} catch(Gs2.Gs2Inbox.Exception.MessageExpiredException e) {
    // Message has expired
}
    // In New Experience, stamp sheets are automatically executed at the SDK level.
    // If an error occurs, a TransactionException is thrown.
    // you can retry with TransactionException::Retry().
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var future = domain.ReadFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Inbox.Exception.MessageExpiredException)
        {
            // Message has expired
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    // In New Experience, stamp sheets are automatically executed at the SDK level.
    // If an error occurs, a TransactionException is thrown.
    // you can retry with TransactionException::Retry().
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Message(
        "message-0001" // messageName
    );
    const auto Future = Domain->Read(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Inbox::Error::FMessageExpiredError::Class))
        {
            // Message has expired
        }
        return false;
    }

receiveGlobalMessage

Receive messages sent to all players

Checks for global messages (messages sent to all players at once, such as maintenance compensation or event rewards) and delivers any that this player hasn’t received yet to their gift box. Each global message is converted into an individual message in the player’s inbox. Messages already received are skipped, so calling this multiple times is safe. Call this when the player opens the gift box screen or logs in, to make sure they have all global messages available. Use this as part of the gift box initialization — call it before listing messages to ensure the player sees all global gifts.

Request

TypeConditionRequiredDefaultValue LimitsDescription
namespaceNamestring
~ 128 charsNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
gameSessionGameSession
GameSession

Result

TypeDescription
itemList<EzMessage>List of received messages

Implementation Example

    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.ReceiveGlobalMessageAsync(
    );
    var item = await result.ModelAsync();
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.ReceiveGlobalMessageFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->ReceiveGlobalMessage(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();

Event Handler

OnReceiveNotification

Push notification used when a message is received

NameTypeDescription
namespaceNamestringNamespace name
Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userIdstringUser ID
messageNamestringMessage Name
Maintains a unique name for each message.
Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message.

Implementation Example

    gs2.Inbox.OnReceiveNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var messageName = notification.MessageName;
    };
    gs2.Inbox.OnReceiveNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var messageName = notification.MessageName;
    };
    Gs2->Inbox->OnReceiveNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto UserId = Notification->UserIdValue;
        const auto MessageName = Notification->MessageNameValue;
    });