Device registration and sending to a User

(new)

Beta

The Push Notifications API is currently available as a Private Beta product. The information contained in this document is subject to change. You acknowledge and agree that your use of the Twilio Push Notifications API is subject to the terms of the Services in Private Beta. This means that some features are not yet implemented and others may be changed before the product is declared as Generally Available. Private Beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

In many production use cases, it is advantageous to store the device token information with Twilio. This allows you to:

Push to all of a User's devices.
Reference Users instead of individually referencing their tokens.
Send pushes to repeat groups of Users through Audiences.

A DeviceRegistration stores a device token so that you can push to it later. It maps to a specific User and App. This structure allows you to push to the same User for different applications, and to push to all of a User's devices for a specific application at once.

Register a device

You can register a device by making a POST request to the /PushNotifications/DeviceRegistrations endpoint.

The following example shows how to register a device by providing an existing userId:

Register a device with a userId

1curl -X POST 'https://comms.twilio.com/v1/PushNotifications/DeviceRegistrations' \
2     -H 'Content-Type: application/json' \
3     -d '{
4          "userId": "comms_user_01h9krwprkeee8fzqspvwy6nq8",
5          "token": "odJFCrnl2edlBDdz1C5Ja:APA91bu2RJtBRnlWmTSHf6pWkLUyifDLkDmWJ6UuVTAIjvFu7WICPhDeOZIiBOB-Y6sHrFH2ZUCr-lgotu2iXW7GboIRoL3u6aHwnMztVuaP_coUNEhEkk_iqq8vH2BzNZV45pFCiRcD",
6          "appName": "test_app",
7          "provider": "FCM"
8        }' \
9     -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

The userId is optional. If you omit it, the API automatically creates a User to store the DeviceRegistration.

Register a device without a userId

1curl -X POST 'https://comms.twilio.com/v1/PushNotifications/DeviceRegistrations' \
2     -H 'Content-Type: application/json' \
3     -d '{
4          "token": "odJFCrnl2edlBDdz1C5Ja:APA91bu2RJtBRnlWmTSHf6pWkLUyifDLkDmWJ6UuVTAIjvFu7WICPhDeOZIiBOB-Y6sHrFH2ZUCr-lgotu2iXW7GboIRoL3u6aHwnMztVuaP_coUNEhEkk_iqq8vH2BzNZV45pFCiRcD",
5          "appName": "test_app",
6          "provider": "FCM"
7        }' \
8     -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Fetch a DeviceRegistration

You can retrieve the details of a DeviceRegistration, including the associated User, by making a GET request:

Fetch a DeviceRegistration

1curl -X GET 'https://comms.twilio.com/v1/PushNotifications/DeviceRegistrations/{DeviceRegistrationId}' \
2     -H 'Content-Type: application/json' \
3     -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Sample response:

1{
2   "appName": "test_app",
3   "userId": "comms_user_01k7q2bx0mft5bvbxh3781hkmr",
4   "devices": [
5      {
6         "provider": "FCM",
7         "token": "odJFCrnl2edlBDdz1C5Ja:APA91bu2RJtBRnlWmTSHf6pWkLUyifDLkDmWJ6UuVTAIjvFu7WICPhDeOZIiBOB-Y6sHrFH2ZUCr-lgotu2iXW7GboIRoL3u6aHwnMztVuaP_coUNEhEkk_iqq8vH2BzNZV45pFCiRcD"
8      }
9   ],
10   "id": "comms_device_registration_175903a30e55ce6dd9ac28d2704867dd",
11   "related": [
12      {
13         "id": "comms_user_01k7q2bx0mft5bvbxh3781hkmr",
14         "name": "user",
15         "uri": "/Users/comms_user_01k7q2bx0mft5bvbxh3781hkmr"
16      },
17      {
18         "id": "test_app",
19         "name": "push_notification_app",
20         "uri": "/PushNotifications/Apps/test_app"
21      }
22   ],
23   "tags": {}
24}

Send a notification to a User

Once you have registered devices to a User, you can send a notification to that User. The Push Notifications API delivers the push to all registered devices for the default App.

Send a notification to a User

1curl -X POST 'https://comms.twilio.com/v1/PushNotifications' \
2     -H 'Content-Type: application/json' \
3     -d '{
4          "to": [
5            {
6              "userId": "comms_user_01h9krwprkeee8fzqspvwy6nq8"
7            }
8          ],
9          "content": {
10            "title": "Welcome Back!",
11            "body": "It looks like you have been away for a while. New offers are waiting for you."
12          }
13        }' \
14     -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

This request delivers the notification to all device tokens associated with the specified User under the default App's Credentials. If the default App does not have a Credential for a specific provider (such as FCM or APNs) that the User has registered, the notification is not delivered to those tokens.

Next steps

Learn how to personalize push notifications for each recipient.
Review the DeviceRegistrations API reference.
Review the Users API reference.