URI HTTP methods Schemas Properties See also

Recommender Models

A recommender model is a type of machine learning (ML) model that generates predictions and recommendations by finding patterns in data. Based on the data that it receives, the model can dynamically predict and deliver a combination of personalized recommendations to add to messages. In Amazon Pinpoint, you can connect to these models, and send personalized recommendations to message recipients based on each recipient’s attributes and behavior.

To use a recommender model with Amazon Pinpoint, you start by creating an Amazon Personalize solution and deploying that solution as an Amazon Personalize campaign. Then you create a configuration for the recommender model in Amazon Pinpoint. In the configuration, you specify settings that determine where and how to retrieve and process data from the Amazon Personalize campaign. This includes: how to correlate user or endpoint identifiers in Amazon Pinpoint with user identifiers in the model; the number of recommended items to retrieve for each user or endpoint; and, where to store and how to process recommended items.

After you create a configuration, you can add recommendations from the model to messages that you send from campaigns and journeys. To do this, create an email, push notification, or SMS message template. In the template, specify the recommender model to use and add message variables that refer to recommended attributes for the model. A recommended attribute is a dynamic attribute that stores recommendation data. When you send a message that uses the template, Amazon Pinpoint retrieves the latest data from the recommender model, replaces each message variable with the recommendation data for each recipient, and then sends the message.

The Recommender Models resource represents the repository of recommender model configurations that are associated with your Amazon Pinpoint account. This resource is available in the following AWS Regions: US East (N. Virginia); US West (Oregon); Asia Pacific (Mumbai); Asia Pacific (Sydney); and, Europe (Ireland).

You can use this resource to create a new Amazon Pinpoint configuration for a recommender model or to retrieve information about all the existing configurations for your account. To update or delete a configuration for a recommender model, use the Recommender Model resource.

URI

/v1/recommenders

HTTP methods

GET

Operation ID: GetRecommenderConfigurations

Retrieves information about all the recommender model configurations that are associated with your Amazon Pinpoint account.

Header parameters
Name	Type	Required	Description
`accept`	String	False	Indicates which content types, expressed as MIME types, the client understands.

Query parameters
Name	Type	Required	Description
`token`	String	False	The `NextToken` string that specifies which page of results to return in a paginated response.
`page-size`	String	False	The maximum number of items to include in each page of a paginated response. This parameter is not supported for application, campaign, and journey metrics.

Responses
Status code	Response model	Description
`200`	`ListRecommenderConfigurationsResponse`	The request succeeded.
`400`	`MessageBody`	The request contains a syntax error (BadRequestException).
`403`	`MessageBody`	The request was denied because access to the specified resource is forbidden (ForbiddenException).
`404`	`MessageBody`	The request failed because the specified resource was not found (NotFoundException).
`405`	`MessageBody`	The request failed because the method is not allowed for the specified resource (MethodNotAllowedException).
`413`	`MessageBody`	The request failed because the payload for the body of the request is too large (RequestEntityTooLargeException).
`429`	`MessageBody`	The request failed because too many requests were sent during a certain amount of time (TooManyRequestsException).
`500`	`MessageBody`	The request failed due to an unknown internal server error, exception, or failure (InternalServerErrorException).

POST

Operation ID: CreateRecommenderConfiguration

Creates an Amazon Pinpoint configuration for a recommender model.

Header parameters
Name	Type	Required	Description
`accept`	String	False	Indicates which content types, expressed as MIME types, the client understands.

Responses
Status code	Response model	Description
`201`	`RecommenderConfigurationResponse`	The request succeeded and the specified resource was created.
`400`	`MessageBody`	The request contains a syntax error (BadRequestException).
`403`	`MessageBody`	The request was denied because access to the specified resource is forbidden (ForbiddenException).
`404`	`MessageBody`	The request failed because the specified resource was not found (NotFoundException).
`405`	`MessageBody`	The request failed because the method is not allowed for the specified resource (MethodNotAllowedException).
`413`	`MessageBody`	The request failed because the payload for the body of the request is too large (RequestEntityTooLargeException).
`429`	`MessageBody`	The request failed because too many requests were sent during a certain amount of time (TooManyRequestsException).
`500`	`MessageBody`	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 Recommender Models resource.

Responses
Status code	Response model	Description
`200`	None	The request succeeded.

Schemas

Request bodies


{
  "Name": "string",
  "Description": "string",
  "RecommendationProviderUri": "string",
  "RecommendationTransformerUri": "string",
  "RecommendationProviderRoleArn": "string",
  "RecommendationsPerMessage": integer,
  "RecommendationProviderIdType": "string",
  "RecommendationsDisplayName": "string",
  "Attributes": {
  }
}

Response bodies


{
  "Item": [
    {
      "Id": "string",
      "CreationDate": "string",
      "LastModifiedDate": "string",
      "Name": "string",
      "Description": "string",
      "RecommendationProviderUri": "string",
      "RecommendationTransformerUri": "string",
      "RecommendationProviderRoleArn": "string",
      "RecommendationsPerMessage": integer,
      "RecommendationProviderIdType": "string",
      "RecommendationsDisplayName": "string",
      "Attributes": {
      }
    }
  ],
  "NextToken": "string"
}


{
  "Id": "string",
  "CreationDate": "string",
  "LastModifiedDate": "string",
  "Name": "string",
  "Description": "string",
  "RecommendationProviderUri": "string",
  "RecommendationTransformerUri": "string",
  "RecommendationProviderRoleArn": "string",
  "RecommendationsPerMessage": integer,
  "RecommendationProviderIdType": "string",
  "RecommendationsDisplayName": "string",
  "Attributes": {
  }
}


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

Properties

CreateRecommenderConfiguration

Specifies Amazon Pinpoint configuration settings for retrieving and processing recommendation data from a recommender model.

Property	Type	Required	Description
`Attributes`	object	False	A map of key-value pairs that defines 1-10 custom endpoint or user attributes, depending on the value for the `RecommendationProviderIdType` property. Each of these attributes temporarily stores a recommended item that's retrieved from the recommender model and sent to an AWS Lambda function for additional processing. Each attribute can be used as a message variable in a message template. In the map, the key is the name of a custom attribute and the value is a custom display name for that attribute. The display name appears in the Attribute finder of the template editor on the Amazon Pinpoint console. The following restrictions apply to these names: An attribute name must start with a letter or number and it can contain up to 50 characters. The characters can be letters, numbers, underscores (_), or hyphens (-). Attribute names are case sensitive and must be unique. An attribute display name must start with a letter or number and it can contain up to 25 characters. The characters can be letters, numbers, spaces, underscores (_), or hyphens (-). This object is required if the configuration invokes an AWS Lambda function (`RecommendationTransformerUri`) to process recommendation data. Otherwise, don't include this object in your request.
`Description`	string	False	A custom description of the configuration for the recommender model. The description can contain up to 128 characters. The characters can be letters, numbers, spaces, or the following symbols: _ ; () , ‐.
`Name`	string	False	A custom name of the configuration for the recommender model. The name must start with a letter or number and it can contain up to 128 characters. The characters can be letters, numbers, spaces, underscores (_), or hyphens (-).
`RecommendationProviderIdType`	string	False	The type of Amazon Pinpoint ID to associate with unique user IDs in the recommender model. This value enables the model to use attribute and event data that’s specific to a particular endpoint or user in an Amazon Pinpoint application. Valid values are: `PINPOINT_ENDPOINT_ID` – Associate each user in the model with a particular endpoint in Amazon Pinpoint. The data is correlated based on endpoint IDs in Amazon Pinpoint. This is the default value. `PINPOINT_USER_ID` – Associate each user in the model with a particular user and endpoint in Amazon Pinpoint. The data is correlated based on user IDs in Amazon Pinpoint. If you specify this value, an endpoint definition in Amazon Pinpoint has to specify both a user ID (`UserId`) and an endpoint ID. Otherwise, messages won’t be sent to the user's endpoint.
`RecommendationProviderRoleArn`	string	True	The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that authorizes Amazon Pinpoint to retrieve recommendation data from the recommender model.
`RecommendationProviderUri`	string	True	The Amazon Resource Name (ARN) of the recommender model to retrieve recommendation data from. This value must match the ARN of an Amazon Personalize campaign.
`RecommendationsDisplayName`	string	False	A custom display name for the standard endpoint or user attribute (`RecommendationItems`) that temporarily stores recommended items for each endpoint or user, depending on the value for the `RecommendationProviderIdType` property. This value is required if the configuration doesn't invoke an AWS Lambda function (`RecommendationTransformerUri`) to perform additional processing of recommendation data. This name appears in the Attribute finder of the template editor on the Amazon Pinpoint console. The name can contain up to 25 characters. The characters can be letters, numbers, spaces, underscores (_), or hyphens (-). These restrictions don't apply to attribute values.
`RecommendationsPerMessage`	integer	False	The number of recommended items to retrieve from the model for each endpoint or user, depending on the value for the `RecommendationProviderIdType` property. This number determines how many recommended items are available for use in message variables. The minimum value is 1. The maximum value is 5. The default value is 5. To use multiple recommended items and custom attributes with message variables, you have to use an AWS Lambda function (`RecommendationTransformerUri`) to perform additional processing of recommendation data.
`RecommendationTransformerUri`	string	False	The name or Amazon Resource Name (ARN) of the AWS Lambda function to invoke for additional processing of recommendation data that's retrieved from the recommender model.

ListRecommenderConfigurationsResponse

Provides information about all the recommender model configurations that are associated with your Amazon Pinpoint account.

Property	Type	Required	Description
`Item`	Array of type RecommenderConfigurationResponse	True	An array of responses, one for each recommender model configuration that's associated with your Amazon Pinpoint account.
`NextToken`	string	False	The string to use in a subsequent request to get the next page of results in a paginated response. This value is null if there are no additional pages.

MessageBody

Provides information about an API request or response.

Property	Type	Required	Description
`Message`	string	False	The message that's returned from the API.
`RequestID`	string	False	The unique identifier for the request or response.

RecommenderConfigurationResponse

Provides information about Amazon Pinpoint configuration settings for retrieving and processing data from a recommender model.

Property	Type	Required	Description
`Attributes`	object	False	A map that defines 1-10 custom endpoint or user attributes, depending on the value for the `RecommendationProviderIdType` property. Each of these attributes temporarily stores a recommended item that's retrieved from the recommender model and sent to an AWS Lambda function for additional processing. Each attribute can be used as a message variable in a message template. This value is null if the configuration doesn't invoke an AWS Lambda function (`RecommendationTransformerUri`) to perform additional processing of recommendation data.
`CreationDate`	string	True	The date, in extended ISO 8601 format, when the configuration was created for the recommender model.
`Description`	string	False	The custom description of the configuration for the recommender model.
`Id`	string	True	The unique identifier for the recommender model configuration.
`LastModifiedDate`	string	True	The date, in extended ISO 8601 format, when the configuration for the recommender model was last modified.
`Name`	string	False	The custom name of the configuration for the recommender model.
`RecommendationProviderIdType`	string	False	The type of Amazon Pinpoint ID that's associated with unique user IDs in the recommender model. This value enables the model to use attribute and event data that’s specific to a particular endpoint or user in an Amazon Pinpoint application. Possible values are: `PINPOINT_ENDPOINT_ID` – Each user in the model is associated with a particular endpoint in Amazon Pinpoint. The data is correlated based on endpoint IDs in Amazon Pinpoint. This is the default value. `PINPOINT_USER_ID` – Each user in the model is associated with a particular user and endpoint in Amazon Pinpoint. The data is correlated based on user IDs in Amazon Pinpoint. If this value is specified, an endpoint definition in Amazon Pinpoint has to specify both a user ID (`UserId`) and an endpoint ID. Otherwise, messages won’t be sent to the user's endpoint.
`RecommendationProviderRoleArn`	string	True	The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that authorizes Amazon Pinpoint to retrieve recommendation data from the recommender model.
`RecommendationProviderUri`	string	True	The Amazon Resource Name (ARN) of the recommender model that Amazon Pinpoint retrieves the recommendation data from. This value is the ARN of an Amazon Personalize campaign.
`RecommendationsDisplayName`	string	False	The custom display name for the standard endpoint or user attribute (`RecommendationItems`) that temporarily stores recommended items for each endpoint or user, depending on the value for the `RecommendationProviderIdType` property. This name appears in the Attribute finder of the template editor on the Amazon Pinpoint console. This value is null if the configuration doesn't invoke an AWS Lambda function (`RecommendationTransformerUri`) to perform additional processing of recommendation data.
`RecommendationsPerMessage`	integer	False	The number of recommended items that are retrieved from the model for each endpoint or user, depending on the value for the `RecommendationProviderIdType` property. This number determines how many recommended items are available for use in message variables.
`RecommendationTransformerUri`	string	False	The name or Amazon Resource Name (ARN) of the AWS Lambda function that Amazon Pinpoint invokes to perform additional processing of recommendation data that it retrieves from the recommender model.