Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Page tools
On this page
Looking for more inspiration?Visit the

DeviceRegistrations resource

(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(link takes you to an external page). 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.

A Device Registration resource associates a device token with a User for push notification delivery. Instead of managing device tokens yourself, you can store them as Device Registrations and send notifications to Users by their userId.

Each Device Registration links a userId to a device token and provider (APN or FCM), scoped to a specific App.

DeviceRegistration Properties

deviceregistration-properties page anchor
Property nameTypeRequiredPIIDescriptionChild properties
idstring
required
Not PII

A reference to a Device Registration.

Example: comms_device_registration_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_device_registration_[a-hjkmnpqrstv-z0-9]{26,34}$
appNamestring
required
Not PII

The name of the App that the device registrations are for.

userIdstring
required
Not PII

A reference to a Push Notification User.

Example: comms_pushnotificationuser_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_pushnotificationuser_[0-7][a-hjkmnpqrstv-z0-9]{25,34}
devicesarray[Device]
required
Not PII

List of devices registered in this set.

Min items: 1Max items: 50
relatedarray[RelatedResource]
required
Not PII

A list of resources that are associated with this Device Registration.

Register a Device

register-a-device page anchor

POST https://comms.twilio.com/v1/PushNotifications/DeviceRegistrations

Register a device for push notifications by making an HTTP POST request to the Device Registrations resource URI.

You must specify an appName that matches an existing App. If the appName does not match any existing App, the operation fails.

If you omit the userId, the API creates a new User automatically.

Request body parameters

request-body-parameters page anchor
Encoding type:application/json
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
userIdstring

Optional

Not PII

The ID of the User to register the device to, if available.

Example: comms_pushnotificationuser_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_pushnotificationuser_[0-7][a-hjkmnpqrstv-z0-9]{25,34}
appNamestring
required
Not PII

The name of the App to register the device for.

If the appName does not match the name of any existing Push Notification App, the operation will fail.

Pattern: ^[a-z0-9_]+$Min length: 1Max length: 64
tokenstring
required
Not PII

The device token to register for push notifications.

providerenum<string>
required
Not PII

Push notification service provider.

Possible values:
APNFCM

Responses

responses page anchor
202400429500503

The request was accepted and a resource ID is available to check the result. The response body contains the resource ID and link to the resource.

SchemaExample
Property nameTypeRequiredDescriptionChild properties
resourceIdstring

Optional

The Resource ID is an identifier for the resource that was created or updated in response to the request.

resourceLocationstring<uri>

Optional

The location (uri) of the resource identified by Resource-Id.

Create a DeviceRegistrationLink to code sample: Create a DeviceRegistration
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.deviceRegistrations.register({

9
        userId: "comms_pushnotificationuser_01h9krwprkeee8fzqspvwy6nq8",

10
        appName: "limonade_app",

11
        token: "dqWD7WEC83K41WHyufTS7:APA91bFcrVaOLqKeJfSiEutJXX2Tr9wN_tYOwYd8rFA6mYUMBFqdz9n6k3v5EpFA_ukXD89hGqG3OarzbVfdjGnLOIAQfwbQcqJkjQWMrhwElrtU1y3JLDPfnjc0eTJLxzhyYvDFopEh",

12
        provider: "FCM",

13
    });

14
}

15
main();

Fetch a Device Registration

fetch-a-device-registration page anchor

GET https://comms.twilio.com/v1/PushNotifications/DeviceRegistrations/{deviceRegistrationId}

Retrieve a single Device Registration resource by making an HTTP GET request to the Device Registration resource URI with the Device Registration ID.

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
deviceRegistrationIdstring
required
Not PII
Example: comms_device_registration_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_device_registration_[a-hjkmnpqrstv-z0-9]{26,34}$

Responses

responses-1 page anchor
200400404429500503

OK

SchemaExample
Property nameTypeRequiredDescriptionChild properties
idstring

Optional

A reference to a Device Registration.

Example: comms_device_registration_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_device_registration_[a-hjkmnpqrstv-z0-9]{26,34}$
appNamestring

Optional

The name of the App that the device registrations are for.

userIdstring

Optional

A reference to a Push Notification User.

Example: comms_pushnotificationuser_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_pushnotificationuser_[0-7][a-hjkmnpqrstv-z0-9]{25,34}
devicesarray[Device]

Optional

List of devices registered in this set.

Min items: 1Max items: 50
relatedarray[RelatedResource]

Optional

A list of resources that are associated with this Device Registration.

Fetch a DeviceRegistrationLink to code sample: Fetch a DeviceRegistration
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.deviceRegistrations.fetch("comms_device_registration_01h9krwprkeee8fzqspvwy6nq8");

9
}

10
main();

List Device Registrations

list-device-registrations page anchor

GET https://comms.twilio.com/v1/PushNotifications/DeviceRegistrations

Returns a list of Device Registrations. The userId query parameter is required. You can optionally filter by appName.

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
userIdstring
required
Not PII

Filter Device Registrations by User.id to retrieve only registrations for that User.

Example: comms_pushnotificationuser_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_pushnotificationuser_[0-7][a-hjkmnpqrstv-z0-9]{25,34}
appNamestring

Optional

Not PII

Filter Device Registrations by their appName. Must be accompanied by the userId query parameter.

Pattern: ^[a-z0-9_]+$Min length: 1Max length: 64
pageTokenstring

Optional

Not PII

The token to retrieve the next page of results.

pageSizeinteger

Optional

Not PII

The number of resources to return in a page.

Default: 50Example: 50Minimum: 1Maximum: 1000

Responses

responses-2 page anchor
200400429500503

OK

SchemaExample
Property nameTypeRequiredDescriptionChild properties
deviceRegistrationsarray[DeviceRegistration]

Optional

List of Device Registrations.

paginationPaginationMetadata

Optional

Metadata for paginated results. This object contains two tokens to navigate through paginated results.

  • Use next to retrieve the 'next' page in the result list.
  • Use self to retrieve the same page of the result list again.
  • Supply the token in the pageToken query param.
List DeviceRegistrationsLink to code sample: List DeviceRegistrations
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.deviceRegistrations.list({

9
        userId: "comms_pushnotificationuser_01h9krwprkeee8fzqspvwy6nq8",

10
        appName: "appName",

11
        pageToken: "pageToken",

12
        pageSize: 50,

13
    });

14
}

15
main();

Delete a Device Registration

delete-a-device-registration page anchor

DELETE https://comms.twilio.com/v1/PushNotifications/DeviceRegistrations/{deviceRegistrationId}

Delete a Device Registration by making an HTTP DELETE request to the Device Registration resource URI with the Device Registration ID.

If successful, returns HTTP 202 (Accepted) with a resource ID to check the result.

Once deleted, the User no longer receives push notifications for the specified App until new devices are registered.

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
deviceRegistrationIdstring
required
Not PII
Example: comms_device_registration_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_device_registration_[a-hjkmnpqrstv-z0-9]{26,34}$

Responses

responses-3 page anchor
202400404429500503

The request was accepted and a resource ID is available to check the result. The response body contains the resource ID and link to the resource.

SchemaExample
Property nameTypeRequiredDescriptionChild properties
resourceIdstring

Optional

The Resource ID is an identifier for the resource that was created or updated in response to the request.

resourceLocationstring<uri>

Optional

The location (uri) of the resource identified by Resource-Id.

Delete a DeviceRegistrationLink to code sample: Delete a DeviceRegistration
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.deviceRegistrations.delete("comms_device_registration_01h9krwprkeee8fzqspvwy6nq8");

9
}

10
main();