Menu
Amazon Pinpoint
REST API Reference

Messages

Use this resource to 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 recipients. 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 sending a direct message.

You can send a direct message as a push notification to your mobile app or as an SMS message to SMS-enabled devices.

URI

/v1/apps/application-id/messages

HTTP Methods

POST

Send a batch of messages

Body

Name Required Type

MessageRequest

true

MessageRequest

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

Response

Status Code Schema

200

MessageResponse

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 MessageRequest

Copy
{ "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" }, "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" } }, "Addresses": {}, "Endpoints": {} }

Response Schemas

Example MessageResponse

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

Example MessageBody

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

Attributes

MessageRequest

Attribute Type Description

Addresses

object

A map of destination addresses, with the address as the key(Email address, phone number or push token) and the Address Configuration as the value.

Context

object

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

Endpoints

object

A map of destination addresses, with the address as the key(Email address, phone number or push token) and the Address Configuration as the value.

MessageConfiguration

DirectMessageConfiguration

Message configuration.

AddressConfiguration

Attribute Type Description

BodyOverride

string

Body override. If specified will override default body.

ChannelType

string

The channel type.

Valid values: GCM | APNS | APNS_SANDBOX | APNS_VOIP | APNS_VOIP_SANDBOX | ADM | SMS | EMAIL | BAIDU

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.

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.

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, the email body or the text message.

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, the email body or the text message.

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, the email body or the text message.

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.

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, the email body or the text message.

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, the email body or the text message.

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 message body of the notification, the email body or the text message.

MessageType

string

Is this a transaction priority message or lower priority.

SenderId

string

Sender ID of sent message.

Substitutions

object

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

MessageResponse

Attribute Type Description

ApplicationId

string

Application id of the message.

EndpointResult

object

A map containing a multi part response for each address, with the endpointId as the key and the result as the value.

RequestId

string

Original request Id for which this message was delivered.

Result

object

A map containing a multi part response for each address, with the address as the key(Email address, phone number or push token) and the result as the value.

EndpointMessageResult

Attribute Type Description

Address

string

Address that endpoint message was delivered to.

DeliveryStatus

string

Delivery status of message.

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)

MessageResult

Attribute Type Description

DeliveryStatus

string

Delivery status of message.

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 returned from the API.

RequestID

string

The unique message body ID.