QBusiness / Client / chat_sync

chat_sync#

QBusiness.Client.chat_sync(**kwargs)#

Starts or continues a non-streaming Amazon Q Business conversation.

Request Syntax

response = client.chat_sync(
    applicationId='string',
    userId='string',
    userGroups=[
        'string',
    ],
    userMessage='string',
    attachments=[
        {
            'name': 'string',
            'data': b'bytes'
        },
    ],
    actionExecution={
        'pluginId': 'string',
        'payload': {
            'string': {
                'value': {...}|[...]|123|123.4|'string'|True|None
            }
        },
        'payloadFieldNameSeparator': 'string'
    },
    authChallengeResponse={
        'responseMap': {
            'string': 'string'
        }
    },
    conversationId='string',
    parentMessageId='string',
    attributeFilter={
        'andAllFilters': [
            {'... recursive ...'},
        ],
        'orAllFilters': [
            {'... recursive ...'},
        ],
        'notFilter': {'... recursive ...'},
        'equalsTo': {
            'name': 'string',
            'value': {
                'stringValue': 'string',
                'stringListValue': [
                    'string',
                ],
                'longValue': 123,
                'dateValue': datetime(2015, 1, 1)
            }
        },
        'containsAll': {
            'name': 'string',
            'value': {
                'stringValue': 'string',
                'stringListValue': [
                    'string',
                ],
                'longValue': 123,
                'dateValue': datetime(2015, 1, 1)
            }
        },
        'containsAny': {
            'name': 'string',
            'value': {
                'stringValue': 'string',
                'stringListValue': [
                    'string',
                ],
                'longValue': 123,
                'dateValue': datetime(2015, 1, 1)
            }
        },
        'greaterThan': {
            'name': 'string',
            'value': {
                'stringValue': 'string',
                'stringListValue': [
                    'string',
                ],
                'longValue': 123,
                'dateValue': datetime(2015, 1, 1)
            }
        },
        'greaterThanOrEquals': {
            'name': 'string',
            'value': {
                'stringValue': 'string',
                'stringListValue': [
                    'string',
                ],
                'longValue': 123,
                'dateValue': datetime(2015, 1, 1)
            }
        },
        'lessThan': {
            'name': 'string',
            'value': {
                'stringValue': 'string',
                'stringListValue': [
                    'string',
                ],
                'longValue': 123,
                'dateValue': datetime(2015, 1, 1)
            }
        },
        'lessThanOrEquals': {
            'name': 'string',
            'value': {
                'stringValue': 'string',
                'stringListValue': [
                    'string',
                ],
                'longValue': 123,
                'dateValue': datetime(2015, 1, 1)
            }
        }
    },
    chatMode='RETRIEVAL_MODE'|'CREATOR_MODE'|'PLUGIN_MODE',
    chatModeConfiguration={
        'pluginConfiguration': {
            'pluginId': 'string'
        }
    },
    clientToken='string'
)

Parameters:

applicationId (string) –
[REQUIRED]

The identifier of the Amazon Q Business application linked to the Amazon Q Business conversation.
userId (string) – The identifier of the user attached to the chat input.
userGroups (list) –
The group names that a user associated with the chat input belongs to.
- (string) –
userMessage (string) – A end user message in a conversation.
attachments (list) –
A list of files uploaded directly during chat. You can upload a maximum of 5 files of upto 10 MB each.
- (dict) –
  
  A file directly uploaded into a web experience chat.
  - name (string) – [REQUIRED]
    
    The name of the file.
  - data (bytes) – [REQUIRED]
    
    The data contained within the uploaded file.
actionExecution (dict) –
A request from an end user to perform an Amazon Q Business plugin action.
- pluginId (string) – [REQUIRED]
  
  The identifier of the plugin the action is attached to.
- payload (dict) – [REQUIRED]
  
  A mapping of field names to the field values in input that an end user provides to Amazon Q Business requests to perform their plugin action.
  - (string) –
    - (dict) –
      
      A user input field in an plugin action execution payload.
      - value (document) – [REQUIRED]
        
        The content of a user input field in an plugin action execution payload.
- payloadFieldNameSeparator (string) – [REQUIRED]
  
  A string used to retain information about the hierarchical contexts within an action execution event payload.
authChallengeResponse (dict) –
An authentication verification event response by a third party authentication server to Amazon Q Business.
- responseMap (dict) – [REQUIRED]
  
  The mapping of key-value pairs in an authentication challenge response.
  - (string) –
    - (string) –
conversationId (string) – The identifier of the Amazon Q Business conversation.
parentMessageId (string) – The identifier of the previous system message in a conversation.
attributeFilter (dict) –
Enables filtering of Amazon Q Business web experience responses based on document attributes or metadata fields.
- andAllFilters (list) –
  
  Performs a logical AND operation on all supplied filters.
  - (dict) –
    
    Enables filtering of responses based on document attributes or metadata fields.
- orAllFilters (list) –
  
  Performs a logical OR operation on all supplied filters.
  - (dict) –
    
    Enables filtering of responses based on document attributes or metadata fields.
- notFilter (dict) –
  
  Performs a logical NOT operation on all supplied filters.
- equalsTo (dict) –
  
  Performs an equals operation on two document attributes or metadata fields. Supported for the following document attribute value types: dateValue, longValue, stringListValue and stringValue.
  - name (string) – [REQUIRED]
    
    The identifier for the attribute.
  - value (dict) – [REQUIRED]
    
    The value of the attribute.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.
    - stringValue (string) –
      
      A string.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - longValue (integer) –
      
      A long integer value.
    - dateValue (datetime) –
      
      A date expressed as an ISO 8601 string.
      
      It’s important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.
- containsAll (dict) –
  
  Returns true when a document contains all the specified document attributes or metadata fields. Supported for the following document attribute value types: stringListValue.
  - name (string) – [REQUIRED]
    
    The identifier for the attribute.
  - value (dict) – [REQUIRED]
    
    The value of the attribute.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.
    - stringValue (string) –
      
      A string.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - longValue (integer) –
      
      A long integer value.
    - dateValue (datetime) –
      
      A date expressed as an ISO 8601 string.
      
      It’s important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.
- containsAny (dict) –
  
  Returns true when a document contains any of the specified document attributes or metadata fields. Supported for the following document attribute value types: stringListValue.
  - name (string) – [REQUIRED]
    
    The identifier for the attribute.
  - value (dict) – [REQUIRED]
    
    The value of the attribute.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.
    - stringValue (string) –
      
      A string.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - longValue (integer) –
      
      A long integer value.
    - dateValue (datetime) –
      
      A date expressed as an ISO 8601 string.
      
      It’s important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.
- greaterThan (dict) –
  
  Performs a greater than operation on two document attributes or metadata fields. Supported for the following document attribute value types: dateValue and longValue.
  - name (string) – [REQUIRED]
    
    The identifier for the attribute.
  - value (dict) – [REQUIRED]
    
    The value of the attribute.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.
    - stringValue (string) –
      
      A string.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - longValue (integer) –
      
      A long integer value.
    - dateValue (datetime) –
      
      A date expressed as an ISO 8601 string.
      
      It’s important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.
- greaterThanOrEquals (dict) –
  
  Performs a greater or equals than operation on two document attributes or metadata fields. Supported for the following document attribute value types: dateValue and longValue.
  - name (string) – [REQUIRED]
    
    The identifier for the attribute.
  - value (dict) – [REQUIRED]
    
    The value of the attribute.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.
    - stringValue (string) –
      
      A string.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - longValue (integer) –
      
      A long integer value.
    - dateValue (datetime) –
      
      A date expressed as an ISO 8601 string.
      
      It’s important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.
- lessThan (dict) –
  
  Performs a less than operation on two document attributes or metadata fields. Supported for the following document attribute value types: dateValue and longValue.
  - name (string) – [REQUIRED]
    
    The identifier for the attribute.
  - value (dict) – [REQUIRED]
    
    The value of the attribute.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.
    - stringValue (string) –
      
      A string.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - longValue (integer) –
      
      A long integer value.
    - dateValue (datetime) –
      
      A date expressed as an ISO 8601 string.
      
      It’s important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.
- lessThanOrEquals (dict) –
  
  Performs a less than or equals operation on two document attributes or metadata fields.Supported for the following document attribute value type: dateValue and longValue.
  - name (string) – [REQUIRED]
    
    The identifier for the attribute.
  - value (dict) – [REQUIRED]
    
    The value of the attribute.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.
    - stringValue (string) –
      
      A string.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - longValue (integer) –
      
      A long integer value.
    - dateValue (datetime) –
      
      A date expressed as an ISO 8601 string.
      
      It’s important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.
chatMode (string) –
The chat modes available to an Amazon Q Business end user.
- RETRIEVAL_MODE - The default chat mode for an Amazon Q Business application. When this mode is enabled, Amazon Q Business generates responses only from data sources connected to an Amazon Q Business application.
- CREATOR_MODE - By selecting this mode, users can choose to generate responses only from the LLM knowledge, without consulting connected data sources, for a chat request.
- PLUGIN_MODE - By selecting this mode, users can choose to use plugins in chat.
For more information, see Admin controls and guardrails, Plugins, and Conversation settings.
chatModeConfiguration (dict) –
The chat mode configuration for an Amazon Q Business application.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: pluginConfiguration.
- pluginConfiguration (dict) –
  
  Configuration information required to invoke chat in PLUGIN_MODE.
  - pluginId (string) – [REQUIRED]
    
    The identifier of the plugin you want to use.
clientToken (string) –
A token that you provide to identify a chat request.

This field is autopopulated if not provided.

Return type:

dict

Returns:

Response Syntax

{
    'conversationId': 'string',
    'systemMessage': 'string',
    'systemMessageId': 'string',
    'userMessageId': 'string',
    'actionReview': {
        'pluginId': 'string',
        'pluginType': 'SERVICE_NOW'|'SALESFORCE'|'JIRA'|'ZENDESK'|'CUSTOM',
        'payload': {
            'string': {
                'displayName': 'string',
                'displayOrder': 123,
                'displayDescription': 'string',
                'type': 'STRING'|'NUMBER'|'ARRAY'|'BOOLEAN',
                'value': {...}|[...]|123|123.4|'string'|True|None,
                'allowedValues': [
                    {
                        'value': {...}|[...]|123|123.4|'string'|True|None,
                        'displayValue': {...}|[...]|123|123.4|'string'|True|None
                    },
                ],
                'allowedFormat': 'string',
                'arrayItemJsonSchema': {...}|[...]|123|123.4|'string'|True|None,
                'required': True|False
            }
        },
        'payloadFieldNameSeparator': 'string'
    },
    'authChallengeRequest': {
        'authorizationUrl': 'string'
    },
    'sourceAttributions': [
        {
            'title': 'string',
            'snippet': 'string',
            'url': 'string',
            'citationNumber': 123,
            'updatedAt': datetime(2015, 1, 1),
            'textMessageSegments': [
                {
                    'beginOffset': 123,
                    'endOffset': 123,
                    'snippetExcerpt': {
                        'text': 'string'
                    }
                },
            ]
        },
    ],
    'failedAttachments': [
        {
            'name': 'string',
            'status': 'FAILED'|'SUCCEEDED',
            'error': {
                'errorMessage': 'string',
                'errorCode': 'InternalError'|'InvalidRequest'|'ResourceInactive'|'ResourceNotFound'
            }
        },
    ]
}

Response Structure

(dict) –
- conversationId (string) –
  
  The identifier of the Amazon Q Business conversation.
- systemMessage (string) –
  
  An AI-generated message in a conversation.
- systemMessageId (string) –
  
  The identifier of an Amazon Q Business AI generated message within the conversation.
- userMessageId (string) –
  
  The identifier of an Amazon Q Business end user text input message within the conversation.
- actionReview (dict) –
  
  A request from Amazon Q Business to the end user for information Amazon Q Business needs to successfully complete a requested plugin action.
  - pluginId (string) –
    
    The identifier of the plugin associated with the action review.
  - pluginType (string) –
    
    The type of plugin.
  - payload (dict) –
    
    Field values that an end user needs to provide to Amazon Q Business for Amazon Q Business to perform the requested plugin action.
    - (string) –
      - (dict) –
        
        A user input field in an plugin action review payload.
        
        displayName (string) –
        
        The name of the field.
        
        displayOrder (integer) –
        
        The display order of fields in a payload.
        
        displayDescription (string) –
        
        The field level description of each action review input field. This could be an explanation of the field. In the Amazon Q Business web experience, these descriptions could be used to display as tool tips to help users understand the field.
        
        type (string) –
        
        The type of field.
        
        value (document) –
        
        The field value.
        
        allowedValues (list) –
        
        Information about the field values that an end user can use to provide to Amazon Q Business for Amazon Q Business to perform the requested plugin action.
        
        (dict) –
        
        Information about the field values that an end user can use to provide to Amazon Q Business for Amazon Q Business to perform the requested plugin action.
        
        value (document) –
        
        The field value.
        
        displayValue (document) –
        
        The name of the field.
        
        allowedFormat (string) –
        
        The expected data format for the action review input field value. For example, in PTO request, from and to would be of datetime allowed format.
        
        arrayItemJsonSchema (document) –
        
        Use to create a custom form with array fields (fields with nested objects inside an array).
        
        required (boolean) –
        
        Information about whether the field is required.
  - payloadFieldNameSeparator (string) –
    
    A string used to retain information about the hierarchical contexts within an action review payload.
- authChallengeRequest (dict) –
  
  An authentication verification event activated by an end user request to use a custom plugin.
  - authorizationUrl (string) –
    
    The URL sent by Amazon Q Business to the third party authentication server to authenticate a custom plugin user through an OAuth protocol.
- sourceAttributions (list) –
  
  The source documents used to generate the conversation response.
  - (dict) –
    
    The documents used to generate an Amazon Q Business web experience response.
    - title (string) –
      
      The title of the document which is the source for the Amazon Q Business generated response.
    - snippet (string) –
      
      The content extract from the document on which the generated response is based.
    - url (string) –
      
      The URL of the document which is the source for the Amazon Q Business generated response.
    - citationNumber (integer) –
      
      The number attached to a citation in an Amazon Q Business generated response.
    - updatedAt (datetime) –
      
      The Unix timestamp when the Amazon Q Business application was last updated.
    - textMessageSegments (list) –
      
      A text extract from a source document that is used for source attribution.
      - (dict) –
        
        Provides information about a text extract in a chat response that can be attributed to a source document.
        
        beginOffset (integer) –
        
        The zero-based location in the response string where the source attribution starts.
        
        endOffset (integer) –
        
        The zero-based location in the response string where the source attribution ends.
        
        snippetExcerpt (dict) –
        
        The relevant text excerpt from a source that was used to generate a citation text segment in an Amazon Q Business chat response.
        
        text (string) –
        
        The relevant text excerpt from a source that was used to generate a citation text segment in an Amazon Q chat response.
- failedAttachments (list) –
  
  A list of files which failed to upload during chat.
  - (dict) –
    
    The details of a file uploaded during chat.
    - name (string) –
      
      The name of a file uploaded during chat.
    - status (string) –
      
      The status of a file uploaded during chat.
    - error (dict) –
      
      An error associated with a file uploaded during chat.
      - errorMessage (string) –
        
        The message explaining the data source sync error.
      - errorCode (string) –
        
        The code associated with the data source sync error.

Exceptions

QBusiness.Client.exceptions.ResourceNotFoundException
QBusiness.Client.exceptions.InternalServerException
QBusiness.Client.exceptions.LicenseNotFoundException
QBusiness.Client.exceptions.ConflictException
QBusiness.Client.exceptions.ThrottlingException
QBusiness.Client.exceptions.ValidationException
QBusiness.Client.exceptions.AccessDeniedException