experience-notifications.md

title	Experience notifications
description	Experience Notifications are a way for users to keep up with their favorite experiences through timely, personalized notifications.

import Intro from '../../includes/experience-notifications/intro.md' import Eligibility from '../../includes/experience-notifications/eligibility.md' import ImplementationCreateNotificationString from '../../includes/experience-notifications/implementation-create-notification-string.md' import DeliverySystem from '../../includes/experience-notifications/delivery-system.md' import AnalyticsOverview from '../../includes/experience-notifications/analytics-overview.md' import AnalyticsNotificationsSummary from '../../includes/experience-notifications/analytics-notification-summary.md' import AnalyticsItemizedStats from '../../includes/experience-notifications/analytics-itemized-stats.md' import Guidelines from '../../includes/experience-notifications/guidelines.md'

Eligibility requirements

Usage guidelines

Implementation

Implementing Experience Notifications begins with creating a notification string. Once a notification string is set up, you can send notifications with optional custom parameters.

Alternatively, you can use the Engine API to trigger notifications through server-side scripts.

Create a notification string

Send an experience notification

The UserNotification API lets you send Experience Notifications to users. Before using it, you must generate an API key or configure OAuth 2.0 for your app. The examples on this page use API keys.

Notifications will be delivered to opted-in users age 13+ through their Roblox notification stream, at which point they can join the experience directly via the Join button on the notification and spawn according to your launch data.

To send an Experience Notification to a user:

1. Copy the API key to the x-api-key request header of the Create User Notification call.

2. In your request:

   1. Copy the notification string asset ID as the value of the payload.message_id property.
   2. Set payload.type to "MOMENT".
   3. Set source.universe to be the universe resource URL "universes/${UniverseID}".

curl --location 'https://apis.roblox.com/cloud/v2/users/${UserId}/notifications' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
	"source": {
		"universe": "universes/${UniverseID}"
	},
	"payload": {
		"message_id": "${AssetID}",
		"type": "MOMENT"
	}
}'

Example response which returns the notification ID in the id field:

{
  "path": "users/505306092/notifications/6ca4d981-36fa-4255-82a1-14d95c116889",
  "id": "6ca4d981-36fa-4255-82a1-14d95c116889"
}

Customize notifications using parameters

To customize the notification for each recipient, you can include parameters in the notification string, then customize the parameters when calling the API. For example, you can define the notification string as:

Then, set the userId-friend and points parameters in the script:

curl --location 'https://apis.roblox.com/cloud/v2/users/${UserId}/notifications' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
	"source": {
		"universe": "universes/${UniverseID}"
	},
	"payload": {
		"message_id": "${AssetID}",
		"type": "MOMENT",
		"parameters": {
			"userId-friend": {"int64_value": 3702832553},
			"points": {"string_value": "5"}
		}
	}
}'

Include launch and analytics data

To further improve user experience, you can include launch data in the notification, useful for scenarios such as routing users to a coordinate location or personalizing the joining experience. Additionally, you can include analytics data to segment the performance of different categories of notifications.

curl --location 'https://apis.roblox.com/cloud/v2/users/${UserId}/notifications' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
	"source": {
		"universe": "universes/${UniverseID}"
	},
	"payload": {
		"message_id": "${AssetID}",
		"type": "MOMENT"
	},
	"join_experience": {
		"launch_data": "Test_Launch_Data"
	},
	"analytics_data": {
		"category": "Test_Analytics_Category"
	}
}'

Delivery system

Analytics

Notifications summary

Itemized stats