Messages

Overview #

Messages let you broadcast information to one or more players at once. They’re ideal for announcements, promotions, notifications about live events like limited-time tournaments, rewards, and gifts.

Messages can be stored for the game client to fetch, or they can be sent as push notifications via integrations to inform players when they are not playing your game. Push notifications remind players to return to your game by sharing content and promotions outside the game.

In addition to push notifications, Satori’s OneSignal integration allows you to send messages by email, helping you reach your players through different channels.

Use cases #

Satori’s Messages feature enables game teams to communicate with their players for different use cases:

1. Remind players about a tournament with broadcast messages
2. Send direct messages for special promotions
3. Provide a notification inbox experience in your game

Key terminology #

• Push Notifications: Messages sent over push servers that appear on a player’s device screen. Use them to reach players outside the game.
• Message Template: A predefined structure that determines how a message is composed, including the title, body, and optional metadata.
• Message Schedule: A configuration that specifies when and how messages from a template are delivered, either by time or by event.
• Direct Message: A message sent directly to one or more specific players, outside a schedule.
• Integration: An external service (such as OneSignal, APNS, or FCM) used to deliver messages to players outside the game client.
• Message Inbox: A collection of messages stored in the player’s in-game inbox, accessible when they log in.

Message Templates #

Templates define the contents of the message to be sent to players and can be used in scheduling or sending direct messages. To send a message using Satori, you need to create a template first.

Creating a template #

In the Messages screen, select Create template to make a new message template.

The information needed to create a message template is given in the table below.

Message content types #

Satori messages support different content types:

• Plain Text
• HTML
• JSON

With Plain text content, you can write any message, but you can’t format the text. If you want to format the content, you can use HTML. The Satori Dashboard provides an editor where you can format your text and add links and images to your HTML content. With JSON content, the editor validates your JSON automatically.

Multi-language support #

When you create a template, the initial information you provide becomes the default content of the template. Within a template, you can add more translations using the “Add Translation” button on the top right.

Translations will be automatically used by Satori based on the language property of the identity. Satori checks for a translation in the player’s language and uses it to:

• Send push messages through integrations (push notification or email)
• Send messages when fetched by the game client

If Satori cannot find a translation for the player’s language, the default content will be used.

Using properties in templates #

Templates support using identity properties in the content. For example, to call players by name or nickname, set a custom property and use it in your messages:

{{ propertiesCustom.name }}, congrats!
You have just completed level {{ propertiesCustom.levelCompletedCount }}! Claim your reward now!
We also sent a discount code to {{ properties.email }} - you can use it in your next purchase!

Satori will replace these placeholders with the actual values of the properties and send the message as:

John, congrats!
You have just completed level 50! Claim your reward now!
We also sent a discount code to john@example.com - you can use it in your next purchase!

All property types (default, computed, and custom) are supported for all content types (Plain Text, HTML, and JSON).

Testing templates #

To test a template, you can send a test message to an identity. In the template details screen of the Satori Dashboard, select Test. Provide an identity and select integrations if you want to test with a specific one.

Message Schedules #

Message schedules define when template messages are sent. Satori supports two different schedule configurations:

1. Time-Based
2. Live Event-Based

To schedule a new message, click on the “Schedule message” button on the top right of the Messages screen. In the modal that opens, you will need to complete the following information:

Time-Based Scheduling Fields

If the schedule is not connected to a live event, you will need to configure the following:

Live Event-Based Scheduling Fields

If the schedule is connected to a live event, you must provide live event details:

The following Reference Points can be configured in the system:

Scheduling from Live Events #

You can also schedule a message from the live event configuration.

1. Open the Live Event you want to add a message schedule.
2. Go to the Message schedules tab. This page lists all messages scheduled for the live event.
3. To set up a new message schedule, click on the “Schedule new message” button.
4. The modal opens and requires the same information as the regular schedule message flow.
5. Enter the information and click “Create”. The new message schedule will be listed.

Direct Messages #

Using Console API #

You can send messages to one or more players directly using the Console API’s /v1/console/message-direct endpoint.

When using the endpoint, provide the following information:

• templateId: The identifier of the template used to render the message content. You can find this information at the top of the page when you open a message template.
• identityIds: List of recipient identity IDs.
• integrations: List of integrations to use for sending the message. Leaving this empty will ensure the message is only delivered to the identity inbox.
• persist: Boolean value that determines whether to store the message in the recipient’s inbox.

An example of the request body is given below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "templateId": "b98c0b60-61b8-4a35-b7e9-f87e5733fe79",
  "identityIds": [
    "00000000-0000-0000-0000-000000000001",
    "00000000-0000-0000-0000-000000000002",
    "00000000-0000-0000-0000-000000000003"
  ],
  "integrations": [
    "FCM",
    "APNS"
  ],
  "persist": true
}

From dashboard #

You can also send direct messages from the Satori Dashboard. You can send a test message, as explained in the “Testing templates” section, or use the Identity details page.

On this page, go to the “Messages” section. Here, all messages in the player’s inbox will be listed. Selecting a message shows details such as Consume time and Read time.

To send a message to this player, click on the “Send message” button and fill in the details in the window that opens. You will need to select the template and the integrations you want the template to trigger.

Integrations #

Integrations allow you to distribute messages to your players while they are not interacting with your game. Players may be offline, inactive for a long time, or may have deleted the game, but with the right integration, you can still reach them.

Satori supports the following integrations:

• OneSignal
• Apple Push Notification Service (APNS)
• Firebase Cloud Messaging (FCM)
• Facebook App-to-User Notifications (Facebook A2U)
• Webhook

To set up an integration:

1. Select Settings > Integrations.
2. You will see “Message Integrations” on this page.
3. Select the integration you want to set up.
4. Enter the details and select Save.

You can add as many integrations as you need here.

Matching players #

When sending messages, Satori checks which integrations are enabled for that schedule. For those integrations, Satori sends the message through the integration for that player if they have a token for it.

To do this, the game client must store the relevant token in Satori’s default properties. For instance, on an iOS client, when a player gives consent for push notifications, the game client should capture the iOS Push Token and store it in the pushTokenIos default property of Satori.

The property to be used for each integration is given in the table below: