Manage system transient notifications

Last updated on October 22, 2026

Overview

The system transient notifications feature of AccelByte Gaming Services (AGS) Chat allows game developers to create categories which later become a hook to system messages or events that can be momentarily displayed as a pop-up inside the game. This article explains how to manage system transient notifications in the AGS Admin Portal or with the AGS CLI.

Prerequisites

Administrators must have the following permissions to manage system transient notifications:

Permissions	Action	Usage
ADMIN:NAMESPACE:{namespace}:CHAT:CATEGORY	CREATE, READ, UPDATE, DELETE	To hook system message or event to the category
ADMIN:NAMESPACE:{namespace}:CHAT:INBOX	CREATE, READ, UPDATE, DELETE	To create system message

To follow the AGS CLI steps, install the AGS CLI and sign in with an account that has the permissions above. See Install and sign in. The examples use a Bash shell.

Transient notifications flow

The following diagrams show more information on how the feature works:

Access the Transient Messages page

To access the management and configuration options outlined in the following sections, log in to your AGS Admin Portal and go to your game namespace dashboard. Then, go to Multiplayer > Chat > Transient Messages.

Manage categories

The following sections detail the management of transient notification categories.

Create new category

To create a new category for system transient notifications, follow these steps:

Admin Portal

1. On the Transient Messages page, open the Categories tab.

2. Click + Create new.

3. Fill out the Create New Category page with the required information.

4. Click Create.

AGS CLI

1. Create a JSON file with the category's settings. Any file name works. This example uses category.json:

   {
     "name": "<CategoryName>",
     "expiresIn": 3600000000000,
     "saveInbox": false,
     "sendNotification": true,
     "enabled": true
   }

   • name: letters, numbers, spaces, -, _, and . only. You can't change it later.
   • expiresIn: how long messages in this category last, in nanoseconds. The Admin Portal takes this value in seconds, so multiply your seconds by 1,000,000,000. The example is one hour.
   • sendNotification: keep this true. The Admin Portal always sets it to true.

   These fields match the other Admin Portal settings:

   Admin Portal setting	Request body field
   Saved In Inbox	saveInbox
   Driver, Topic, Event Name, and User ID Path	hook: {"driver": "KAFKA", "params": {"topic": "<Topic>", "eventName": "<EventName>", "userIdsPath": "<UserIdPath>"}}. Leave hook out for no driver.
   jsonSchema	jsonSchema

2. Create the category. After @, pass the path to your JSON file:

   ags chat inbox create-category --namespace <YourNamespace> --json @category.json

Edit a category

Admin Portal

To edit a category, return to the Transient Messages page. Under the Categories tab, click your category's name under the Categories section to make your desired changes, then click Update when you're done.

AGS CLI

1. List the categories:

   ags chat inbox list-categories --namespace <YourNamespace> --format json

2. Copy your category's object from the output into a JSON file, such as category.json, and edit the settings you want to change. See Create new category for the fields.

3. Update the category. Replace <CategoryName> with the category's name:

   ags chat inbox update-category --namespace <YourNamespace> --category <CategoryName> --json @category.json

   warning

   Every update overwrites all of the category's settings. A field you leave out of the file is reset, so keep every field from step 2 in the file.

Delete a category

Admin Portal

You can delete a category by going to the Transient Messages page under the Categories tab, finding your category listed in the Categories section, and clicking the Delete option that's next to it under the Action column.

AGS CLI

To delete a category, run the following command. Replace <CategoryName> with the category's name:

ags chat inbox delete-category --namespace <YourNamespace> --category <CategoryName>

Manage messages

The following sections detail the management of transient notification messages.

Create a new message

To create a new message for system transient notifications, follow these steps:

Admin Portal

1. On the Transient Messages page, open the Messages tab.

2. Click + Create new.

3. Fill out the Create New Message page with the content, recipient, and category of your message.

4. Click Save as Draft to send the message later, or click Send to send the message right away.

AGS CLI

1. Create a JSON file with the message. Any file name works. This example uses message.json:

   {
     "category": "<CategoryName>",
     "message": {"body": "<MessageBody>"},
     "scope": "USER",
     "userIds": ["<UserId>"],
     "expiredAt": <ExpiredAt>,
     "status": "DRAFT"
   }

   • category: the name of the category. To see your categories, run ags chat inbox list-categories --namespace <YourNamespace>.
   • message: the content of the message. body holds the text that you type in the Admin Portal.
   • scope and userIds: to send the message to specific players, set scope to USER and list their user IDs in userIds. To send it to all players, set scope to NAMESPACE and userIds to []. The Admin Portal also accepts usernames and emails, but the AGS CLI only accepts user IDs.
   • expiredAt: when the message expires, as a Unix timestamp in seconds. The Admin Portal sets it to the current time plus the category's expiry time. It must be in the future. On Linux, date -d '+1 day' +%s prints the timestamp for one day from now.
   • status: DRAFT to save the message as a draft, or SENT to send it right away.

2. Create the message. After @, pass the path to your JSON file:

   ags chat inbox create-message --namespace <YourNamespace> --json @message.json

   The command prints the new message, including its id.

Edit and send draft messages

Admin Portal

You can find your messages on the Transient Messages page under the Messages tab listed under the Message List section. You can edit draft messages by clicking into their names. You can save your changes by clicking Save as Draft, or send the messages right away by clicking Send.

AGS CLI

1. Find the ID of the draft message:

   ags chat inbox list-messages --namespace <YourNamespace> --transient true --status DRAFT

2. To edit the draft, create a JSON file with the message's new settings. This example uses message.json:

   {
     "message": {"body": "<MessageBody>"},
     "scope": "USER",
     "userIds": ["<UserId>"],
     "expiredAt": <ExpiredAt>
   }

   The fields work the same as in Create a new message. You can't change the category.

   warning

   Every update overwrites the message, its recipients, and its expiry time. Include all four fields, even the ones you don't change.

3. Save your changes. Replace <MessageId> with the draft's id from step 1. After @, pass the path to your JSON file:

   ags chat inbox update-message --namespace <YourNamespace> --message-id <MessageId> --json @message.json

4. To send the draft, run:

   ags chat inbox send-message --namespace <YourNamespace> --message-id <MessageId>

Unsend a sent message

Admin Portal

You can find your messages on the Transient Messages page under the Messages tab listed under the Message List section. To unsend a message, find the message you want to unsend and click the ellipsis menu next to it under the Action column and click Unsend. Then, type UNSEND to confirm.

AGS CLI

1. Find the ID of the sent message:

   ags chat inbox list-messages --namespace <YourNamespace> --transient true --status SENT

2. Unsend the message. Replace <MessageId> with the message's id:

   ags chat inbox unsend-message --namespace <YourNamespace> --inbox <MessageId> --json '{"userIds": []}'

   An empty userIds list unsends the message from every recipient and marks it as unsent. To unsend it from specific players only, list their user IDs instead.

Duplicate a sent message as draft

Admin Portal

You can find your messages on the Transient Messages page under the Messages tab listed under the Message List section. To duplicate a sent message and save it as a draft, find the message you want to duplicate and click the ellipsis menu next to it under the Action column and click Duplicate as Draft. Then, click Duplicate to confirm.

AGS CLI

1. Get the message that you want to duplicate. Replace <MessageId> with the message's id, which ags chat inbox list-messages --namespace <YourNamespace> --transient true lists:

   ags chat inbox list-messages --namespace <YourNamespace> --message-id <MessageId> --format json

2. Create a JSON file, such as message.json, with the category, message, scope, and userIds values from the output. Set status to DRAFT and expiredAt to a new time in the future. See Create a new message for the fields.

3. Create the draft:

   ags chat inbox create-message --namespace <YourNamespace> --json @message.json