Connect / Client / search_contacts

search_contacts

Connect.Client.search_contacts(**kwargs)

Searches contacts in an Amazon Connect instance.

See also: AWS API Documentation

Request Syntax

response = client.search_contacts(
    InstanceId='string',
    TimeRange={
        'Type': 'INITIATION_TIMESTAMP'|'SCHEDULED_TIMESTAMP'|'CONNECTED_TO_AGENT_TIMESTAMP'|'DISCONNECT_TIMESTAMP',
        'StartTime': datetime(2015, 1, 1),
        'EndTime': datetime(2015, 1, 1)
    },
    SearchCriteria={
        'AgentIds': [
            'string',
        ],
        'AgentHierarchyGroups': {
            'L1Ids': [
                'string',
            ],
            'L2Ids': [
                'string',
            ],
            'L3Ids': [
                'string',
            ],
            'L4Ids': [
                'string',
            ],
            'L5Ids': [
                'string',
            ]
        },
        'Channels': [
            'VOICE'|'CHAT'|'TASK',
        ],
        'ContactAnalysis': {
            'Transcript': {
                'Criteria': [
                    {
                        'ParticipantRole': 'AGENT'|'CUSTOMER'|'SYSTEM'|'CUSTOM_BOT',
                        'SearchText': [
                            'string',
                        ],
                        'MatchType': 'MATCH_ALL'|'MATCH_ANY'
                    },
                ],
                'MatchType': 'MATCH_ALL'|'MATCH_ANY'
            }
        },
        'InitiationMethods': [
            'INBOUND'|'OUTBOUND'|'TRANSFER'|'QUEUE_TRANSFER'|'CALLBACK'|'API'|'DISCONNECT'|'MONITOR'|'EXTERNAL_OUTBOUND',
        ],
        'QueueIds': [
            'string',
        ],
        'SearchableContactAttributes': {
            'Criteria': [
                {
                    'Key': 'string',
                    'Values': [
                        'string',
                    ]
                },
            ],
            'MatchType': 'MATCH_ALL'|'MATCH_ANY'
        }
    },
    MaxResults=123,
    NextToken='string',
    Sort={
        'FieldName': 'INITIATION_TIMESTAMP'|'SCHEDULED_TIMESTAMP'|'CONNECTED_TO_AGENT_TIMESTAMP'|'DISCONNECT_TIMESTAMP'|'INITIATION_METHOD'|'CHANNEL',
        'Order': 'ASCENDING'|'DESCENDING'
    }
)

Parameters:

• InstanceId (string) –

  [REQUIRED]

  The identifier of Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.

• TimeRange (dict) –

  [REQUIRED]

  Time range that you want to search results.

  • Type (string) – [REQUIRED]

    The type of timestamp to search.

  • StartTime (datetime) – [REQUIRED]

    The start time of the time range.

  • EndTime (datetime) – [REQUIRED]

    The end time of the time range.

• SearchCriteria (dict) –

  The search criteria to be used to return contacts.

  • AgentIds (list) –

    The identifiers of agents who handled the contacts.

    • (string) –

  • AgentHierarchyGroups (dict) –

    The agent hierarchy groups of the agent at the time of handling the contact.

    • L1Ids (list) –

      The identifiers for level 1 hierarchy groups.

      • (string) –

    • L2Ids (list) –

      The identifiers for level 2 hierarchy groups.

      • (string) –

    • L3Ids (list) –

      The identifiers for level 3 hierarchy groups.

      • (string) –

    • L4Ids (list) –

      The identifiers for level 4 hierarchy groups.

      • (string) –

    • L5Ids (list) –

      The identifiers for level 5 hierarchy groups.

      • (string) –

  • Channels (list) –

    The list of channels associated with contacts.

    • (string) –

  • ContactAnalysis (dict) –

    Search criteria based on analysis outputs from Amazon Connect Contact Lens.

    • Transcript (dict) –

      Search criteria based on transcript analyzed by Amazon Connect Contact Lens.

      • Criteria (list) – [REQUIRED]

        The list of search criteria based on Contact Lens conversational analytics transcript.

        • (dict) –

          A structure that defines search criteria base on words or phrases, participants in the Contact Lens conversational analytics transcript.

          • ParticipantRole (string) – [REQUIRED]

            The participant role in a transcript

          • SearchText (list) – [REQUIRED]

            The words or phrases used to search within a transcript.

            • (string) –

          • MatchType (string) – [REQUIRED]

            The match type combining search criteria using multiple search texts in a transcript criteria.

      • MatchType (string) –

        The match type combining search criteria using multiple transcript criteria.

  • InitiationMethods (list) –

    The list of initiation methods associated with contacts.

    • (string) –

  • QueueIds (list) –

    The list of queue IDs associated with contacts.

    • (string) –

  • SearchableContactAttributes (dict) –

    The search criteria based on user-defined contact attributes that have been configured for contact search. For more information, see Search by customer contact attributes in the Amazon Connect Administrator Guide.

    Warning

    To use SearchableContactAttributes in a search request, the GetContactAttributes action is required to perform an API request. For more information, see `https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonconnect.html#amazonconnect-actions-as-permissions <https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonconnect.html#amazonconnect-actions-as-permissions>`__Actions defined by Amazon Connect.

    • Criteria (list) – [REQUIRED]

      The list of criteria based on user-defined contact attributes that are configured for contact search.

      • (dict) –

        The search criteria based on user-defned contact attribute key and values to search on.

        • Key (string) – [REQUIRED]

          The key containing a searchable user-defined contact attribute.

        • Values (list) – [REQUIRED]

          The list of values to search for within a user-defined contact attribute.

          • (string) –

    • MatchType (string) –

      The match type combining search criteria using multiple searchable contact attributes.

• MaxResults (integer) – The maximum number of results to return per page.

• NextToken (string) – The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

• Sort (dict) –

  Specifies a field to sort by and a sort order.

  • FieldName (string) – [REQUIRED]

    The name of the field on which to sort.

  • Order (string) – [REQUIRED]

    An ascending or descending sort.

Return type:

dict

Returns:

Response Syntax

{
    'Contacts': [
        {
            'Arn': 'string',
            'Id': 'string',
            'InitialContactId': 'string',
            'PreviousContactId': 'string',
            'InitiationMethod': 'INBOUND'|'OUTBOUND'|'TRANSFER'|'QUEUE_TRANSFER'|'CALLBACK'|'API'|'DISCONNECT'|'MONITOR'|'EXTERNAL_OUTBOUND',
            'Channel': 'VOICE'|'CHAT'|'TASK',
            'QueueInfo': {
                'Id': 'string',
                'EnqueueTimestamp': datetime(2015, 1, 1)
            },
            'AgentInfo': {
                'Id': 'string',
                'ConnectedToAgentTimestamp': datetime(2015, 1, 1)
            },
            'InitiationTimestamp': datetime(2015, 1, 1),
            'DisconnectTimestamp': datetime(2015, 1, 1),
            'ScheduledTimestamp': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string',
    'TotalCount': 123
}

Response Structure

• (dict) –

  • Contacts (list) –

    Information about the contacts.

    • (dict) –

      Information of returned contact.

      • Arn (string) –

        The Amazon Resource Name (ARN) of the contact.

      • Id (string) –

        The identifier of the contact summary.

      • InitialContactId (string) –

        If this contact is related to other contacts, this is the ID of the initial contact.

      • PreviousContactId (string) –

        If this contact is not the first contact, this is the ID of the previous contact.

      • InitiationMethod (string) –

        Indicates how the contact was initiated.

      • Channel (string) –

        How the contact reached your contact center.

      • QueueInfo (dict) –

        If this contact was queued, this contains information about the queue.

        • Id (string) –

          The unique identifier for the queue.

        • EnqueueTimestamp (datetime) –

          The timestamp when the contact was added to the queue.

      • AgentInfo (dict) –

        Information about the agent who accepted the contact.

        • Id (string) –

          The identifier of the agent who accepted the contact.

        • ConnectedToAgentTimestamp (datetime) –

          The timestamp when the contact was connected to the agent.

      • InitiationTimestamp (datetime) –

        The date and time this contact was initiated, in UTC time. For INBOUND, this is when the contact arrived. For OUTBOUND, this is when the agent began dialing. For CALLBACK, this is when the callback contact was created. For TRANSFER and QUEUE_TRANSFER, this is when the transfer was initiated. For API, this is when the request arrived. For EXTERNAL_OUTBOUND, this is when the agent started dialing the external participant. For MONITOR, this is when the supervisor started listening to a contact.

      • DisconnectTimestamp (datetime) –

        The timestamp when the customer endpoint disconnected from Amazon Connect.

      • ScheduledTimestamp (datetime) –

        The timestamp, in Unix epoch time format, at which to start running the inbound flow.

  • NextToken (string) –

    If there are additional results, this is the token for the next set of results.

  • TotalCount (integer) –

    The total number of contacts which matched your search query.

Exceptions

• Connect.Client.exceptions.InvalidRequestException

• Connect.Client.exceptions.InvalidParameterException

• Connect.Client.exceptions.ResourceNotFoundException

• Connect.Client.exceptions.InternalServiceException

• Connect.Client.exceptions.ThrottlingException