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

Parameters:

actionExecution (dict) –
A request from an end user to perform an Amazon Q Business plugin action.
- 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.
- pluginId (string) – [REQUIRED]
  
  The identifier of the plugin the action is attached to.
applicationId (string) –
[REQUIRED]

The identifier of the Amazon Q Business application linked to the Amazon Q Business 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.
  - data (bytes) – [REQUIRED]
    
    The data contained within the uploaded file.
  - name (string) – [REQUIRED]
    
    The name of the file.
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.
- 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: dateValue, longValue, stringListValue, stringValue.
    - 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.
    - longValue (integer) –
      
      A long integer value.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - stringValue (string) –
      
      A string.
- 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: 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: dateValue, longValue, stringListValue, stringValue.
    - 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.
    - longValue (integer) –
      
      A long integer value.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - stringValue (string) –
      
      A string.
- 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: dateValue, longValue, stringListValue, stringValue.
    - 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.
    - longValue (integer) –
      
      A long integer value.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - stringValue (string) –
      
      A string.
- 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: dateValue, longValue, stringListValue, stringValue.
    - 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.
    - longValue (integer) –
      
      A long integer value.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - stringValue (string) –
      
      A string.
- 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: dateValue, longValue, stringListValue, stringValue.
    - 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.
    - longValue (integer) –
      
      A long integer value.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - stringValue (string) –
      
      A string.
- 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: dateValue, longValue, stringListValue, stringValue.
    - 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.
    - longValue (integer) –
      
      A long integer value.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - stringValue (string) –
      
      A string.
- 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: dateValue, longValue, stringListValue, stringValue.
    - 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.
    - longValue (integer) –
      
      A long integer value.
    - stringListValue (list) –
      
      A list of strings.
      - (string) –
    - stringValue (string) –
      
      A string.
- notFilter (dict) –
  
  Performs a logical NOT operation on all supplied filters.
- orAllFilters (list) –
  
  Performs a logical OR operation on all supplied filters.
  - (dict) –
    
    Enables filtering of responses based on document attributes or metadata fields.
chatMode (string) –
The chat modes available in an Amazon Q Business web experience.
- 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.
conversationId (string) – The identifier of the Amazon Q Business conversation.
parentMessageId (string) – The identifier of the previous end user text input message in a conversation.
userGroups (list) –
The groups that a user associated with the chat input belongs to.
- (string) –
userId (string) – The identifier of the user attached to the chat input.
userMessage (string) – A end user message in a conversation.

Return type:

dict

Returns:

Response Syntax

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

Response Structure

(dict) –
- 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.
  - 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.
        
        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.
        
        displayValue (document) –
        
        The name of the field.
        
        value (document) –
        
        The field value.
        
        displayName (string) –
        
        The name of the field.
        
        displayOrder (integer) –
        
        The display order of fields in a payload.
        
        required (boolean) –
        
        Information about whether the field is required.
        
        type (string) –
        
        The type of field.
        
        value (document) –
        
        The field value.
  - payloadFieldNameSeparator (string) –
    
    A string used to retain information about the hierarchical contexts within an action review payload.
  - pluginId (string) –
    
    The identifier of the plugin associated with the action review.
  - pluginType (string) –
    
    The type of plugin.
- conversationId (string) –
  
  The identifier of the Amazon Q Business conversation.
- failedAttachments (list) –
  
  A list of files which failed to upload during chat.
  - (dict) –
    
    The details of a file uploaded during chat.
    - error (dict) –
      
      An error associated with a file uploaded during chat.
      - errorCode (string) –
        
        The code associated with the data source sync error.
      - errorMessage (string) –
        
        The message explaining the data source sync error.
    - name (string) –
      
      The name of a file uploaded during chat.
    - status (string) –
      
      The status of a file uploaded during chat.
- sourceAttributions (list) –
  
  The source documents used to generate the conversation response.
  - (dict) –
    
    The documents used to generate an Amazon Q Business web experience response.
    - citationNumber (integer) –
      
      The number attached to a citation in an Amazon Q Business generated response.
    - snippet (string) –
      
      The content extract from the document on which the generated response is based.
    - 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.
    - title (string) –
      
      The title of the document which is the source for the Amazon Q Business generated response.
    - updatedAt (datetime) –
      
      The Unix timestamp when the Amazon Q Business application was last updated.
    - url (string) –
      
      The URL of the document which is the source for the Amazon Q Business generated response.
- 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.

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