Transactional Messages

Sending push notifications to individual or small groups of User IDs is a user-friendly and helpful way to keep lines of communication opened with your clients.

Transactional push notifications are great for letting users know that their action is completed, whether that is billing related or simply saying "Thanks for performing this action!" (whatever that action may be).

Setup

The best practice for this use case is to set and target the device by the User ID. This can be done by sending OneSignal your Users IDs (external_user_id) or saving the OneSignal User ID (Player ID) to your database.

Please see our Internal Database & CRM integration guide for more details.

Using External User ID

If you fetch your database User ID and set it to OneSignal with the setExternalUserId method or add it via our API Edit device, you can then use include_external_user_ids on our Create notification REST API POST call to send notifications to specific users.

Example:

curl --include \
     --request POST \
     --header "Content-Type: application/json; charset=utf-8" \
     --data-binary "{\"app_id\": \"5eb5a37e-b458-11e3-ac11-000c2940e62c\",
\"contents\": {\"en\": \"English Message\"},
\"include_external_user_ids\": [\"YOUR_USER_ID\"]}" \
     https://onesignal.com/api/v1/notifications

{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
  "include_external_user_ids": ["YOUR_USER_ID"],
  "data": {"foo": "bar"},
  "contents": {"en": "English Message"}
}

If the user is unsubscribed, our API returns all the External User IDs of devices that are not subscribed anymore that looks like this:

{
  "errors": {
    "invalid_external_user_ids" : ["YOUR_USER_ID"]
  }
}

If multiple devices have the same External User ID, it will count them multiple times in the callback but any devices still subscribed will not be counted.

For example, if you have 3 devices with External User ID "37" and 2 of those 3 unsubscribe, then the callback will show "invalid_external_user_ids" : ["37", "37"] but the 3rd External User ID will still be subscribed.

Using OneSignal Player ID

To target the OneSignal Player ID, you can then use include_player_ids on our Create notification REST API POST call to send notifications to specific users.

Example:

curl --include \
     --request POST \
     --header "Content-Type: application/json; charset=utf-8" \
     --data-binary "{\"app_id\": \"5eb5a37e-b458-11e3-ac11-000c2940e62c\",
\"contents\": {\"en\": \"English Message\"},
\"include_player_ids\": [\"6392d91a-b206-4b7b-a620-cd68e32c3a76\"]}" \
     https://onesignal.com/api/v1/notifications

{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
  "include_player_ids": ["6392d91a-b206-4b7b-a620-cd68e32c3a76"],
  "data": {"foo": "bar"},
  "contents": {"en": "English Message"}
}

If the user is unsubscribed, our API returns all the Player IDs of devices that are not subscribed anymore that looks like this:

{
  "errors": {
    "invalid_player_ids" : ["6392d91a-b206-4b7b-a620-cd68e32c3a76"]
  }
}

You can then process these Player IDs on your server to remove them from your database.