QBusiness / Client / chat_sync

chat_sync#

QBusiness.Client.chat_sync(**kwargs)#

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

See also: AWS API Documentation

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