In-App Template - Amazon Pinpoint

In-App Template

An in-app messaging template is a type of message template that contains content and settings that you can define, save, and reuse in messages that you send to users of your applications.

When you create an in-app messaging template, you specify the layout of the message and the content contained in the message. You can also change the color and position of the message text, add buttons to the message, and add images to the message.

The In-App Template resource represents the repository of in-app messaging templates that are associated with your Amazon Pinpoint account. You can use this resource to create, retrieve, update, or delete a message template for messages that you send through the in-app messaging channel.

Amazon Pinpoint supports versioning for all types of message templates. When you use the In-App Template resource to work with a template, you can use supported parameters to specify whether your request applies to only a specific version of the template or to the overall template. For example, if you update a template, you can specify whether you want to save your updates as a new version of the template or save them to the latest existing version of the template. To retrieve information about all the versions of a template, use the Template Versions resource.

URI

/v1/templates/template-name/inapp

HTTP methods

GET

Operation ID: GetInAppTemplate

Retrieves the content and configuration of an in-app message template.

Path parameters
NameTypeRequiredDescription
template-nameStringTrue

The name of the message template. A template name must start with an alphanumeric character and can contain a maximum of 128 characters. The characters can be alphanumeric characters, underscores (_), or hyphens (-). Template names are case sensitive.

Header parameters
NameTypeRequiredDescription
acceptStringFalse

Indicates which content types, expressed as MIME types, the client understands.

Query parameters
NameTypeRequiredDescription
versionStringFalse

The unique identifier for the version of the message template to update, retrieve information about, or delete. To retrieve identifiers and other information for all the versions of a template, use the Template Versionsresource.

If specified, this value must match the identifier for an existing template version. If specified for an update operation, this value must match the identifier for the latest existing version of the template. This restriction helps ensure that race conditions don't occur.

If you don't specify a value for this parameter, Amazon Pinpoint does the following:

  • For a get operation, retrieves information about the active version of the template.

  • For an update operation, saves the updates to (overwrites) the latest existing version of the template, if the create-new-version parameter isn't used or is set to false.

  • For a delete operation, deletes the template, including all versions of the template.

Responses
Status codeResponse modelDescription
200InAppTemplateResponse

The request succeeded.

400MessageBody

The request contains a syntax error (BadRequestException).

403MessageBody

The request was denied because access to the specified resource is forbidden (ForbiddenException).

404MessageBody

The request failed because the specified resource was not found (NotFoundException).

405MessageBody

The request failed because the method is not allowed for the specified resource (MethodNotAllowedException).

413MessageBody

The request failed because the payload for the body of the request is too large (RequestEntityTooLargeException).

429MessageBody

The request failed because too many requests were sent during a certain amount of time (TooManyRequestsException).

500MessageBody

The request failed due to an unknown internal server error, exception, or failure (InternalServerErrorException).

POST

Operation ID: CreateInAppTemplate

Creates a new in-app message template.

Path parameters
NameTypeRequiredDescription
template-nameStringTrue

The name of the message template. A template name must start with an alphanumeric character and can contain a maximum of 128 characters. The characters can be alphanumeric characters, underscores (_), or hyphens (-). Template names are case sensitive.

Header parameters
NameTypeRequiredDescription
acceptStringFalse

Indicates which content types, expressed as MIME types, the client understands.

Responses
Status codeResponse modelDescription
201TemplateCreateMessageBody

The request succeeded and the specified resource was created.

400MessageBody

The request contains a syntax error (BadRequestException).

403MessageBody

The request was denied because access to the specified resource is forbidden (ForbiddenException).

405MessageBody

The request failed because the method is not allowed for the specified resource (MethodNotAllowedException).

409MessageBody

The request failed due to a conflict with the current state of the specified resource (ConflictException).

429MessageBody

The request failed because too many requests were sent during a certain amount of time (TooManyRequestsException).

500MessageBody

The request failed due to an unknown internal server error, exception, or failure (InternalServerErrorException).

PUT

Operation ID: UpdateInAppTemplate

Updates an existing in-app message template.

Path parameters
NameTypeRequiredDescription
template-nameStringTrue

The name of the message template. A template name must start with an alphanumeric character and can contain a maximum of 128 characters. The characters can be alphanumeric characters, underscores (_), or hyphens (-). Template names are case sensitive.

Header parameters
NameTypeRequiredDescription
acceptStringFalse

Indicates which content types, expressed as MIME types, the client understands.

Query parameters
NameTypeRequiredDescription
create-new-versionStringFalse

Specifies whether to save the updates as a new version of the message template. Valid values are: true, save the updates as a new version; and, false, save the updates to (overwrite) the latest existing version of the template.

If you don't specify a value for this parameter, Amazon Pinpoint saves the updates to (overwrites) the latest existing version of the template. If you specify a value of true for this parameter, don't specify a value for the version parameter. Otherwise, an error will occur.

versionStringFalse

The unique identifier for the version of the message template to update, retrieve information about, or delete. To retrieve identifiers and other information for all the versions of a template, use the Template Versionsresource.

If specified, this value must match the identifier for an existing template version. If specified for an update operation, this value must match the identifier for the latest existing version of the template. This restriction helps ensure that race conditions don't occur.

If you don't specify a value for this parameter, Amazon Pinpoint does the following:

  • For a get operation, retrieves information about the active version of the template.

  • For an update operation, saves the updates to (overwrites) the latest existing version of the template, if the create-new-version parameter isn't used or is set to false.

  • For a delete operation, deletes the template, including all versions of the template.

Responses
Status codeResponse modelDescription
202MessageBody

The request was accepted for processing. Processing may not be complete.

400MessageBody

The request contains a syntax error (BadRequestException).

403MessageBody

The request was denied because access to the specified resource is forbidden (ForbiddenException).

404MessageBody

The request failed because the specified resource was not found (NotFoundException).

405MessageBody

The request failed because the method is not allowed for the specified resource (MethodNotAllowedException).

413MessageBody

The request failed because the payload for the body of the request is too large (RequestEntityTooLargeException).

429MessageBody

The request failed because too many requests were sent during a certain amount of time (TooManyRequestsException).

500MessageBody

The request failed due to an unknown internal server error, exception, or failure (InternalServerErrorException).

DELETE

Operation ID: DeleteInAppTemplate

Deletes an existing in-app message template.

Path parameters
NameTypeRequiredDescription
template-nameStringTrue

The name of the message template. A template name must start with an alphanumeric character and can contain a maximum of 128 characters. The characters can be alphanumeric characters, underscores (_), or hyphens (-). Template names are case sensitive.

Header parameters
NameTypeRequiredDescription
acceptStringFalse

Indicates which content types, expressed as MIME types, the client understands.

Query parameters
NameTypeRequiredDescription
versionStringFalse

The unique identifier for the version of the message template to update, retrieve information about, or delete. To retrieve identifiers and other information for all the versions of a template, use the Template Versionsresource.

If specified, this value must match the identifier for an existing template version. If specified for an update operation, this value must match the identifier for the latest existing version of the template. This restriction helps ensure that race conditions don't occur.

If you don't specify a value for this parameter, Amazon Pinpoint does the following:

  • For a get operation, retrieves information about the active version of the template.

  • For an update operation, saves the updates to (overwrites) the latest existing version of the template, if the create-new-version parameter isn't used or is set to false.

  • For a delete operation, deletes the template, including all versions of the template.

Responses
Status codeResponse modelDescription
202MessageBody

The request was accepted for processing. Processing may not be complete.

400MessageBody

The request contains a syntax error (BadRequestException).

403MessageBody

The request was denied because access to the specified resource is forbidden (ForbiddenException).

404MessageBody

The request failed because the specified resource was not found (NotFoundException).

405MessageBody

The request failed because the method is not allowed for the specified resource (MethodNotAllowedException).

413MessageBody

The request failed because the payload for the body of the request is too large (RequestEntityTooLargeException).

429MessageBody

The request failed because too many requests were sent during a certain amount of time (TooManyRequestsException).

500MessageBody

The request failed due to an unknown internal server error, exception, or failure (InternalServerErrorException).

OPTIONS

Retrieves information about the communication requirements and options that are available for the In-App Template resource.

Path parameters
NameTypeRequiredDescription
template-nameStringTrue

The name of the message template. A template name must start with an alphanumeric character and can contain a maximum of 128 characters. The characters can be alphanumeric characters, underscores (_), or hyphens (-). Template names are case sensitive.

Responses
Status codeResponse modelDescription
200None

The request succeeded.

Schemas

Request bodies

{ "tags": { }, "TemplateDescription": "string", "Layout": enum, "Content": [ { "HeaderConfig": { "Header": "string", "TextColor": "string", "Alignment": enum }, "BackgroundColor": "string", "BodyConfig": { "Body": "string", "TextColor": "string", "Alignment": enum }, "ImageUrl": "string", "PrimaryBtn": { "DefaultConfig": { "Text": "string", "ButtonAction": enum, "Link": "string", "TextColor": "string", "BackgroundColor": "string", "BorderRadius": integer }, "Web": { "ButtonAction": enum, "Link": "string" }, "IOS": { "ButtonAction": enum, "Link": "string" }, "Android": { "ButtonAction": enum, "Link": "string" } }, "SecondaryBtn": { "DefaultConfig": { "Text": "string", "ButtonAction": enum, "Link": "string", "TextColor": "string", "BackgroundColor": "string", "BorderRadius": integer }, "Web": { "ButtonAction": enum, "Link": "string" }, "IOS": { "ButtonAction": enum, "Link": "string" }, "Android": { "ButtonAction": enum, "Link": "string" } } } ], "CustomConfig": { } }
{ "tags": { }, "TemplateDescription": "string", "Layout": enum, "Content": [ { "HeaderConfig": { "Header": "string", "TextColor": "string", "Alignment": enum }, "BackgroundColor": "string", "BodyConfig": { "Body": "string", "TextColor": "string", "Alignment": enum }, "ImageUrl": "string", "PrimaryBtn": { "DefaultConfig": { "Text": "string", "ButtonAction": enum, "Link": "string", "TextColor": "string", "BackgroundColor": "string", "BorderRadius": integer }, "Web": { "ButtonAction": enum, "Link": "string" }, "IOS": { "ButtonAction": enum, "Link": "string" }, "Android": { "ButtonAction": enum, "Link": "string" } }, "SecondaryBtn": { "DefaultConfig": { "Text": "string", "ButtonAction": enum, "Link": "string", "TextColor": "string", "BackgroundColor": "string", "BorderRadius": integer }, "Web": { "ButtonAction": enum, "Link": "string" }, "IOS": { "ButtonAction": enum, "Link": "string" }, "Android": { "ButtonAction": enum, "Link": "string" } } } ], "CustomConfig": { } }

Response bodies

{ "CreationDate": "string", "LastModifiedDate": "string", "TemplateType": enum, "TemplateName": "string", "TemplateDescription": "string", "Version": "string", "tags": { }, "Arn": "string", "Layout": enum, "Content": [ { "HeaderConfig": { "Header": "string", "TextColor": "string", "Alignment": enum }, "BackgroundColor": "string", "BodyConfig": { "Body": "string", "TextColor": "string", "Alignment": enum }, "ImageUrl": "string", "PrimaryBtn": { "DefaultConfig": { "Text": "string", "ButtonAction": enum, "Link": "string", "TextColor": "string", "BackgroundColor": "string", "BorderRadius": integer }, "Web": { "ButtonAction": enum, "Link": "string" }, "IOS": { "ButtonAction": enum, "Link": "string" }, "Android": { "ButtonAction": enum, "Link": "string" } }, "SecondaryBtn": { "DefaultConfig": { "Text": "string", "ButtonAction": enum, "Link": "string", "TextColor": "string", "BackgroundColor": "string", "BorderRadius": integer }, "Web": { "ButtonAction": enum, "Link": "string" }, "IOS": { "ButtonAction": enum, "Link": "string" }, "Android": { "ButtonAction": enum, "Link": "string" } } } ], "CustomConfig": { } }
{ "RequestID": "string", "Message": "string", "Arn": "string" }
{ "RequestID": "string", "Message": "string" }

Properties

DefaultButtonConfiguration

Information about the default behavior for a button that appears in an in-app message. You can optionally add button configurations that specifically apply to iOS, Android, or web browser users.

PropertyTypeRequiredDescription
BackgroundColor

string

False

The background color of a button, expressed as a string consisting of a hex color code (such as "#000000" for black).

BorderRadius

integer

False

The border radius of a button.

ButtonAction

string

Values: LINK | DEEP_LINK | CLOSE

True

The action that occurs when a recipient chooses a button in an in-app message. You can specify one of the following:

  • LINK – A link to a web destination.

  • DEEP_LINK – A link to a specific page in an application.

  • CLOSE – Dismisses the message.

string

False

The destination (such as a URL) for a button.

Text

string

True

The text that appears on a button in an in-app message.

TextColor

string

False

The color of the body text in a button, expressed as a string consisting of a hex color code (such as "#000000" for black).

InAppMessageBodyConfig

Configuration information related to the main body text of an in-app message.

PropertyTypeRequiredDescription
Alignment

string

Values: LEFT | CENTER | RIGHT

True

The text alignment of the main body text of the message.

Body

string

True

The main body text of the message.

TextColor

string

False

The color of the body text, expressed as a string consisting of a hex color code (such as "#000000" for black).

InAppMessageButton

Configuration information for a button that appears in an in-app message.

PropertyTypeRequiredDescription
Android

OverrideButtonConfiguration

False

An object that defines the default behavior for a button in in-app messages sent to Android.

DefaultConfig

DefaultButtonConfiguration

False

An object that defines the default behavior for a button in an in-app message.

IOS

OverrideButtonConfiguration

False

An object that defines the default behavior for a button in in-app messages sent to iOS devices.

Web

OverrideButtonConfiguration

False

An object that defines the default behavior for a button in in-app messages for web applications.

InAppMessageContent

Configuration information related to an in-app message.

PropertyTypeRequiredDescription
BackgroundColor

string

False

The background color for an in-app message banner, expressed as a string consisting of a hex color code (such as "#000000" for black).

BodyConfig

InAppMessageBodyConfig

False

An object that contains configuration information about the header or title text of the in-app message.

HeaderConfig

InAppMessageHeaderConfig

False

An object that contains configuration information about the header or title text of the in-app message.

ImageUrl

string

False

The URL of the image that appears on an in-app message banner.

PrimaryBtn

InAppMessageButton

False

An object that contains configuration information about the primary button in an in-app message.

SecondaryBtn

InAppMessageButton

False

An object that contains configuration information about the secondary button in an in-app message.

InAppMessageHeaderConfig

Configuration information related to the message header for an in-app message.

PropertyTypeRequiredDescription
Alignment

string

Values: LEFT | CENTER | RIGHT

True

The text alignment of the title of the message.

Header

string

True

The text that appears in the header or title of the message.

TextColor

string

False

The color of the body text, expressed as a string consisting of a hex color code (such as "#000000" for black).

InAppTemplateRequest

Specifies the content and settings for a message template that can be used to send in-app messages.

PropertyTypeRequiredDescription
Content

Array of type InAppMessageContent

False

An object that contains information about the content of an in-app message, including its title and body text, text colors, background colors, images, buttons, and behaviors.

CustomConfig

object

False

Information about the custom data that is included in an in-app messaging payload.

Layout

string

Values: BOTTOM_BANNER | TOP_BANNER | OVERLAYS | MOBILE_FEED | MIDDLE_BANNER | CAROUSEL

False

A string that determines the appearance of the in-app message. You can specify one of the following:

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

tags

object

False
Note

As of 22-05-2023 the tags attribute has been deprecated. After this date any value in the PUT UpdateInAppTemplate tags attribute is not processed and an error code is not returned. The POST CreateInAppTemplate tags attribute is processed. Use the Tags resource to add or modify tags.

(Deprecated) A string-to-string map of key-value pairs that defines the tags to associate with the message template. Each tag consists of a required tag key and an associated tag value.

TemplateDescription

string

False

An optional description of the in-app template.

InAppTemplateResponse

Provides information about the content and settings for an in-app message template.

PropertyTypeRequiredDescription
Arn

string

False

The Amazon Resource Name (ARN) of the message template.

Content

Array of type InAppMessageContent

False

An array that contains configurtion information about the message, including title and body text, text colors, background colors, image URLs, and button configurations.

CreationDate

string

True

The date, in ISO 8601 format, when the message template was created.

CustomConfig

object

False

An object that contains custom data (in the form of key-value pairs) that is included in the in-app messaging payload.

LastModifiedDate

string

True

The date, in ISO 8601 format, when the message template was last modified.

Layout

string

Values: BOTTOM_BANNER | TOP_BANNER | OVERLAYS | MOBILE_FEED | MIDDLE_BANNER | CAROUSEL

False

A string that determines the appearance of the in-app message. You can specify one of the following:

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

tags

object

False

A string-to-string map of key-value pairs that identifies the tags that are associated with the message template. Each tag consists of a required tag key and an associated tag value.

TemplateDescription

string

False

A description of the message template.

TemplateName

string

True

The name of the in-app message template.

TemplateType

string

Values: EMAIL | SMS | VOICE | PUSH | INAPP

True

The type of channel that the message template is designed for. For an in-app message template, this value is INAPP.

Version

string

False

The unique identifier, shown as an integer, of the active version of the message template, or the version of the template that you specified by using the version parameter in your request.

MessageBody

Provides information about an API request or response.

PropertyTypeRequiredDescription
Message

string

False

The message that's returned from the API.

RequestID

string

False

The unique identifier for the request or response.

OverrideButtonConfiguration

Configuration information related to the configuration of a button with settings that are specific to a certain device type.

PropertyTypeRequiredDescription
ButtonAction

string

Values: LINK | DEEP_LINK | CLOSE

False

The action that occurs when a recipient chooses a button in an in-app message. You can specify one of the following:

  • LINK – A link to a web destination.

  • DEEP_LINK – A link to a specific page in an application.

  • CLOSE – Dismisses the message.

string

False

The destination (such as a URL) for a button.

TemplateCreateMessageBody

PropertyTypeRequiredDescription
Arn

string

False
Message

string

False
RequestID

string

False

See also

For more information about using this API in one of the language-specific AWS SDKs and references, see the following:

GetInAppTemplate

CreateInAppTemplate

UpdateInAppTemplate

DeleteInAppTemplate