QConnect / Client / get_recommendations

get_recommendations¶

QConnect.Client.get_recommendations(**kwargs)¶

Warning

This API will be discontinued starting June 1, 2024. To receive generative responses after March 1, 2024, you will need to create a new Assistant in the Amazon Connect console and integrate the Amazon Q in Connect JavaScript library (amazon-q-connectjs) into your applications.

Retrieves recommendations for the specified session. To avoid retrieving the same recommendations in subsequent calls, use NotifyRecommendationsReceived. This API supports long-polling behavior with the waitTimeSeconds parameter. Short poll is the default behavior and only returns recommendations already available. To perform a manual query against an assistant, use QueryAssistant.

Danger

This operation is deprecated and may not function as expected. This operation should not be used going forward and is only kept for the purpose of backwards compatiblity.

Request Syntax

response = client.get_recommendations(
    assistantId='string',
    sessionId='string',
    maxResults=123,
    waitTimeSeconds=123,
    nextChunkToken='string'
)

Parameters:

assistantId (string) –
[REQUIRED]

The identifier of the Amazon Q in Connect assistant. Can be either the ID or the ARN. URLs cannot contain the ARN.
sessionId (string) –
[REQUIRED]

The identifier of the session. Can be either the ID or the ARN. URLs cannot contain the ARN.
maxResults (integer) – The maximum number of results to return per page.
waitTimeSeconds (integer) – The duration (in seconds) for which the call waits for a recommendation to be made available before returning. If a recommendation is available, the call returns sooner than WaitTimeSeconds. If no messages are available and the wait time expires, the call returns successfully with an empty list.
nextChunkToken (string) – The token for the next set of chunks. Use the value returned in the previous response in the next request to retrieve the next set of chunks.

Return type:

dict

Returns:

Response Syntax

{
    'recommendations': [
        {
            'recommendationId': 'string',
            'document': {
                'contentReference': {
                    'knowledgeBaseArn': 'string',
                    'knowledgeBaseId': 'string',
                    'contentArn': 'string',
                    'contentId': 'string',
                    'sourceURL': 'string',
                    'referenceType': 'WEB_CRAWLER'|'KNOWLEDGE_BASE'
                },
                'title': {
                    'text': 'string',
                    'highlights': [
                        {
                            'beginOffsetInclusive': 123,
                            'endOffsetExclusive': 123
                        },
                    ]
                },
                'excerpt': {
                    'text': 'string',
                    'highlights': [
                        {
                            'beginOffsetInclusive': 123,
                            'endOffsetExclusive': 123
                        },
                    ]
                }
            },
            'relevanceScore': 123.0,
            'relevanceLevel': 'HIGH'|'MEDIUM'|'LOW',
            'type': 'KNOWLEDGE_CONTENT'|'GENERATIVE_RESPONSE'|'GENERATIVE_ANSWER'|'DETECTED_INTENT'|'GENERATIVE_ANSWER_CHUNK'|'BLOCKED_GENERATIVE_ANSWER_CHUNK'|'INTENT_ANSWER_CHUNK'|'BLOCKED_INTENT_ANSWER_CHUNK'|'EMAIL_RESPONSE_CHUNK'|'EMAIL_OVERVIEW_CHUNK'|'EMAIL_GENERATIVE_ANSWER_CHUNK',
            'data': {
                'reference': {
                    'contentReference': {
                        'knowledgeBaseArn': 'string',
                        'knowledgeBaseId': 'string',
                        'contentArn': 'string',
                        'contentId': 'string',
                        'sourceURL': 'string',
                        'referenceType': 'WEB_CRAWLER'|'KNOWLEDGE_BASE'
                    },
                    'generativeReference': {
                        'modelId': 'string',
                        'generationId': 'string'
                    }
                },
                'details': {
                    'contentData': {
                        'textData': {
                            'title': {
                                'text': 'string',
                                'highlights': [
                                    {
                                        'beginOffsetInclusive': 123,
                                        'endOffsetExclusive': 123
                                    },
                                ]
                            },
                            'excerpt': {
                                'text': 'string',
                                'highlights': [
                                    {
                                        'beginOffsetInclusive': 123,
                                        'endOffsetExclusive': 123
                                    },
                                ]
                            }
                        },
                        'rankingData': {
                            'relevanceScore': 123.0,
                            'relevanceLevel': 'HIGH'|'MEDIUM'|'LOW'
                        }
                    },
                    'generativeData': {
                        'completion': 'string',
                        'references': [
                            {'... recursive ...'},
                        ],
                        'rankingData': {
                            'relevanceScore': 123.0,
                            'relevanceLevel': 'HIGH'|'MEDIUM'|'LOW'
                        }
                    },
                    'intentDetectedData': {
                        'intent': 'string',
                        'intentId': 'string'
                    },
                    'sourceContentData': {
                        'id': 'string',
                        'type': 'KNOWLEDGE_CONTENT',
                        'textData': {
                            'title': {
                                'text': 'string',
                                'highlights': [
                                    {
                                        'beginOffsetInclusive': 123,
                                        'endOffsetExclusive': 123
                                    },
                                ]
                            },
                            'excerpt': {
                                'text': 'string',
                                'highlights': [
                                    {
                                        'beginOffsetInclusive': 123,
                                        'endOffsetExclusive': 123
                                    },
                                ]
                            }
                        },
                        'rankingData': {
                            'relevanceScore': 123.0,
                            'relevanceLevel': 'HIGH'|'MEDIUM'|'LOW'
                        },
                        'citationSpan': {
                            'beginOffsetInclusive': 123,
                            'endOffsetExclusive': 123
                        }
                    },
                    'generativeChunkData': {
                        'completion': 'string',
                        'references': [
                            {'... recursive ...'},
                        ],
                        'nextChunkToken': 'string'
                    },
                    'emailResponseChunkData': {
                        'completion': 'string',
                        'nextChunkToken': 'string'
                    },
                    'emailOverviewChunkData': {
                        'completion': 'string',
                        'nextChunkToken': 'string'
                    },
                    'emailGenerativeAnswerChunkData': {
                        'completion': 'string',
                        'references': [
                            {'... recursive ...'},
                        ],
                        'nextChunkToken': 'string'
                    }
                }
            }
        },
    ],
    'triggers': [
        {
            'id': 'string',
            'type': 'QUERY'|'GENERATIVE',
            'source': 'ISSUE_DETECTION'|'RULE_EVALUATION'|'OTHER',
            'data': {
                'query': {
                    'text': 'string'
                }
            },
            'recommendationIds': [
                'string',
            ]
        },
    ]
}

Response Structure

(dict) –
- recommendations (list) –
  
  The recommendations.
  - (dict) –
    
    Information about the recommendation.
    - recommendationId (string) –
      
      The identifier of the recommendation.
    - document (dict) –
      
      The recommended document.
      - contentReference (dict) –
        
        A reference to the content resource.
        
        knowledgeBaseArn (string) –
        
        The Amazon Resource Name (ARN) of the knowledge base.
        
        knowledgeBaseId (string) –
        
        The identifier of the knowledge base. This should not be a QUICK_RESPONSES type knowledge base.
        
        contentArn (string) –
        
        The Amazon Resource Name (ARN) of the content.
        
        contentId (string) –
        
        The identifier of the content.
        
        sourceURL (string) –
        
        The web URL of the source content.
        
        referenceType (string) –
        
        The type of reference content.
      - title (dict) –
        
        The title of the document.
        
        text (string) –
        
        Text in the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
      - excerpt (dict) –
        
        The excerpt from the document.
        
        text (string) –
        
        Text in the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
    - relevanceScore (float) –
      
      The relevance score of the recommendation.
    - relevanceLevel (string) –
      
      The relevance level of the recommendation.
    - type (string) –
      
      The type of recommendation.
    - data (dict) –
      
      Summary of the recommended content.
      - reference (dict) –
        
        Reference information about the content.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: contentReference, generativeReference. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        contentReference (dict) –
        
        Reference information about the content.
        
        knowledgeBaseArn (string) –
        
        The Amazon Resource Name (ARN) of the knowledge base.
        
        knowledgeBaseId (string) –
        
        The identifier of the knowledge base. This should not be a QUICK_RESPONSES type knowledge base.
        
        contentArn (string) –
        
        The Amazon Resource Name (ARN) of the content.
        
        contentId (string) –
        
        The identifier of the content.
        
        sourceURL (string) –
        
        The web URL of the source content.
        
        referenceType (string) –
        
        The type of reference content.
        
        generativeReference (dict) –
        
        Reference information about the generative content.
        
        modelId (string) –
        
        The identifier of the LLM model.
        
        generationId (string) –
        
        The identifier of the LLM model.
      - details (dict) –
        
        Details about the data.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: contentData, generativeData, intentDetectedData, sourceContentData, generativeChunkData, emailResponseChunkData, emailOverviewChunkData, emailGenerativeAnswerChunkData. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        contentData (dict) –
        
        Details about the content data.
        
        textData (dict) –
        
        Details about the content text data.
        
        title (dict) –
        
        The text of the document.
        
        text (string) –
        
        Text in the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
        
        excerpt (dict) –
        
        The text of the document.
        
        text (string) –
        
        Text in the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
        
        rankingData (dict) –
        
        Details about the content ranking data.
        
        relevanceScore (float) –
        
        The relevance level of the recommendation.
        
        relevanceLevel (string) –
        
        The relevance score of the content.
        
        generativeData (dict) –
        
        Details about the generative data.
        
        completion (string) –
        
        The LLM response.
        
        references (list) –
        
        The references used to generative the LLM response.
        
        (dict) –
        
        Summary of the data.
        
        rankingData (dict) –
        
        Details about the generative content ranking data.
        
        relevanceScore (float) –
        
        The relevance level of the recommendation.
        
        relevanceLevel (string) –
        
        The relevance score of the content.
        
        intentDetectedData (dict) –
        
        Details about the intent data.
        
        intent (string) –
        
        The detected intent.
        
        intentId (string) –
        
        The identifier of the detected intent.
        
        sourceContentData (dict) –
        
        Details about the content data.
        
        id (string) –
        
        The identifier of the source content.
        
        type (string) –
        
        The type of the source content.
        
        textData (dict) –
        
        Details about the source content text data.
        
        title (dict) –
        
        The text of the document.
        
        text (string) –
        
        Text in the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
        
        excerpt (dict) –
        
        The text of the document.
        
        text (string) –
        
        Text in the document.
        
        highlights (list) –
        
        Highlights in the document text.
        
        (dict) –
        
        Offset specification to describe highlighting of document excerpts for rendering search results and recommendations.
        
        beginOffsetInclusive (integer) –
        
        The offset for the start of the highlight.
        
        endOffsetExclusive (integer) –
        
        The offset for the end of the highlight.
        
        rankingData (dict) –
        
        Details about the source content ranking data.
        
        relevanceScore (float) –
        
        The relevance level of the recommendation.
        
        relevanceLevel (string) –
        
        The relevance score of the content.
        
        citationSpan (dict) –
        
        Contains information about where the text with a citation begins and ends in the generated output.
        
        beginOffsetInclusive (integer) –
        
        Where the text with a citation starts in the generated output.
        
        endOffsetExclusive (integer) –
        
        Where the text with a citation ends in the generated output.
        
        generativeChunkData (dict) –
        
        Details about the generative chunk data.
        
        completion (string) –
        
        A chunk of the LLM response.
        
        references (list) –
        
        The references used to generate the LLM response.
        
        (dict) –
        
        Summary of the data.
        
        nextChunkToken (string) –
        
        The token for the next set of chunks. Use the value returned in the previous response in the next request to retrieve the next set of chunks.
        
        emailResponseChunkData (dict) –
        
        Streaming chunk data for email response generation containing partial response content.
        
        completion (string) –
        
        The partial or complete professional email response text with appropriate greetings and closings.
        
        nextChunkToken (string) –
        
        Token for retrieving the next chunk of streaming response data, if available.
        
        emailOverviewChunkData (dict) –
        
        Streaming chunk data for email overview containing partial overview content.
        
        completion (string) –
        
        The partial or complete overview text content in structured HTML format with customer issues, resolutions, and next steps.
        
        nextChunkToken (string) –
        
        Token for retrieving the next chunk of streaming overview data, if available.
        
        emailGenerativeAnswerChunkData (dict) –
        
        Streaming chunk data for email generative answers containing partial knowledge-based response content.
        
        completion (string) –
        
        The partial or complete text content of the generative answer response.
        
        references (list) –
        
        Source references and citations from knowledge base articles used to generate the answer.
        
        (dict) –
        
        Summary of the data.
        
        nextChunkToken (string) –
        
        Token for retrieving the next chunk of streaming response data, if available.
- triggers (list) –
  
  The triggers corresponding to recommendations.
  - (dict) –
    
    A recommendation trigger provides context on the event that produced the referenced recommendations. Recommendations are only referenced in recommendationIds by a single RecommendationTrigger.
    - id (string) –
      
      The identifier of the recommendation trigger.
    - type (string) –
      
      The type of recommendation trigger.
    - source (string) –
      
      The source of the recommendation trigger.
      - ISSUE_DETECTION: The corresponding recommendations were triggered by a Contact Lens issue.
      - RULE_EVALUATION: The corresponding recommendations were triggered by a Contact Lens rule.
    - data (dict) –
      
      A union type containing information related to the trigger.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: query. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - query (dict) –
        
        Data associated with the QUERY RecommendationTriggerType.
        
        text (string) –
        
        The text associated with the recommendation trigger.
    - recommendationIds (list) –
      
      The identifiers of the recommendations.
      - (string) –

Exceptions

QConnect.Client.exceptions.ValidationException
QConnect.Client.exceptions.AccessDeniedException
QConnect.Client.exceptions.ResourceNotFoundException

get_recommendations¶

Warning

Danger

Request Syntax

Response Syntax

Response Structure

Note

Note

Note

Exceptions