Push notifications

How it works

In Web Shop, you can set up push notifications — personal or bulk messages that users receive directly in their browser. Push notifications let you inform users about new items, promotions, and special offers.

To send a notification to a user — for example, after they lose a battle or run out of resources — call the Xsolla API for sending notifications on the game server side.

After clicking the notification, the user goes to the Web Shop, where they can purchase the items they need.

Push notifications are configured in the Xsolla site builder and work only for published Web Shops.

Xsolla doesn’t track in-game events. You define when the game server makes the API call to send a notification, for example:

Interaction flow

1. The user opens the Web Shop in a browser or via an installed PWA and sees a banner offering to subscribe to notifications.
2. The user clicks Subscribe and allows notifications in the browser’s system prompt.

    flowchart LR
      A[User opens Web Shop] --> B{Permission already granted?}
      B -- Yes --> C[Automatic subscription]
      B -- No --> D{Can the browser show the system prompt?}
      D -- Yes --> E[System prompt]
      D -- No --> F[Subscribe banner]
      F --> E
      E -- Allow --> G[Subscribed]
      E -- Block --> H[Not subscribed]
  

3. The Web Shop registers the user as a subscriber in the Xsolla system. The subscription is linked to the browser or the installed PWA on the user’s device. The notifications you can send to the user depend on their authorization status:

   • If the user is logged in to the Web Shop, their ID is linked to the subscription — you can send personal notifications to this user.
   • If the user is not logged in, you can only send them bulk notifications; after the user logs in, the subscription is automatically linked to their user ID.

4. The game server makes the Xsolla API call to send notifications.

5. The user receives the push notification.

6. The user clicks the notification and goes to the Web Shop — to the page specified in the data.url parameter, or to the main page if the parameter isn’t passed. If the user has an active session in the Web Shop, they remain logged in.

  sequenceDiagram
    participant U as User
    participant WS as Web Shop
    participant G as Game
    participant X as Xsolla
    note over U,X: Subscription
    U->>WS: Opens the site / PWA
    WS->>U: Displays the subscription banner
    U->>WS: Subscribes and allows notifications
    WS->>X: Registers the subscriber (User ID, browser / PWA)
    X-->>WS: Confirms the subscription
    note over U,X: Sending a notification
    G->>X: Calls POST /messages/push/send
    X-->>G: Returns message_id
    X->>U: Sends the push notification
    U->>WS: Clicks the notification, follows data.url
    WS->>U: Displays store offers

How to get it

3. Go to the Push notifications section.
4. Turn on the Enable notifications toggle.
5. Copy the values from the Application ID, Client ID, and Client secret key fields — you will need them to send API requests from the game server. The parameters are created once, when the Enable notifications toggle is turned on for the first time, and are used for the entire project: if there are several sites in the project, the same values are used for all of them.
6. Set up the subscription banner if needed: change the title, description, icon, and button text.
7. To have the site automatically request the user’s permission to send push notifications when opened, turn on the Auto-request permission toggle (optional). If the toggle is off, permission is requested only after the user clicks the Subscribe button.
8. To apply the changes, publish the site.

9. On the game server, implement the push notification sending logic. The game server must make the API call for sending notifications and pass the user ID in the request.

Sending notifications

Xsolla doesn’t send notifications automatically — the sending is always initiated by your game server via the API call.

Base URL: https://messaging-platform.xsolla.com

Authentication

Requests are authenticated via the OAuth 2.0 protocol. Get a server JWT using the Generate JWT API call, passing the following parameters:

• grant_type — JWT grant type, pass the client_credentials value
• client_id — the Client ID field value from the Push notifications section settings
• client_secret — the Client secret key field value from the Push notifications section settings

Pass the received token in the Authorization: Bearer <token> header.

Send notification to user

Sends a personal push notification to a user by their ID. The notification is delivered to all browsers and installed PWAs where the user has subscribed to notifications.

HTTP request

POST https://messaging-platform.xsolla.com/api/v1/messages/push/send

Request headers

Request parameters

Response parameters

Example request

 1{
 2  "notification_type": "user_validation",
 3  "settings": {
 4    "project_id": 123456,
 5    "merchant_id": 789012
 6  },
 7  "user": {
 8    "id": "11111111-1111-1111-1111-111111111111"
 9  }
10}

Example response

1{
2  "message_ids": [
3"aa8ef5c2-front-4a3b-9d2e-example00001",
4"bb9fa6d3-front-4b4c-8e3f-example00002"
5    ]
6}

Send notification to all users

Sends a push notification to all or selected subscribed users. The notification is delivered to all browsers and installed PWAs where the user has subscribed to notifications.

HTTP request

POST https://messaging-platform.xsolla.com/api/v2/messages/push/send_batch

Request headers

Request parameters

Response parameters

Example request

 1POST /api/v2/messages/push/send_batch HTTP/1.1
 2Host: messaging-platform.xsolla.com
 3Authorization: Bearer <token>
 4Idempotency-Key: 5c1f0d2a-9b7e-4f36-8a1d-example00002
 5Content-Type: application/json
 6
 7{
 8  "app_id": "your_app_id",
 9  "recipients": {
10    "type": "all"
11  },
12  "title": "Seasonal sale!",
13  "body": "Up to 50% off in the Web Shop until the end of the week."
14}

 1POST /api/v1/messages/push/send_batch HTTP/1.1
 2Host: messaging-platform.xsolla.com
 3Authorization: Bearer <token>
 4Idempotency-Key: 7d2e1f3b-8c6a-4e57-9b2f-example00003
 5Content-Type: application/json
 6
 7{
 8  "app_id": "your_app_id",
 9  "recipients": {
10    "type": "external_user_id",
11    "external_user_id": ["player_123", "player_456"]
12  },
13  "title": "Seasonal sale!",
14  "body": "Up to 50% off in the Web Shop until the end of the week."
15}

Example response

1{
2  "summary": {
3    "failed_count": 0,
4    "success_count": 20
5  }
6}

 1{
 2  "results": [
 3    {
 4      "message_id": "cc0ab7e4-front-4c5d-9f4a-example00003",
 5      "player_id": "player_123",
 6      "status": "success"
 7    },
 8    {
 9      "message_id": "dd1bc8f5-front-4d6e-8a5b-example00004",
10      "player_id": "player_456",
11      "status": "success"
12    }
13  ]
14}