Apps 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. 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.

An App resource represents a namespace that associates different Credentials with specific Device Registrations. Use Apps to separate registrations and credentials for different environments or applications.

For example, you might have a development App and a production App, or you might offer more than one user-facing application to your customers.

The API creates an App automatically when you create a Credential with an appName that doesn't exist yet. If no other Apps exist, the API sets the new App as the default. You can have a maximum of 10 Apps per account.

App Properties

Property nameTypeRequiredPIIDescriptionChild properties

namestring

required

Not PII

The name of the App. This is the unique identifier of the App.

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

isDefaultboolean

required

Not PII

Whether this App is the default (Push Notification) App for the Account. The first App auto-created is automatically set as the default. To update the default App, use PATCH /PushNotifications/Apps/{appName}.

defaultCredentialsarray[PushNotificationAppDefaultCredential]

required

Not PII

The default Credentials for this App.

Show defaultCredentials properties

createdAtstring<date-time>

required

Not PII

updatedAtstring<date-time>

required

Not PII

Fetch an App

GET https://comms.twilio.com/v1/PushNotifications/Apps/{appName}

Retrieve a single App resource by making an HTTP GET request to the App resource URI with the App name.

The response includes the App's defaultCredentials array, which lists the default credential for each provider type (APN, FCM).

Path parameters

Property nameTypeRequiredPIIDescription

appNamestring

required

Not PII

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

Responses

200400404429500503

SchemaExample

Property nameTypeRequiredDescriptionChild properties

namestring

Optional

The name of the App. This is the unique identifier of the App.

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

isDefaultboolean

Optional

defaultCredentialsarray[PushNotificationAppDefaultCredential]

Optional

The default Credentials for this App.

Show defaultCredentials properties

createdAtstring<date-time>

Optional

updatedAtstring<date-time>

Optional

This error indicates that the request content was malformed or ambiguous.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the requested resource was not found.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that you have sent too many requests to the API. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the Twilio API is experiencing server-side issues. The request should not be retried.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the Twilio API is temporarily unavailable. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

Fetch a PushNotification App

1import { TwilioClient } from "twilio-comms";
2
3async function main() {
4    const client = new TwilioClient({
5        accountId: "<username>",
6        authToken: "<password>",
7    });
8    await client.pushNotifications.apps.fetch("appName");
9}
10main();

List Apps

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

Returns a list of all Apps associated with your account. You can filter by date range or default status.

Query parameters

Property nameTypeRequiredPIIDescription

startDatestring<date-time>

Optional

Not PII

Filter to Push Notification Apps created after the specified date and time.

endDatestring<date-time>

Optional

Not PII

Filter to Push Notification Apps created before the specified date and time.

isDefaultboolean

Optional

Not PII

Filter by App.isDefault.

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

200400429500503

SchemaExample

Property nameTypeRequiredDescriptionChild properties

appsarray[PushNotificationApp]

Optional

Show apps properties

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.

Show pagination properties

This error indicates that the request content was malformed or ambiguous.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that you have sent too many requests to the API. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the Twilio API is experiencing server-side issues. The request should not be retried.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the Twilio API is temporarily unavailable. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

List PushNotification Apps

1import { TwilioClient } from "twilio-comms";
2
3async function main() {
4    const client = new TwilioClient({
5        accountId: "<username>",
6        authToken: "<password>",
7    });
8    await client.pushNotifications.apps.list({
9        startDate: new Date("2024-01-15T09:30:00Z"),
10        endDate: new Date("2024-01-15T09:30:00Z"),
11        isDefault: true,
12        pageToken: "pageToken",
13        pageSize: 50,
14    });
15}
16main();

Update an App

PATCH https://comms.twilio.com/v1/PushNotifications/Apps/{appName}

Update an existing App by making an HTTP PATCH request to the App resource URI with the App name.

Set isDefault to true to make this App the default App for your account.

Path parameters

Property nameTypeRequiredPIIDescription

appNamestring

required

Not PII

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

Request body parameters

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

isDefaultboolean

required

Not PII

Whether this App is the default (Push Notification) App for the Account.

Set to true to set this App as the default App.

Responses

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.

This error indicates that the request content was malformed or ambiguous.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the requested resource was not found.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that you have sent too many requests to the API. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the Twilio API is experiencing server-side issues. The request should not be retried.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

This error indicates that the Twilio API is temporarily unavailable. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[TwilioError]

Optional

A list of one or more Twilio API errors.

Show errors properties

Update a PushNotification App

1import { TwilioClient } from "twilio-comms";
2
3async function main() {
4    const client = new TwilioClient({
5        accountId: "<username>",
6        authToken: "<password>",
7    });
8    await client.pushNotifications.apps.update("appName", {
9        isDefault: true,
10    });
11}
12main();