Amazon Connect Customer Profiles

Retrieves recommendations for a profile in a specific domain. The profile is identified using a search key, which consists of a KeyName and a KeyValues list. The KeyName can be a predefined key (for example, _profileId, _phone, _email) or a custom-defined key.

The search key must match exactly one profile. If no profile matches the search key, the operation returns a ResourceNotFoundException. If more than one profile matches the search key, the operation returns a BadRequestException. You can use the SearchProfiles API to review the matching profiles.

See also: AWS API Documentation

Request Syntax

client.search_recommendations(
    DomainName='string',
    KeyName='string',
    KeyValues=[
        'string',
    ],
    Recommender={
        'Name': 'string',
        'Filters': [
            {
                'Name': 'string',
                'Values': {
                    'string': 'string'
                }
            },
        ],
        'PromotionalFilters': [
            {
                'Name': 'string',
                'Values': {
                    'string': 'string'
                },
                'PromotionName': 'string',
                'PercentPromotedItems': 123
            },
        ]
    },
    CandidateIds=[
        'string',
    ],
    Context={
        'string': 'string'
    },
    Diversity={
        'Enabled': True|False,
        'Values': {
            'string': 123
        }
    },
    Metadata={
        'Columns': [
            'string',
        ]
    },
    MaxRecommendations=123
)

type DomainName:

string

param DomainName:

[REQUIRED]

The unique name of the domain.

type KeyName:

string

param KeyName:

[REQUIRED]

A searchable identifier of a customer profile. You can use a predefined key, such as _profileId, _phone, or _email, or a custom-defined key.

type KeyValues:

list

param KeyValues:

[REQUIRED]

A list of key values. Provide one value for each field of the search key.

• (string) --

type Recommender:

dict

param Recommender:

[REQUIRED]

The recommender used to generate the recommendations.

• Name (string) -- [REQUIRED]

  The unique name of the recommender.

• Filters (list) --

  A list of filters to apply to the returned recommendations. Filters define criteria for including or excluding items from the recommendation results.

  • (dict) --

    A filter that specifies criteria for including or excluding items from recommendations.

    • Name (string) --

      The name of the recommender filter to apply.

    • Values (dict) --

      The values to use when filtering recommendations. For each placeholder parameter in your filter expression, provide the parameter name (in matching case) as a key and the filter value(s) as the corresponding value. Separate multiple values for one parameter with a comma.

      • (string) --

        • (string) --

• PromotionalFilters (list) --

  A list of promotional filters to apply to the recommendations. Promotional filters allow you to promote specific items within a configurable subset of recommendation results.

  • (dict) --

    Contains information on a promotion. A promotion defines additional business rules that apply to a configurable subset of recommended items.

    • Name (string) --

      The name of the recommender filter to use for the promotion.

    • Values (dict) --

      The values to use when promoting items. For each placeholder parameter in your promotion's filter expression, provide the parameter name (in matching case) as a key and the filter value(s) as the corresponding value. Separate multiple values for one parameter with a comma.

      • (string) --

        • (string) --

    • PromotionName (string) --

      The name of the promotion.

    • PercentPromotedItems (integer) --

      The percentage of recommended items to apply the promotion to.

type CandidateIds:

list

param CandidateIds:

A list of item IDs to rank for the user. Use this when you want to re-rank a specific set of items rather than getting recommendations from the full item catalog. Required for personalized-ranking use cases.

• (string) --

type Context:

dict

param Context:

The contextual metadata used to provide dynamic runtime information to tailor recommendations.

• (string) --

  • (string) --

type Diversity:

dict

param Diversity:

Runtime diversity configuration for this request. Enables diversity-aware recommendations and optionally supplies values for placeholder-based diversity caps configured on the recommender.

• Enabled (boolean) -- [REQUIRED]

  Whether diversity-aware recommendations are enabled for this request.

• Values (dict) --

  An optional map of placeholder name to integer cap value used to resolve $name placeholders defined in the recommender's DiversityConfig at inference time. Up to 2 entries are supported.

  • (string) --

    • (integer) --

type Metadata:

dict

param Metadata:

Configuration for metadata to include in recommendation responses.

• Columns (list) --

  A list of metadata column names from your Items dataset to include in the recommendation response.

  • (string) --

type MaxRecommendations:

integer

param MaxRecommendations:

The maximum number of recommendations to return. The default value is 5.

rtype:

dict

returns:

Response Syntax

{
    'ProfileId': 'string',
    'Recommendations': [
        {
            'CatalogItem': {
                'Id': 'string',
                'Name': 'string',
                'Code': 'string',
                'Type': 'string',
                'Category': 'string',
                'Description': 'string',
                'AdditionalInformation': 'string',
                'ImageLink': 'string',
                'Link': 'string',
                'CreatedAt': datetime(2015, 1, 1),
                'UpdatedAt': datetime(2015, 1, 1),
                'Price': 'string',
                'Attributes': {
                    'string': 'string'
                }
            },
            'Score': 123.0
        },
    ]
}

Response Structure

• (dict) --

  • ProfileId (string) --

    The unique identifier of the profile for which to retrieve recommendations.

  • Recommendations (list) --

    List of recommendations generated by the recommender.

    • (dict) --

      Represents a single recommendation generated by the recommender system.

      • CatalogItem (dict) --

        The catalog item being recommended, including its complete details and attributes.

        • Id (string) --

          The unique identifier for the catalog item.

        • Name (string) --

          The display name of the catalog item.

        • Code (string) --

          The product code or SKU of the catalog item.

        • Type (string) --

          The type classification of the catalog item.

        • Category (string) --

          The category to which the catalog item belongs.

        • Description (string) --

          A detailed description of the catalog item.

        • AdditionalInformation (string) --

          Supplementary information about the catalog item beyond the basic description.

        • ImageLink (string) --

          The URL link to the item's image.

        • Link (string) --

          The URL link to the item's detailed page or external resource.

        • CreatedAt (datetime) --

          The timestamp when the catalog item was created.

        • UpdatedAt (datetime) --

          The timestamp when the catalog item was last updated.

        • Price (string) --

          The price of the catalog item.

        • Attributes (dict) --

          Additional attributes or properties associated with the catalog item stored as key-value pairs.

          • (string) --

            • (string) --

      • Score (float) --

        Recommendation Score between 0 and 1.