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 array of agent ids

    • (string) –

  • AgentHierarchyGroups (dict) –

    The agent hierarchy groups

    • 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 array of channels

    • (string) –

  • ContactAnalysis (dict) –

    The ContactAnalysis object used in search criteria

    • Transcript (dict) –

      A structure that defines filters can be used to search with text within an Amazon Connect Contact Lens analyzed transcript.

      • Criteria (list) – [REQUIRED]

        The array of transcript search criteria

        • (dict) –

          The transcript criteria used to search

          • 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 of search texts in a transcript criteria.

      • MatchType (string) –

        The match type of multiple transcript criteira

  • InitiationMethods (list) –

    The array of initiaton methods

    • (string) –

  • QueueIds (list) –

    The array of queue ids.

    • (string) –

  • SearchableContactAttributes (dict) –

    The SearchableContactAttributes object used in search criteria

    • Criteria (list) – [REQUIRED]

      The array of searhale contact attribute criteria

      • (dict) –

        The criteria of searchable contact attributes.

        • Key (string) – [REQUIRED]

          The searchable contact attribute key

        • Values (list) – [REQUIRED]

          The array of contact attribute values used to filter search results.

          • (string) –

    • MatchType (string) –

      The match type of multiple searchable contact attributes criteria.

• 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