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

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


{
  "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",
      "Keyword": "string",
      "OriginationNumber": "string"
    }
  },
  "Addresses": {},
  "Endpoints": {}
}

Response Schemas

Example MessageResponse


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

Example MessageBody


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

Attributes

MessageRequest

Attribute	Type	Description
Addresses	object	A map of key-value pairs, where each key is an address and each value is an AddressConfiguration object. An address can be a push notification token, a phone number, or an email address.
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 key-value pairs, where each key is an endpoint ID and each value is an EndpointSendConfiguration object. Within an EndpointSendConfiguration object, you can tailor the message for an endpoint by specifying message overrides or substitutions.
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.
EmailMessage	EmailMessage	The message to Email channels. Overrides the default message.
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.

EmailMessage

Attribute	Type	Description
Body	string	The message body of the notification, the email body or the text message.
FeedbackForwardingAddress	string	The email address that bounces and complaints will be forwarded to when feedback forwarding is enabled.
FromAddress	string	The email address used to send the email from. Defaults to use FromAddress specified in the Email Channel.
RawEmail	RawEmail	An email represented as a raw MIME message.
ReplyToAddresses	array	The reply-to email address(es) for the email. If the recipient replies to the email, each reply-to address will receive the reply.
SimpleEmail	SimpleEmail	An email composed of a subject, a text part and a html part.
Substitutions	object	Default message substitutions. Can be overridden by individual address substitutions.

RawEmail

Attribute	Type	Description
Data	string	The raw data of the email.

SimpleEmail

Attribute	Type	Description
HtmlPart	SimpleEmailPart	The content of the message, in HTML format. Use this for email clients that can process HTML. You can include clickable links, formatted text, and much more in an HTML message.
Subject	SimpleEmailPart	The subject of the message: A short summary of the content, which will appear in the recipient's inbox.
TextPart	SimpleEmailPart	The content of the message, in text format. Use this for text-based email clients, or clients on high-latency networks (such as mobile devices).

SimpleEmailPart

Attribute	Type	Description
Charset	string	The character set of the content.
Data	string	The textual data of the content.

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

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

MessageResult

Attribute	Type	Description
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 returned from the API.
RequestID	string	The unique message body ID.

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »

Apr	MAY	Jun
	15
2017	2018	2019