Operations 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 Operation resource represents a push notification request that targets one or more recipients. When you send a notification, the API validates the input and returns an HTTP 202 Accepted response with an operationId in the response body. Use the operationId to monitor the status and delivery progress of the request.

As the Operation is processed, it generates a PushNotification with an associated pushNotificationId for each recipient. Each PushNotification then creates at least one delivery attempt for each provider (FCM or APNs) that is tried.

(information)

Info

Records are available for 7 days after creation. Requests for data older than 7 days may return incomplete results.

Operation Properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

required

Not PII

The Operation ID is an identifier that can be used to correlate all of the resources created in a request.

Issue a GET request to the resource list location, using the Operation ID as a query parameter to retrieve the resources that correlate with the Operation.

Example: comms_operation_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_operation_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

statusenum<string>

required

Not PII

The status of an Operation.

Possible values:

SCHEDULEDPROCESSINGCOMPLETEDCANCELED

statsPushNotificationOperationStats

required

Not PII

Represents the stats of a sending operation of one or many Push Notifications.

total is the total number of Push Notifications in the Operation.
- To get the status for each Push Notification, fetch the resource with: GET /PushNotifications/{pushNotificationId}.
recipients is the total number of recipients targeted in an Operation.
unaddressable is the number of recipients to which no sending attempts were made because a valid token could not be found in the recipient's Device Registration set for the Credentials or App provided.
scheduled is the number of Push Notifications that are scheduled to be sent by Twilio in the future.
queued is the number of Push Notifications that are queued in Twilio for sending.
sent is the number of Push Notifications that have been sent by Twilio.
failed is the number of Push Notifications that failed during processing by Twilio. Get Errors with GET /PushNotifications/Operations/{operationId}/Errors fore more detail.
canceled is the number of Push Notifications that were canceled via API request.

Example: {"total":1,"recipients":1,"queued":0,"sent":0,"scheduled":0,"unaddressable":0,"failed":0,"canceled":0}

Show stats properties

createdAtstring<date-time>

required

Not PII

updatedAtstring<date-time>

required

Not PII

Operation status values

Status	Description
`SCHEDULED`	The operation is scheduled for future processing.
`PROCESSING`	The operation is currently being processed.
`COMPLETED`	All notifications in the operation have been processed.
`CANCELED`	The operation was canceled.

Operation stats

The stats object in the response provides aggregated delivery metrics:

Field	Description
`total`	Total push notifications in the operation.
`recipients`	Total targeted recipients.
`unaddressable`	Recipients with no valid device token found.
`scheduled`	Notifications scheduled for future sending.
`queued`	Notifications queued for sending.
`sent`	Notifications sent to the provider.
`failed`	Notifications that failed during processing.
`canceled`	Notifications canceled via the API.

Fetch an Operation

GET https://comms.twilio.com/v1/PushNotifications/Operations/{operationId}

Retrieve the status and delivery statistics of a push notification operation by making an HTTP GET request to the Operation resource URI with the Operation ID.

Path parameters

Property nameTypeRequiredPIIDescription

operationIdstring

required

Not PII

Example: comms_operation_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_operation_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

Responses

200400404429500503

Schema

Property nameTypeRequiredDescriptionChild properties

idstring

Optional

The Operation ID is an identifier that can be used to correlate all of the resources created in a request.

Issue a GET request to the resource list location, using the Operation ID as a query parameter to retrieve the resources that correlate with the Operation.

Example: comms_operation_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_operation_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

statusenum<string>

Optional

The status of an Operation.

Possible values:

SCHEDULEDPROCESSINGCOMPLETEDCANCELED

statsPushNotificationOperationStats

Optional

Represents the stats of a sending operation of one or many Push Notifications.

total is the total number of Push Notifications in the Operation.
- To get the status for each Push Notification, fetch the resource with: GET /PushNotifications/{pushNotificationId}.
recipients is the total number of recipients targeted in an Operation.
unaddressable is the number of recipients to which no sending attempts were made because a valid token could not be found in the recipient's Device Registration set for the Credentials or App provided.
scheduled is the number of Push Notifications that are scheduled to be sent by Twilio in the future.
queued is the number of Push Notifications that are queued in Twilio for sending.
sent is the number of Push Notifications that have been sent by Twilio.
failed is the number of Push Notifications that failed during processing by Twilio. Get Errors with GET /PushNotifications/Operations/{operationId}/Errors fore more detail.
canceled is the number of Push Notifications that were canceled via API request.

Example: {"total":1,"recipients":1,"queued":0,"sent":0,"scheduled":0,"unaddressable":0,"failed":0,"canceled":0}

Show stats 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 Operation

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.fetchOperation("comms_operation_01h9krwprkeee8fzqspvwy6nq8");
9}
10main();

List Operations

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

Returns a list of Operations. You can filter by date range or status.

Query parameters

Property nameTypeRequiredPIIDescription

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

startDatestring<date-time>

Optional

Not PII

Filter to Operations created after the specified date and time.

endDatestring<date-time>

Optional

Not PII

Filter to Operations created before the specified date and time.

statusenum<string>

Optional

Not PII

Filter to Operations with the specified status.

Possible values:

SCHEDULEDPROCESSINGCOMPLETEDCANCELED

Responses

200400429500503

Schema

Property nameTypeRequiredDescriptionChild properties

operationsarray[PushNotificationOperation]

Optional

A list of Push Notification Operations.

Show operations properties

Property nameTypeRequiredDescriptionChild properties

idstring

Optional

The Operation ID is an identifier that can be used to correlate all of the resources created in a request.

Issue a GET request to the resource list location, using the Operation ID as a query parameter to retrieve the resources that correlate with the Operation.

Example: comms_operation_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_operation_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

statusenum<string>

Optional

The status of an Operation.

Possible values:

SCHEDULEDPROCESSINGCOMPLETEDCANCELED

statsPushNotificationOperationStats

Optional

Represents the stats of a sending operation of one or many Push Notifications.

total is the total number of Push Notifications in the Operation.
- To get the status for each Push Notification, fetch the resource with: GET /PushNotifications/{pushNotificationId}.
recipients is the total number of recipients targeted in an Operation.
unaddressable is the number of recipients to which no sending attempts were made because a valid token could not be found in the recipient's Device Registration set for the Credentials or App provided.
scheduled is the number of Push Notifications that are scheduled to be sent by Twilio in the future.
queued is the number of Push Notifications that are queued in Twilio for sending.
sent is the number of Push Notifications that have been sent by Twilio.
failed is the number of Push Notifications that failed during processing by Twilio. Get Errors with GET /PushNotifications/Operations/{operationId}/Errors fore more detail.
canceled is the number of Push Notifications that were canceled via API request.

Example: {"total":1,"recipients":1,"queued":0,"sent":0,"scheduled":0,"unaddressable":0,"failed":0,"canceled":0}

Show stats properties

createdAtstring<date-time>

Optional

updatedAtstring<date-time>

Optional

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 Operations

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.listOperations({
9        pageToken: "pageToken",
10        pageSize: 50,
11        startDate: new Date("2024-01-15T09:30:00Z"),
12        endDate: new Date("2024-01-15T09:30:00Z"),
13        status: "SCHEDULED",
14    });
15}
16main();