Menu
Amazon Pinpoint
REST API Reference

Users Messages

Use this resource to message a list of users. Amazon Pinpoint sends the message to all of the endpoints that are associated with each user.

A user represents an individual who is assigned a unique user ID, and this ID is assigned to one or more endpoints. For example, if an individual uses your app on multiple devices, your app could assign that person's user ID to the endpoint for each device.

With the users-messages resource, you specify the message recipients as user IDs. For each user ID, Amazon Pinpoint delivers the message to all of the user's endpoints. Within the body of your request, you can specify a default message, and you can tailor your message for different channels, including those for mobile push and SMS.

With this resource, you send a direct message, which is a one time message that you send to a limited audience without creating a campaign. You can send the message to up to 100 users per request. You cannot use the message to engage a segment. When you send the message, Amazon Pinpoint delivers it immediately, and you cannot schedule the delivery. To engage a user segment, and to schedule the message delivery, create a campaign instead of using the users-messages resource.

URI

/v1/apps/application-id/users-messages

HTTP Methods

POST

Use this resource to message a list of users. Amazon Pinpoint sends the message to all of the endpoints that are associated with each user. A user represents an individual who is assigned a unique user ID, and this ID is assigned to one or more endpoints. For example, if an individual uses your app on multiple devices, your app could assign that person's user ID to the endpoint for each device. With the users-messages resource, you specify the message recipients as user IDs. For each user ID, Amazon Pinpoint delivers the message to all of the user's endpoints. Within the body of your request, you can specify a default message, and you can tailor your message for different channels, including those for mobile push and SMS. With this resource, you send a direct message, which is a one time message that you send to a limited audience without creating a campaign. You can send the message to up to 100 users per request. You cannot use the message to engage a segment. When you send the message, Amazon Pinpoint delivers it immediately, and you cannot schedule the delivery. To engage a user segment, and to schedule the message delivery, create a campaign instead of using the users-messages resource.

Body

Name Required Type

SendUsersMessageRequest

true

SendUsersMessageRequest

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

Response

Status Code Schema

200

SendUsersMessageResponse

Errors

Errors

Status Code Schema Error Type

400

MessageBody

BadRequestException

403

MessageBody

ForbiddenException

404

MessageBody

NotFoundException

405

MessageBody

MethodNotAllowedException

429

MessageBody

TooManyRequestsException

500

MessageBody

InternalServerErrorException

Schemas

Request Schemas

Example SendUsersMessageRequest

{ "Context": {}, "MessageConfiguration": { "DefaultMessage": { "Body": "string", "Substitutions": {} }, "DefaultPushNotificationMessage": { "Body": "string", "Substitutions": {}, "Title": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "Data": {} }, "APNSMessage": { "Body": "string", "Substitutions": {}, "Title": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "Data": {}, "MediaUrl": "string", "Sound": "string", "Badge": 0, "Category": "string", "ThreadId": "string", "RawContent": "string", "PreferredAuthenticationMethod": "string", "TimeToLive": 0, "Priority": "string", "CollapseId": "string" }, "GCMMessage": { "Body": "string", "Substitutions": {}, "Title": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "Data": {}, "IconReference": "string", "Sound": "string", "ImageUrl": "string", "ImageIconUrl": "string", "SmallImageIconUrl": "string", "RawContent": "string", "CollapseKey": "string", "RestrictedPackageName": "string", "TimeToLive": 0, "Priority": "string" }, "BaiduMessage": { "Body": "string", "Substitutions": {}, "Title": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "Data": {}, "IconReference": "string", "Sound": "string", "ImageUrl": "string", "ImageIconUrl": "string", "SmallImageIconUrl": "string", "RawContent": "string", "TimeToLive": 0 }, "ADMMessage": { "Body": "string", "Substitutions": {}, "Title": "string", "Action": "OPEN_APP", "Url": "string", "SilentPush": true, "Data": {}, "IconReference": "string", "Sound": "string", "ImageUrl": "string", "ImageIconUrl": "string", "SmallImageIconUrl": "string", "RawContent": "string", "ConsolidationKey": "string", "ExpiresAfter": "string", "MD5": "string" }, "SMSMessage": { "Body": "string", "Substitutions": {}, "SenderId": "string", "MessageType": "TRANSACTIONAL", "Keyword": "string", "OriginationNumber": "string" } }, "Users": {} }

Response Schemas

Example SendUsersMessageResponse

{ "RequestId": "string", "ApplicationId": "string", "Result": {} }

Example MessageBody

{ "RequestID": "string", "Message": "string" }

Attributes

SendUsersMessageRequest

Attribute Type Description

Context

object

A map of custom attribute-value pairs. Amazon Pinpoint adds these attributes to the data.pinpoint object in the body of the push notification payload. Amazon Pinpoint also provides these attributes in the events that it generates for users-messages deliveries.

MessageConfiguration

DirectMessageConfiguration

Message definitions for the default message and any messages that are tailored for specific channels.

Users

object

A map that associates user IDs with EndpointSendConfiguration objects. Within an EndpointSendConfiguration object, you can tailor the message for a user by specifying message overrides or substitutions.

DirectMessageConfiguration

Attribute Type Description

ADMMessage

ADMMessage

The message to ADM channels. Overrides the default push notification message.

APNSMessage

APNSMessage

The message to APNS channels. Overrides the default push notification message.

BaiduMessage

BaiduMessage

The message to Baidu GCM channels. Overrides the default push notification message.

DefaultMessage

DefaultMessage

The default message for all channels.

DefaultPushNotificationMessage

DefaultPushNotificationMessage

The default push notification message for all push channels.

GCMMessage

GCMMessage

The message to GCM channels. Overrides the default push notification message.

SMSMessage

SMSMessage

The message to SMS channels. Overrides the default message.

ADMMessage

Attribute Type Description

Action

string

The action that occurs if the user taps a push notification delivered by the campaign: OPEN_APP - Your app launches, or it becomes the foreground app if it has been sent to the background. This is the default action. DEEP_LINK - Uses deep linking features in iOS and Android to open your app and display a designated user interface within the app. URL - The default mobile browser on the user's device launches and opens a web page at the URL you specify. Possible values include: OPEN_APP | DEEP_LINK | URL

Body

string

The message body of the notification.

ConsolidationKey

string

Optional. Arbitrary string used to indicate multiple messages are logically the same and that ADM is allowed to drop previously enqueued messages in favor of this one.

Data

object

The data payload used for a silent push. This payload is added to the notifications' data.pinpoint.jsonBody' object

ExpiresAfter

string

Optional. Number of seconds ADM should retain the message if the device is offline

IconReference

string

The icon image name of the asset saved in your application.

ImageIconUrl

string

The URL that points to an image used as the large icon to the notification content view.

ImageUrl

string

The URL that points to an image used in the push notification.

MD5

string

Optional. Base-64-encoded MD5 checksum of the data parameter. Used to verify data integrity

RawContent

string

The Raw JSON formatted string to be used as the payload. This value overrides the message.

SilentPush

boolean

Indicates if the message should display on the users device. Silent pushes can be used for Remote Configuration and Phone Home use cases.

SmallImageIconUrl

string

The URL that points to an image used as the small icon for the notification which will be used to represent the notification in the status bar and content view

Sound

string

Indicates a sound to play when the device receives the notification. Supports default, or the filename of a sound resource bundled in the app. Android sound files must reside in /res/raw/

Substitutions

object

Default message substitutions. Can be overridden by individual address substitutions.

Title

string

The message title that displays above the message on the user's device.

Url

string

The URL to open in the user's mobile browser. Used if the value for Action is URL.

APNSMessage

Attribute Type Description

Action

string

The action that occurs if the user taps a push notification delivered by the campaign: OPEN_APP - Your app launches, or it becomes the foreground app if it has been sent to the background. This is the default action. DEEP_LINK - Uses deep linking features in iOS and Android to open your app and display a designated user interface within the app. URL - The default mobile browser on the user's device launches and opens a web page at the URL you specify. Possible values include: OPEN_APP | DEEP_LINK | URL

Badge

integer

Include this key when you want the system to modify the badge of your app icon. If this key is not included in the dictionary, the badge is not changed. To remove the badge, set the value of this key to 0.

Body

string

The message body of the notification.

Category

string

Provide this key with a string value that represents the notification's type. This value corresponds to the value in the identifier property of one of your app's registered categories.

CollapseId

string

An ID that, if assigned to multiple messages, causes APNs to coalesce the messages into a single push notification instead of delivering each message individually. The value must not exceed 64 bytes. Amazon Pinpoint uses this value to set the apns-collapse-id request header when it sends the message to APNs.

Data

object

The data payload used for a silent push. This payload is added to the notifications' data.pinpoint.jsonBody' object

MediaUrl

string

The URL that points to a video used in the push notification.

PreferredAuthenticationMethod

string

The preferred authentication method, either "CERTIFICATE" or "TOKEN"

Priority

string

The message priority. Amazon Pinpoint uses this value to set the apns-priority request header when it sends the message to APNs. Accepts the following values:

"5" - Low priority. Messages might be delayed, delivered in groups, and throttled.

"10" - High priority. Messages are sent immediately. High priority messages must cause an alert, sound, or badge on the receiving device.

The default value is "10".

The equivalent values for FCM or GCM messages are "normal" and "high". Amazon Pinpoint accepts these values for APNs messages and converts them.

For more information about the apns-priority parameter, see Communicating with APNs in the APNs Local and Remote Notification Programming Guide.

RawContent

string

The Raw JSON formatted string to be used as the payload. This value overrides the message.

SilentPush

boolean

Indicates if the message should display on the users device. Silent pushes can be used for Remote Configuration and Phone Home use cases.

Sound

string

Include this key when you want the system to play a sound. The value of this key is the name of a sound file in your app's main bundle or in the Library/Sounds folder of your app's data container. If the sound file cannot be found, or if you specify defaultfor the value, the system plays the default alert sound.

Substitutions

object

Default message substitutions. Can be overridden by individual address substitutions.

ThreadId

string

Provide this key with a string value that represents the app-specific identifier for grouping notifications. If you provide a Notification Content app extension, you can use this value to group your notifications together.

TimeToLive

integer

The length of time (in seconds) that APNs stores and attempts to deliver the message. If the value is 0, APNs does not store the message or attempt to deliver it more than once. Amazon Pinpoint uses this value to set the apns-expiration request header when it sends the message to APNs.

Title

string

The message title that displays above the message on the user's device.

Url

string

The URL to open in the user's mobile browser. Used if the value for Action is URL.

BaiduMessage

Attribute Type Description

Action

string

The action that occurs if the user taps a push notification delivered by the campaign: OPEN_APP - Your app launches, or it becomes the foreground app if it has been sent to the background. This is the default action. DEEP_LINK - Uses deep linking features in iOS and Android to open your app and display a designated user interface within the app. URL - The default mobile browser on the user's device launches and opens a web page at the URL you specify. Possible values include: OPEN_APP | DEEP_LINK | URL

Body

string

The message body of the notification.

Data

object

The data payload used for a silent push. This payload is added to the notifications' data.pinpoint.jsonBody' object

IconReference

string

The icon image name of the asset saved in your application.

ImageIconUrl

string

The URL that points to an image used as the large icon to the notification content view.

ImageUrl

string

The URL that points to an image used in the push notification.

RawContent

string

The Raw JSON formatted string to be used as the payload. This value overrides the message.

SilentPush

boolean

Indicates if the message should display on the users device. Silent pushes can be used for Remote Configuration and Phone Home use cases.

SmallImageIconUrl

string

The URL that points to an image used as the small icon for the notification which will be used to represent the notification in the status bar and content view

Sound

string

Indicates a sound to play when the device receives the notification. Supports default, or the filename of a sound resource bundled in the app. Android sound files must reside in /res/raw/

Substitutions

object

Default message substitutions. Can be overridden by individual address substitutions.

TimeToLive

integer

This parameter specifies how long (in seconds) the message should be kept in Baidu storage if the device is offline. The and the default value and the maximum time to live supported is 7 days (604800 seconds)

Title

string

The message title that displays above the message on the user's device.

Url

string

The URL to open in the user's mobile browser. Used if the value for Action is URL.

DefaultMessage

Attribute Type Description

Body

string

The message body of the notification, the email body or the text message.

Substitutions

object

Default message substitutions. Can be overridden by individual address substitutions.

DefaultPushNotificationMessage

Attribute Type Description

Action

string

The action that occurs if the user taps a push notification delivered by the campaign: OPEN_APP - Your app launches, or it becomes the foreground app if it has been sent to the background. This is the default action. DEEP_LINK - Uses deep linking features in iOS and Android to open your app and display a designated user interface within the app. URL - The default mobile browser on the user's device launches and opens a web page at the URL you specify. Possible values include: OPEN_APP | DEEP_LINK | URL

Body

string

The message body of the notification.

Data

object

The data payload used for a silent push. This payload is added to the notifications' data.pinpoint.jsonBody' object

SilentPush

boolean

Indicates if the message should display on the users device. Silent pushes can be used for Remote Configuration and Phone Home use cases.

Substitutions

object

Default message substitutions. Can be overridden by individual address substitutions.

Title

string

The message title that displays above the message on the user's device.

Url

string

The URL to open in the user's mobile browser. Used if the value for Action is URL.

GCMMessage

Attribute Type Description

Action

string

The action that occurs if the user taps a push notification delivered by the campaign: OPEN_APP - Your app launches, or it becomes the foreground app if it has been sent to the background. This is the default action. DEEP_LINK - Uses deep linking features in iOS and Android to open your app and display a designated user interface within the app. URL - The default mobile browser on the user's device launches and opens a web page at the URL you specify. Possible values include: OPEN_APP | DEEP_LINK | URL

Body

string

The message body of the notification.

CollapseKey

string

This parameter identifies a group of messages (e.g., with collapse_key: "Updates Available") that can be collapsed, so that only the last message gets sent when delivery can be resumed. This is intended to avoid sending too many of the same messages when the device comes back online or becomes active.

Data

object

The data payload used for a silent push. This payload is added to the notifications' data.pinpoint.jsonBody' object

IconReference

string

The icon image name of the asset saved in your application.

ImageIconUrl

string

The URL that points to an image used as the large icon to the notification content view.

ImageUrl

string

The URL that points to an image used in the push notification.

Priority

string

The message priority. Amazon Pinpoint uses this value to set the FCM or GCM priority parameter when it sends the message. Accepts the following values:

"Normal" - Messages might be delayed. Delivery is optimized for battery usage on the receiving device. Use normal priority unless immediate delivery is required.

"High" - Messages are sent immediately and might wake a sleeping device.

The equivalent values for APNs messages are "5" and "10". Amazon Pinpoint accepts these values here and converts them.

For more information, see About FCM Messages in the Firebase documentation.

RawContent

string

The Raw JSON formatted string to be used as the payload. This value overrides the message.

RestrictedPackageName

string

This parameter specifies the package name of the application where the registration tokens must match in order to receive the message.

SilentPush

boolean

Indicates if the message should display on the users device. Silent pushes can be used for Remote Configuration and Phone Home use cases.

SmallImageIconUrl

string

The URL that points to an image used as the small icon for the notification which will be used to represent the notification in the status bar and content view

Sound

string

Indicates a sound to play when the device receives the notification. Supports default, or the filename of a sound resource bundled in the app. Android sound files must reside in /res/raw/

Substitutions

object

Default message substitutions. Can be overridden by individual address substitutions.

TimeToLive

integer

The length of time (in seconds) that FCM or GCM stores and attempts to deliver the message. If unspecified, the value defaults to the maximum, which is 2,419,200 seconds (28 days). Amazon Pinpoint uses this value to set the FCM or GCM time_to_live parameter.

Title

string

The message title that displays above the message on the user's device.

Url

string

The URL to open in the user's mobile browser. Used if the value for Action is URL.

SMSMessage

Attribute Type Description

Body

string

The body of the SMS message.

Keyword

string

The SMS program name that you provided to AWS Support when you requested your dedicated number.

MessageType

string

Is this a transaction priority message or lower priority.

OriginationNumber

string

The phone number that the SMS message originates from. Specify one of the dedicated long codes or short codes that you requested from AWS Support and that is assigned to your account. If this attribute is not specified, Amazon Pinpoint randomly assigns a long code.

SenderId

string

The sender ID that is shown as the message sender on the recipient's device. Support for sender IDs varies by country or region.

Substitutions

object

Default message substitutions. Can be overridden by individual address substitutions.

EndpointSendConfiguration

Attribute Type Description

BodyOverride

string

Body override. If specified will override default body.

Context

object

A map of custom attributes to attributes to be attached to the message for this address. This payload is added to the push notification's 'data.pinpoint' object or added to the email/sms delivery receipt event attributes.

RawContent

string

The Raw JSON formatted string to be used as the payload. This value overrides the message.

Substitutions

object

A map of substitution values for the message to be merged with the DefaultMessage's substitutions. Substitutions on this map take precedence over the all other substitutions.

TitleOverride

string

Title override. If specified will override default title if applicable.

SendUsersMessageResponse

Attribute Type Description

ApplicationId

string

The unique ID of the Amazon Pinpoint project used to send the message.

RequestId

string

The unique ID assigned to the users-messages request.

Result

object

An object that shows the endpoints that were messaged for each user. The object provides a list of user IDs. For each user ID, it provides the endpoint IDs that were messaged. For each endpoint ID, it provides an EndpointMessageResult object.

EndpointMessageResult

Attribute Type Description

Address

string

Address that endpoint message was delivered to.

DeliveryStatus

string

Delivery status of message.

MessageId

string

Unique message identifier associated with the message that was sent.

StatusCode

integer

Downstream service status code.

StatusMessage

string

Status message for message delivery.

UpdatedToken

string

If token was updated as part of delivery. (This is GCM Specific)

MessageBody

Attribute Type Description

Message

string

The error message that's returned from the API.

RequestID

string

The unique message body ID.