Sending and retrieving in-app messages in Amazon Pinpoint
You can use in-app messages to send targeted messages to users of your applications. In-app messages are highly customizable. They can include buttons that open websites or take users to specific parts of your app. You can configure background and text colors, position the text, and add buttons and images to the notification. You can send a single message, or create a carousel that contains up to five unique messages. For an overview of in-app messages, including instructions for creating in-app message templates, see Creating in-app templates in the Amazon Pinpoint User Guide.
You can use AWS Amplify to seamlessly integrate the in-app messaging capabilities of
Amazon Pinpoint into your app. Amplify can automatically handle the processes of fetching messages,
rendering messages, and sending analytics data to Amazon Pinpoint. This integration is currently
supported for React Native applications. For more information, see In-App Messaging
This section provides information about requesting the in-app messages for an endpoint in your app, and for interpreting the result of that request.
Retrieving in-app messages for an endpoint
Your applications can call the GetInAppMessages API to retrieve all of the in-app messages that a given
endpoint is entitled to. When you call the GetInAppMessages
API, you
provide the following parameters:
-
ApplicationId
– The unique ID of the Amazon Pinpoint project that the in-app message campaign is associated with. -
EndpointId
– The unique ID of the endpoint that you're retrieving messages for.
When you call the API with these values, it returns a list of messages. For more information about the response produced by this operation, see Understanding GetInAppMessages API responses.
You can use the AWS SDKs to call the GetInAppMessages
operation. The
following code examples include functions that retrieve in-app messages.
Understanding GetInAppMessages
API responses
When you call the GetInAppMessages API operation, it returns a list of messages that the specified endpoint is entitled to. Your app can then render the message based on the values in the response.
The following is an example of the JSON object that is returned when you call the
GetInAppMessages
API:
{ "InAppMessagesResponse":{ "InAppMessageCampaigns":[ { "CampaignId":"inAppTestCampaign-4c545b28d21a490cb51b0b364example", "DailyCap":0, "InAppMessage":{ "Content":[ { "BackgroundColor":"#f8e71c", "BodyConfig":{ "Alignment":"CENTER", "Body":"This is a sample in-app message sent using Amazon Pinpoint.", "TextColor":"#d0021b" }, "HeaderConfig":{ "Alignment":"CENTER", "Header":"Sample In-App Message", "TextColor":"#d0021b" }, "ImageUrl":"https://example.com/images/thumbnail.png", "PrimaryBtn":{ "DefaultConfig":{ "BackgroundColor":"#d0021b", "BorderRadius":50, "ButtonAction":"CLOSE", "Text":"Dismiss", "TextColor":"#f8e71c" } } } ], "Layout":"MIDDLE_BANNER" }, "Priority":3, "Schedule":{ "EndDate":"2021-11-06T00:08:05Z", "EventFilter":{ "Dimensions":{ "Attributes":{ }, "EventType":{ "DimensionType":"INCLUSIVE", "Values":[ "_session.start" ] }, "Metrics":{ } } } }, "SessionCap":0, "TotalCap":0, "TreatmentId":"0" } ] } }
The following sections provide more information about the components of this response.
InAppMessageCampaigns
object
The InAppMessageCampaigns
object contains the following
attributes:
Attribute | Description | Where it's set |
---|---|---|
|
A string that contains the name and unique campaign ID of the Amazon Pinpoint campaign that the message was sent from. The name precedes the campaign ID. The two values are separated with a hyphen (-). |
Automatically created by Amazon Pinpoint when you create the campaign. |
|
An integer that represents the ID of the campaign treatment
for this message. If the campaign only has one treatment, the
value is |
|
|
The priority of the in-app message, expressed as an integer between 1 and 5, inclusive, where 1 indicates the highest priority, and 5 indicates the lowest priority. |
Step 1 of the campaign creation process. |
|
An InAppMessage object that contains information about how the message is rendered. |
Based on the content in the in-app message template that was specified for the campaign. |
|
A Schedule object that contains information about when the message was sent. |
Step
4 of the campaign creation process (if the campaign
was created in the console) or the |
|
The number of times, shown as an integer, that an in-app message can be shown to the user during a 24-hour period. |
Inherited from project-level settings. If the campaign includes settings that override the project settings, then those are used instead. |
|
The number of times, expressed as an integer, that an in-app message can be shown to the user during an application session. |
|
|
The total number of times, expressed as an integer, that any in-app message can be shown to an endpoint per campaign. |
InAppMessage
object
The InAppMessage
object contains the following attributes:
Attribute | Description | Where it's set |
---|---|---|
|
An array containing an InAppMessageContent object, which describes the content of the message. |
Based on the content in the in-app message template that was specified for the campaign. |
|
A string that describes how the in-app message will appear on the recipient's device. Possible values are:
|
HeaderConfig
object
The HeaderConfig
object contains the following attributes:
Attribute | Description | Where it's set |
---|---|---|
|
A string that specifies the text alignment of the header
text. Possible values are |
Based on the content in the in-app message template that was specified for the campaign. |
|
The message header text. |
|
|
The color of the header text, expressed as string describing the hex color code (such as "#000000" for black). |
BodyConfig
object
The BodyConfig
object contains the following attributes:
Attribute | Description | Where it's set |
---|---|---|
|
A string that specifies the text alignment of the message
body. Possible values are |
Based on the content in the in-app message template that was specified for the campaign. |
|
The main body text of the message. |
|
|
The color of the body text, expressed as a string containing a hex color code (such as "#000000" for black). |
InAppMessageContent
object
The InAppMessageContent
object contains the following
attributes:
Attribute | Description | Where it's set |
---|---|---|
|
The background color of the in-app message, expressed as a string containing a hex color code (such as "#000000" for black). |
Based on the content in the in-app message template that was specified for the campaign. |
|
A BodyConfig object, which contains information related to the main body content of the message. |
|
|
A HeaderConfig object, which contains information related to the header or title of the message. |
|
|
The URL of the image that appears in the message. |
|
|
An InAppMessageButton object that contains information about the main button in the message. |
|
|
An InAppMessageButton object that contains information about the secondary button in the message. Not present if the in-app message template doesn't specify a secondary button. |
Schedule
object
The Schedule
object contains the following attributes:
Attribute | Description | Where it's set |
---|---|---|
|
The scheduled time, in ISO 8601 format, when the campaign will end. |
Step 4 of
the campaign creation process (if the campaign was created in
the console) or the |
|
Information about the event that causes the in-app message to be shown. When you generate an event that matches with an Amazon Pinpoint in-app campaign, the message is displayed. |
InAppMessageButton
object
An InAppMessageButton
object contains the following
attributes:
Attribute | Description | Where it's set |
---|---|---|
|
A DefaultButtonConfig object that contains information about the default settings for a button in an in-app message. |
Based on the content in the in-app message template that was specified for the campaign. |
|
An OverrideButtonConfig object that specifies the way
the button behaves on Android devices. This overrides the
default button configuration detailed in the
|
|
|
An OverrideButtonConfig object that specifies the way
the button behaves on iOS devices. This overrides the default
button configuration detailed in the |
|
|
An OverrideButtonConfig object that specifies the way
the button behaves in web apps. This overrides the default
button configuration detailed in the |
DefaultButtonConfig
object
An DefaultButtonConfig
object contains the following
attributes:
Attribute | Description | Where it's set |
---|---|---|
|
The background color of the button, expressed as a string containing a hex color code (such as "#000000" for black). |
Based on the content in the in-app message template that was specified for the campaign. |
|
The radius of the button's border in pixels, expressed as an integer. A larger number results in more rounded corners. | |
|
A string that describes the action that occurs when a recipient chooses a button in the in-app message. Possible values are:
|
|
|
The destination URL for a button. Not present for buttons
where the ButtonAction is |
|
|
The text that appears on the button. | |
|
The color of the text on the button, expressed as a string containing a hex color code (such as "#000000" for black). |
OverrideButtonConfig
object
The OverrideButtonConfig
object is only present if the in-app message
template uses override buttons. An override button is a button that has a specific
configuration for a particular device type, such as an iOS device, Android device,
or a web browser.
An OverrideButtonConfig
object contains the following
attributes:
Attribute | Description | Where it's set |
---|---|---|
|
The action that occurs when a recipient chooses a button in the in-app message. Possible values are:
|
Based on the content in the in-app message template that was specified for the campaign. |
|
The destination URL for a button. Not present for buttons
where the |
|
|
The text that appears on the button. | |
|
The color of the text on the button, expressed as a string containing a hex color code (such as "#000000" for black). |