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 in the Amplify Framework Documentation.

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.

JavaScript

Create the client in a separate module and export it:

import { PinpointClient } from "@aws-sdk/client-pinpoint";
const REGION = "us-east-1";
const pinClient = new PinpointClient({ region: REGION });
export { pinClient };

Retrieve in-app messages for an endpoint:

// Import required AWS SDK clients and commands for Node.js
import { PinpointClient, GetInAppMessagesCommand } from "@aws-sdk/client-pinpoint";
import { pinClient } from "./lib/pinClient.js";

("use strict");

//The Amazon Pinpoint application ID.
const projectId = "4c545b28d21a490cb51b0b364example";

//The ID of the endpoint to retrieve messages for.
const endpointId = "c5ac671ef67ee3ad164cf7706example";

const params = {
  ApplicationId: projectId,
  EndpointId: endpointId
};

const run = async () => {
  try {
    const data = await pinClient.send(new GetInAppMessagesCommand(params));
    console.log(JSON.stringify(data, null, 4));
    return data; 
  } catch (err) {
    console.log("Error", err);
  }
};
run();

Python

import logging
import boto3
from botocore.exceptions import ClientError

logger = logging.getLogger(__name__)

def retrieve_inapp_messages(
            pinpoint_client, project_id, endpoint_id):
    """
    Retrieves the in-app messages that a given endpoint is entitled to.

    :param pinpoint_client: A Boto3 Pinpoint client.
    :param project_id: An Amazon Pinpoint project ID.
    :param endpoint_id: The ID of the endpoint to retrieve messages for.
    :return: A JSON object that contains information about the in-app message.
    """

    try:
        response = pinpoint_client.get_in_app_messages(
            ApplicationId=project_id,
            EndpointId=endpoint_id)
    except ClientError:
        logger.exception("Couldn't retrieve messages.")
        raise
    else:
        return response

def main():
    project_id = "4c545b28d21a490cb51b0b364example"
    endpoint_id = "c5ac671ef67ee3ad164cf7706example"
    inapp_response = retrieve_inapp_messages(
        boto3.client('pinpoint'), project_id, endpoint_id)
    print(inapp_response)

if __name__ == '__main__':
    main()

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
CampaignId	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.
TreatmentId	An integer that represents the ID of the campaign treatment for this message. If the campaign only has one treatment, the value is 0.
Priority	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.
InAppMessage	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.
Schedule	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 Schedule object (if the campaign was created using the API or an SDK).
DailyCap	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.
SessionCap	The number of times, expressed as an integer, that an in-app message can be shown to the user during an application session.
TotalCap	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
Content	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.
Layout	A string that describes how the in-app message will appear on the recipient's device. Possible values are: BOTTOM_BANNER – a message that appears as a banner at the bottom of the page. TOP_BANNER – a message that appears as a banner at the top of the page. OVERLAYS – a message that covers entire screen. MOBILE_FEED – a message that appears in a window in front of the page. MIDDLE_BANNER – a message that appears as a banner in the middle of the page. CAROUSEL – a scrollable layout of up to five unique messages.

HeaderConfig object

The HeaderConfig object contains the following attributes:

Attribute	Description	Where it's set
Alignment	A string that specifies the text alignment of the header text. Possible values are LEFT, CENTER, and RIGHT.	Based on the content in the in-app message template that was specified for the campaign.
Header	The message header text.
TextColor	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
Alignment	A string that specifies the text alignment of the message body. Possible values are LEFT, CENTER, and RIGHT.	Based on the content in the in-app message template that was specified for the campaign.
Body	The main body text of the message.
TextColor	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
BackgroundColor	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.
BodyConfig	A BodyConfig object, which contains information related to the main body content of the message.
HeaderConfig	A HeaderConfig object, which contains information related to the header or title of the message.
ImageUrl	The URL of the image that appears in the message.
PrimaryBtn	An InAppMessageButton object that contains information about the main button in the message.
SecondaryBtn	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
EndDate	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 Schedule object (if the campaign was created using the API or an SDK).
EventFilter	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
DefaultConfig	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.
Android	An OverrideButtonConfig object that specifies the way the button behaves on Android devices. This overrides the default button configuration detailed in the DefaultConfig object.
IOS	An OverrideButtonConfig object that specifies the way the button behaves on iOS devices. This overrides the default button configuration detailed in the DefaultConfig object.
Web	An OverrideButtonConfig object that specifies the way the button behaves in web apps. This overrides the default button configuration detailed in the DefaultConfig object.

DefaultButtonConfig object

An DefaultButtonConfig object contains the following attributes:

Attribute	Description	Where it's set
BackgroundColor	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.
BorderRadius	The radius of the button's border in pixels, expressed as an integer. A larger number results in more rounded corners.
ButtonAction	A string that describes the action that occurs when a recipient chooses a button in the in-app message. Possible values are: LINK – A link to a web destination. DEEP_LINK – A link to a specific page in an application. CLOSE – Dismisses the message.
Link	The destination URL for a button. Not present for buttons where the ButtonAction is CLOSE.
Text	The text that appears on the button.
TextColor	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
ButtonAction	The action that occurs when a recipient chooses a button in the in-app message. Possible values are: LINK – A link to a web destination. DEEP_LINK – A link to a specific page in an application. CLOSE – Dismisses the message.	Based on the content in the in-app message template that was specified for the campaign.
Link	The destination URL for a button. Not present for buttons where the ButtonAction is CLOSE.
Text	The text that appears on the button.
TextColor	The color of the text on the button, expressed as a string containing a hex color code (such as "#000000" for black).