2023/12/21 - Amazon Connect Service - 12 new 3 updated api methods
Changes Adds APIs to manage User Proficiencies and Predefined Attributes. Enhances StartOutboundVoiceContact API input. Introduces SearchContacts API. Enhances DescribeContact API. Adds an API to update Routing Attributes in QueuePriority and QueueTimeAdjustmentSeconds.
This API is in preview release for Amazon Connect and is subject to change.
Updates routing priority and age on the contact (QueuePriority and QueueTimeAdjustmentInSeconds ). These properties can be used to change a customer's position in the queue. For example, you can move a contact to the back of the queue by setting a lower routing priority relative to other contacts in queue; or you can move a contact to the front of the queue by increasing the routing age which will make the contact look artificially older and therefore higher up in the first-in-first-out routing order. Note that adjusting the routing age of a contact affects only its position in queue, and not its actual queue wait time as reported through metrics. These properties can also be updated by using the Set routing priority / age flow block .
See also: AWS API Documentation
Request Syntax
client.update_contact_routing_data(
InstanceId='string',
ContactId='string',
QueueTimeAdjustmentSeconds=123,
QueuePriority=123
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the contact in this instance of Amazon Connect.
integer
The number of seconds to add or subtract from the contact's routing age. Contacts are routed to agents on a first-come, first-serve basis. This means that changing their amount of time in queue compared to others also changes their position in queue.
integer
Priority of the contact in the queue. The default priority for new contacts is 5. You can raise the priority of a contact compared to other contacts in the queue by assigning them a higher priority, such as 1 or 2.
dict
Response Syntax
{}
Response Structure
(dict) --
Updates a predefined attribute for the specified Amazon Connect instance.
See also: AWS API Documentation
Request Syntax
client.update_predefined_attribute(
InstanceId='string',
Name='string',
Values={
'StringList': [
'string',
]
}
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The name of the predefined attribute.
dict
The values of the predefined attribute.
StringList (list) --
Predefined attribute values of type string list.
(string) --
None
Searches contacts in an Amazon Connect instance.
See also: AWS API Documentation
Request Syntax
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'
}
)
string
[REQUIRED]
The identifier of Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance
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.
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.
integer
The maximum number of results to return per page.
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.
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.
dict
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.
Lists proficiencies associated with a user.
See also: AWS API Documentation
Request Syntax
client.list_user_proficiencies(
InstanceId='string',
UserId='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the user account.
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.
integer
The maximum number of results to return per page.
dict
Response Syntax
{
'NextToken': 'string',
'UserProficiencyList': [
{
'AttributeName': 'string',
'AttributeValue': 'string',
'Level': ...
},
],
'LastModifiedTime': datetime(2015, 1, 1),
'LastModifiedRegion': 'string'
}
Response Structure
(dict) --
NextToken (string) --
If there are additional results, this is the token for the next set of results.
UserProficiencyList (list) --
Information about the user proficiencies.
(dict) --
Information about proficiency of a user.
AttributeName (string) --
The name of user's proficiency. You must use name of predefined attribute present in the Amazon Connect instance.
AttributeValue (string) --
The value of user's proficiency. You must use value of predefined attribute present in the Amazon Connect instance.
Level (float) --
The level of the proficiency. The valid values are 1, 2, 3, 4 and 5.
LastModifiedTime (datetime) --
The last time that the user's proficiencies are were modified.
LastModifiedRegion (string) --
The region in which a user's proficiencies were last modified.
Deletes a predefined attribute from the specified Amazon Connect instance.
See also: AWS API Documentation
Request Syntax
client.delete_predefined_attribute(
InstanceId='string',
Name='string'
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The name of the predefined attribute.
None
Describes a predefined attribute for the specified Amazon Connect instance.
See also: AWS API Documentation
Request Syntax
client.describe_predefined_attribute(
InstanceId='string',
Name='string'
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The name of the predefined attribute.
dict
Response Syntax
{
'PredefinedAttribute': {
'Name': 'string',
'Values': {
'StringList': [
'string',
]
},
'LastModifiedTime': datetime(2015, 1, 1),
'LastModifiedRegion': 'string'
}
}
Response Structure
(dict) --
PredefinedAttribute (dict) --
Information about the predefined attribute.
Name (string) --
The name of the predefined attribute.
Values (dict) --
The values of the predefined attribute.
StringList (list) --
Predefined attribute values of type string list.
(string) --
LastModifiedTime (datetime) --
Last modified time.
LastModifiedRegion (string) --
Last modified region.
Updates the properties associated with the proficiencies of a user.
See also: AWS API Documentation
Request Syntax
client.update_user_proficiencies(
InstanceId='string',
UserId='string',
UserProficiencies=[
{
'AttributeName': 'string',
'AttributeValue': 'string',
'Level': ...
},
]
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the user account.
list
[REQUIRED]
The proficiencies to be updated for the user. Proficiencies must first be associated to the user. You can do this using AssociateUserProficiencies API.
(dict) --
Information about proficiency of a user.
AttributeName (string) -- [REQUIRED]
The name of user's proficiency. You must use name of predefined attribute present in the Amazon Connect instance.
AttributeValue (string) -- [REQUIRED]
The value of user's proficiency. You must use value of predefined attribute present in the Amazon Connect instance.
Level (float) -- [REQUIRED]
The level of the proficiency. The valid values are 1, 2, 3, 4 and 5.
None
Predefined attributes that meet certain criteria.
See also: AWS API Documentation
Request Syntax
client.search_predefined_attributes(
InstanceId='string',
NextToken='string',
MaxResults=123,
SearchCriteria={
'OrConditions': [
{'... recursive ...'},
],
'AndConditions': [
{'... recursive ...'},
],
'StringCondition': {
'FieldName': 'string',
'Value': 'string',
'ComparisonType': 'STARTS_WITH'|'CONTAINS'|'EXACT'
}
}
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
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.
integer
The maximum number of results to return per page.
dict
The search criteria to be used to return predefined attributes.
OrConditions (list) --
A list of conditions which would be applied together with an OR condition.
(dict) --
The search criteria to be used to return predefined attributes.
AndConditions (list) --
A list of conditions which would be applied together with an AND condition.
(dict) --
The search criteria to be used to return predefined attributes.
StringCondition (dict) --
A leaf node condition which can be used to specify a string condition.
Note
The currently supported values for FieldName are name and description .
FieldName (string) --
The name of the field in the string condition.
Value (string) --
The value of the string.
ComparisonType (string) --
The type of comparison to be made when evaluating the string condition.
dict
Response Syntax
{
'PredefinedAttributes': [
{
'Name': 'string',
'Values': {
'StringList': [
'string',
]
},
'LastModifiedTime': datetime(2015, 1, 1),
'LastModifiedRegion': 'string'
},
],
'NextToken': 'string',
'ApproximateTotalCount': 123
}
Response Structure
(dict) --
PredefinedAttributes (list) --
Predefined attributes matched by the search criteria.
(dict) --
Information about a predefined attribute.
Name (string) --
The name of the predefined attribute.
Values (dict) --
The values of the predefined attribute.
StringList (list) --
Predefined attribute values of type string list.
(string) --
LastModifiedTime (datetime) --
Last modified time.
LastModifiedRegion (string) --
Last modified region.
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.
ApproximateTotalCount (integer) --
The approximate number of predefined attributes which matched your search query.
Creates a new predefined attribute for the specified Amazon Connect instance.
See also: AWS API Documentation
Request Syntax
client.create_predefined_attribute(
InstanceId='string',
Name='string',
Values={
'StringList': [
'string',
]
}
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The name of the predefined attribute.
dict
[REQUIRED]
The values of the predefined attribute.
StringList (list) --
Predefined attribute values of type string list.
(string) --
None
>Associates a set of proficiencies with a user.
See also: AWS API Documentation
Request Syntax
client.associate_user_proficiencies(
InstanceId='string',
UserId='string',
UserProficiencies=[
{
'AttributeName': 'string',
'AttributeValue': 'string',
'Level': ...
},
]
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN of the instance).
string
[REQUIRED]
The identifier of the user account.
list
[REQUIRED]
The proficiencies to associate with the user.
(dict) --
Information about proficiency of a user.
AttributeName (string) -- [REQUIRED]
The name of user's proficiency. You must use name of predefined attribute present in the Amazon Connect instance.
AttributeValue (string) -- [REQUIRED]
The value of user's proficiency. You must use value of predefined attribute present in the Amazon Connect instance.
Level (float) -- [REQUIRED]
The level of the proficiency. The valid values are 1, 2, 3, 4 and 5.
None
Disassociates a set of proficiencies from a user.
See also: AWS API Documentation
Request Syntax
client.disassociate_user_proficiencies(
InstanceId='string',
UserId='string',
UserProficiencies=[
{
'AttributeName': 'string',
'AttributeValue': 'string'
},
]
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the user account.
list
[REQUIRED]
The proficiencies to disassociate from the user.
(dict) --
Information about proficiency to be disassociated from the user.
AttributeName (string) -- [REQUIRED]
The name of user's proficiency.
AttributeValue (string) -- [REQUIRED]
The value of user's proficiency.
None
Lists predefined attributes for the specified Amazon Connect instance.
See also: AWS API Documentation
Request Syntax
client.list_predefined_attributes(
InstanceId='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
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.
integer
The maximum number of results to return per page.
dict
Response Syntax
{
'NextToken': 'string',
'PredefinedAttributeSummaryList': [
{
'Name': 'string',
'LastModifiedTime': datetime(2015, 1, 1),
'LastModifiedRegion': 'string'
},
]
}
Response Structure
(dict) --
NextToken (string) --
If there are additional results, this is the token for the next set of results.
PredefinedAttributeSummaryList (list) --
Summary of the predefined attributes.
(dict) --
Summary of a predefined attribute.
Name (string) --
The name of the predefined attribute.
LastModifiedTime (datetime) --
Last modified time.
LastModifiedRegion (string) --
Last modified region.
{'Contact': {'QueuePriority': 'long', 'QueueTimeAdjustmentSeconds': 'integer'}}
This API is in preview release for Amazon Connect and is subject to change.
Describes the specified contact.
Warning
Contact information remains available in Amazon Connect for 24 months, and then it is deleted.
Only data from November 12, 2021, and later is returned by this API.
See also: AWS API Documentation
Request Syntax
client.describe_contact(
InstanceId='string',
ContactId='string'
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
string
[REQUIRED]
The identifier of the contact.
dict
Response Syntax
{
'Contact': {
'Arn': 'string',
'Id': 'string',
'InitialContactId': 'string',
'PreviousContactId': 'string',
'InitiationMethod': 'INBOUND'|'OUTBOUND'|'TRANSFER'|'QUEUE_TRANSFER'|'CALLBACK'|'API'|'DISCONNECT'|'MONITOR'|'EXTERNAL_OUTBOUND',
'Name': 'string',
'Description': 'string',
'Channel': 'VOICE'|'CHAT'|'TASK',
'QueueInfo': {
'Id': 'string',
'EnqueueTimestamp': datetime(2015, 1, 1)
},
'AgentInfo': {
'Id': 'string',
'ConnectedToAgentTimestamp': datetime(2015, 1, 1),
'AgentPauseDurationInSeconds': 123
},
'InitiationTimestamp': datetime(2015, 1, 1),
'DisconnectTimestamp': datetime(2015, 1, 1),
'LastUpdateTimestamp': datetime(2015, 1, 1),
'LastPausedTimestamp': datetime(2015, 1, 1),
'LastResumedTimestamp': datetime(2015, 1, 1),
'TotalPauseCount': 123,
'TotalPauseDurationInSeconds': 123,
'ScheduledTimestamp': datetime(2015, 1, 1),
'RelatedContactId': 'string',
'WisdomInfo': {
'SessionArn': 'string'
},
'QueueTimeAdjustmentSeconds': 123,
'QueuePriority': 123,
'Tags': {
'string': 'string'
}
}
}
Response Structure
(dict) --
Contact (dict) --
Information about the contact.
Arn (string) --
The Amazon Resource Name (ARN) for the contact.
Id (string) --
The identifier for the contact.
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.
Name (string) --
The name of the contact.
Description (string) --
The description of the contact.
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.
AgentPauseDurationInSeconds (integer) --
Agent pause duration for a contact in seconds.
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.
LastUpdateTimestamp (datetime) --
The timestamp when contact was last updated.
LastPausedTimestamp (datetime) --
The timestamp when the contact was last paused.
LastResumedTimestamp (datetime) --
The timestamp when the contact was last resumed.
TotalPauseCount (integer) --
Total pause count for a contact.
TotalPauseDurationInSeconds (integer) --
Total pause duration for a contact in seconds.
ScheduledTimestamp (datetime) --
The timestamp, in Unix epoch time format, at which to start running the inbound flow.
RelatedContactId (string) --
The contactId that is related to this contact.
WisdomInfo (dict) --
Information about Amazon Connect Wisdom.
SessionArn (string) --
The Amazon Resource Name (ARN) of the Wisdom session.
QueueTimeAdjustmentSeconds (integer) --
An integer that represents the queue time adjust to be applied to the contact, in seconds (longer / larger queue time are routed preferentially). Cannot be specified if the QueuePriority is specified. Must be statically defined and a valid integer value.
QueuePriority (integer) --
An integer that represents the queue priority to be applied to the contact (lower priorities are routed preferentially). Cannot be specified if the QueueTimeAdjustmentSeconds is specified. Must be statically defined, must be larger than zero, and a valid integer value. Default Value is 5.
Tags (dict) --
Tags associated with the contact. This contains both Amazon Web Services generated and user-defined tags.
(string) --
(string) --
{'Filters': {'RoutingStepExpressions': ['string']},
'Groupings': {'ROUTING_STEP_EXPRESSION'}}
Response {'MetricResults': {'Dimensions': {'RoutingStepExpression': 'string'}}}
Gets the real-time metric data from the specified Amazon Connect instance.
For a description of each metric, see Real-time Metrics Definitions in the Amazon Connect Administrator Guide .
See also: AWS API Documentation
Request Syntax
client.get_current_metric_data(
InstanceId='string',
Filters={
'Queues': [
'string',
],
'Channels': [
'VOICE'|'CHAT'|'TASK',
],
'RoutingProfiles': [
'string',
],
'RoutingStepExpressions': [
'string',
]
},
Groupings=[
'QUEUE'|'CHANNEL'|'ROUTING_PROFILE'|'ROUTING_STEP_EXPRESSION',
],
CurrentMetrics=[
{
'Name': 'AGENTS_ONLINE'|'AGENTS_AVAILABLE'|'AGENTS_ON_CALL'|'AGENTS_NON_PRODUCTIVE'|'AGENTS_AFTER_CONTACT_WORK'|'AGENTS_ERROR'|'AGENTS_STAFFED'|'CONTACTS_IN_QUEUE'|'OLDEST_CONTACT_AGE'|'CONTACTS_SCHEDULED'|'AGENTS_ON_CONTACT'|'SLOTS_ACTIVE'|'SLOTS_AVAILABLE',
'Unit': 'SECONDS'|'COUNT'|'PERCENT'
},
],
NextToken='string',
MaxResults=123,
SortCriteria=[
{
'SortByMetric': 'AGENTS_ONLINE'|'AGENTS_AVAILABLE'|'AGENTS_ON_CALL'|'AGENTS_NON_PRODUCTIVE'|'AGENTS_AFTER_CONTACT_WORK'|'AGENTS_ERROR'|'AGENTS_STAFFED'|'CONTACTS_IN_QUEUE'|'OLDEST_CONTACT_AGE'|'CONTACTS_SCHEDULED'|'AGENTS_ON_CONTACT'|'SLOTS_ACTIVE'|'SLOTS_AVAILABLE',
'SortOrder': 'ASCENDING'|'DESCENDING'
},
]
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
dict
[REQUIRED]
The filters to apply to returned metrics. You can filter up to the following limits:
Queues: 100
Routing profiles: 100
Channels: 3 (VOICE, CHAT, and TASK channels are supported.)
Metric data is retrieved only for the resources associated with the queues or routing profiles, and by any channels included in the filter. (You cannot filter by both queue AND routing profile.) You can include both resource IDs and resource ARNs in the same request.
Currently tagging is only supported on the resources that are passed in the filter.
Queues (list) --
The queues to use to filter the metrics. You should specify at least one queue, and can specify up to 100 queues per request. The GetCurrentMetricsData API in particular requires a queue when you include a Filter in your request.
(string) --
Channels (list) --
The channel to use to filter the metrics.
(string) --
RoutingProfiles (list) --
A list of up to 100 routing profile IDs or ARNs.
(string) --
RoutingStepExpressions (list) --
A list of expressions as a filter, in which an expression is an object of a step in a routing criteria.
(string) --
list
The grouping applied to the metrics returned. For example, when grouped by QUEUE , the metrics returned apply to each queue rather than aggregated for all queues.
If you group by CHANNEL , you should include a Channels filter. VOICE, CHAT, and TASK channels are supported.
If you group by ROUTING_PROFILE , you must include either a queue or routing profile filter. In addition, a routing profile filter is required for metrics CONTACTS_SCHEDULED , CONTACTS_IN_QUEUE , and OLDEST_CONTACT_AGE .
If no Grouping is included in the request, a summary of metrics is returned.
(string) --
list
[REQUIRED]
The metrics to retrieve. Specify the name and unit for each metric. The following metrics are available. For a description of all the metrics, see Real-time Metrics Definitions in the Amazon Connect Administrator Guide .
AGENTS_AFTER_CONTACT_WORK
Unit: COUNT
Name in real-time metrics report: ACW
AGENTS_AVAILABLE
Unit: COUNT
Name in real-time metrics report: Available
AGENTS_ERROR
Unit: COUNT
Name in real-time metrics report: Error
AGENTS_NON_PRODUCTIVE
Unit: COUNT
Name in real-time metrics report: NPT (Non-Productive Time)
AGENTS_ON_CALL
Unit: COUNT
Name in real-time metrics report: On contact
AGENTS_ON_CONTACT
Unit: COUNT
Name in real-time metrics report: On contact
AGENTS_ONLINE
Unit: COUNT
Name in real-time metrics report: Online
AGENTS_STAFFED
Unit: COUNT
Name in real-time metrics report: Staffed
CONTACTS_IN_QUEUE
Unit: COUNT
Name in real-time metrics report: In queue
CONTACTS_SCHEDULED
Unit: COUNT
Name in real-time metrics report: Scheduled
OLDEST_CONTACT_AGE
Unit: SECONDS
When you use groupings, Unit says SECONDS and the Value is returned in SECONDS.
When you do not use groupings, Unit says SECONDS but the Value is returned in MILLISECONDS. For example, if you get a response like this:
{ "Metric": { "Name": "OLDEST_CONTACT_AGE", "Unit": "SECONDS" }, "Value": 24113.0 }
The actual OLDEST_CONTACT_AGE is 24 seconds.
Name in real-time metrics report: Oldest
SLOTS_ACTIVE
Unit: COUNT
Name in real-time metrics report: Active
SLOTS_AVAILABLE
Unit: COUNT
Name in real-time metrics report: Availability
(dict) --
Contains information about a real-time metric. For a description of each metric, see Real-time Metrics Definitions in the Amazon Connect Administrator Guide .
Name (string) --
The name of the metric.
Unit (string) --
The unit for the metric.
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.
The token expires after 5 minutes from the time it is created. Subsequent requests that use the token must use the same request parameters as the request that generated the token.
integer
The maximum number of results to return per page.
list
The way to sort the resulting response based on metrics. You can enter one sort criteria. By default resources are sorted based on AGENTS_ONLINE , DESCENDING . The metric collection is sorted based on the input metrics.
Note the following:
Sorting on SLOTS_ACTIVE and SLOTS_AVAILABLE is not supported.
(dict) --
The way to sort the resulting response based on metrics. By default resources are sorted based on AGENTS_ONLINE , DESCENDING . The metric collection is sorted based on the input metrics.
SortByMetric (string) --
The current metric names.
SortOrder (string) --
The way to sort.
dict
Response Syntax
{
'NextToken': 'string',
'MetricResults': [
{
'Dimensions': {
'Queue': {
'Id': 'string',
'Arn': 'string'
},
'Channel': 'VOICE'|'CHAT'|'TASK',
'RoutingProfile': {
'Id': 'string',
'Arn': 'string'
},
'RoutingStepExpression': 'string'
},
'Collections': [
{
'Metric': {
'Name': 'AGENTS_ONLINE'|'AGENTS_AVAILABLE'|'AGENTS_ON_CALL'|'AGENTS_NON_PRODUCTIVE'|'AGENTS_AFTER_CONTACT_WORK'|'AGENTS_ERROR'|'AGENTS_STAFFED'|'CONTACTS_IN_QUEUE'|'OLDEST_CONTACT_AGE'|'CONTACTS_SCHEDULED'|'AGENTS_ON_CONTACT'|'SLOTS_ACTIVE'|'SLOTS_AVAILABLE',
'Unit': 'SECONDS'|'COUNT'|'PERCENT'
},
'Value': 123.0
},
]
},
],
'DataSnapshotTime': datetime(2015, 1, 1),
'ApproximateTotalCount': 123
}
Response Structure
(dict) --
NextToken (string) --
If there are additional results, this is the token for the next set of results.
The token expires after 5 minutes from the time it is created. Subsequent requests that use the token must use the same request parameters as the request that generated the token.
MetricResults (list) --
Information about the real-time metrics.
(dict) --
Contains information about a set of real-time metrics.
Dimensions (dict) --
The dimensions for the metrics.
Queue (dict) --
Information about the queue for which metrics are returned.
Id (string) --
The identifier of the queue.
Arn (string) --
The Amazon Resource Name (ARN) of the queue.
Channel (string) --
The channel used for grouping and filters.
RoutingProfile (dict) --
Information about the routing profile assigned to the user.
Id (string) --
The identifier of the routing profile.
Arn (string) --
The Amazon Resource Name (ARN) of the routing profile.
RoutingStepExpression (string) --
The expression of a step in a routing criteria.
Collections (list) --
The set of metrics.
(dict) --
Contains the data for a real-time metric.
Metric (dict) --
Information about the metric.
Name (string) --
The name of the metric.
Unit (string) --
The unit for the metric.
Value (float) --
The value of the metric.
DataSnapshotTime (datetime) --
The time at which the metrics were retrieved and cached for pagination.
ApproximateTotalCount (integer) --
The total count of the result, regardless of the current page size.
{'Filters': {'RoutingStepExpressions': ['string']},
'Groupings': {'ROUTING_STEP_EXPRESSION'}}
Response {'MetricResults': {'Dimensions': {'RoutingStepExpression': 'string'}}}
Gets historical metric data from the specified Amazon Connect instance.
For a description of each historical metric, see Historical Metrics Definitions in the Amazon Connect Administrator Guide .
Note
We recommend using the GetMetricDataV2 API. It provides more flexibility, features, and the ability to query longer time ranges than GetMetricData . Use it to retrieve historical agent and contact metrics for the last 3 months, at varying intervals. You can also use it to build custom dashboards to measure historical queue and agent performance. For example, you can track the number of incoming contacts for the last 7 days, with data split by day, to see how contact volume changed per day of the week.
See also: AWS API Documentation
Request Syntax
client.get_metric_data(
InstanceId='string',
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
Filters={
'Queues': [
'string',
],
'Channels': [
'VOICE'|'CHAT'|'TASK',
],
'RoutingProfiles': [
'string',
],
'RoutingStepExpressions': [
'string',
]
},
Groupings=[
'QUEUE'|'CHANNEL'|'ROUTING_PROFILE'|'ROUTING_STEP_EXPRESSION',
],
HistoricalMetrics=[
{
'Name': 'CONTACTS_QUEUED'|'CONTACTS_HANDLED'|'CONTACTS_ABANDONED'|'CONTACTS_CONSULTED'|'CONTACTS_AGENT_HUNG_UP_FIRST'|'CONTACTS_HANDLED_INCOMING'|'CONTACTS_HANDLED_OUTBOUND'|'CONTACTS_HOLD_ABANDONS'|'CONTACTS_TRANSFERRED_IN'|'CONTACTS_TRANSFERRED_OUT'|'CONTACTS_TRANSFERRED_IN_FROM_QUEUE'|'CONTACTS_TRANSFERRED_OUT_FROM_QUEUE'|'CONTACTS_MISSED'|'CALLBACK_CONTACTS_HANDLED'|'API_CONTACTS_HANDLED'|'OCCUPANCY'|'HANDLE_TIME'|'AFTER_CONTACT_WORK_TIME'|'QUEUED_TIME'|'ABANDON_TIME'|'QUEUE_ANSWER_TIME'|'HOLD_TIME'|'INTERACTION_TIME'|'INTERACTION_AND_HOLD_TIME'|'SERVICE_LEVEL',
'Threshold': {
'Comparison': 'LT',
'ThresholdValue': 123.0
},
'Statistic': 'SUM'|'MAX'|'AVG',
'Unit': 'SECONDS'|'COUNT'|'PERCENT'
},
],
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The identifier of the Amazon Connect instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
datetime
[REQUIRED]
The timestamp, in UNIX Epoch time format, at which to start the reporting interval for the retrieval of historical metrics data. The time must be specified using a multiple of 5 minutes, such as 10:05, 10:10, 10:15.
The start time cannot be earlier than 24 hours before the time of the request. Historical metrics are available only for 24 hours.
datetime
[REQUIRED]
The timestamp, in UNIX Epoch time format, at which to end the reporting interval for the retrieval of historical metrics data. The time must be specified using an interval of 5 minutes, such as 11:00, 11:05, 11:10, and must be later than the start time timestamp.
The time range between the start and end time must be less than 24 hours.
dict
[REQUIRED]
The queues, up to 100, or channels, to use to filter the metrics returned. Metric data is retrieved only for the resources associated with the queues or channels included in the filter. You can include both queue IDs and queue ARNs in the same request. VOICE, CHAT, and TASK channels are supported.
Note
To filter by Queues , enter the queue ID/ARN, not the name of the queue.
Queues (list) --
The queues to use to filter the metrics. You should specify at least one queue, and can specify up to 100 queues per request. The GetCurrentMetricsData API in particular requires a queue when you include a Filter in your request.
(string) --
Channels (list) --
The channel to use to filter the metrics.
(string) --
RoutingProfiles (list) --
A list of up to 100 routing profile IDs or ARNs.
(string) --
RoutingStepExpressions (list) --
A list of expressions as a filter, in which an expression is an object of a step in a routing criteria.
(string) --
list
The grouping applied to the metrics returned. For example, when results are grouped by queue, the metrics returned are grouped by queue. The values returned apply to the metrics for each queue rather than aggregated for all queues.
If no grouping is specified, a summary of metrics for all queues is returned.
(string) --
list
[REQUIRED]
The metrics to retrieve. Specify the name, unit, and statistic for each metric. The following historical metrics are available. For a description of each metric, see Historical Metrics Definitions in the Amazon Connect Administrator Guide .
Note
This API does not support a contacts incoming metric (there's no CONTACTS_INCOMING metric missing from the documented list).
ABANDON_TIME
Unit: SECONDS
Statistic: AVG
AFTER_CONTACT_WORK_TIME
Unit: SECONDS
Statistic: AVG
API_CONTACTS_HANDLED
Unit: COUNT
Statistic: SUM
CALLBACK_CONTACTS_HANDLED
Unit: COUNT
Statistic: SUM
CONTACTS_ABANDONED
Unit: COUNT
Statistic: SUM
CONTACTS_AGENT_HUNG_UP_FIRST
Unit: COUNT
Statistic: SUM
CONTACTS_CONSULTED
Unit: COUNT
Statistic: SUM
CONTACTS_HANDLED
Unit: COUNT
Statistic: SUM
CONTACTS_HANDLED_INCOMING
Unit: COUNT
Statistic: SUM
CONTACTS_HANDLED_OUTBOUND
Unit: COUNT
Statistic: SUM
CONTACTS_HOLD_ABANDONS
Unit: COUNT
Statistic: SUM
CONTACTS_MISSED
Unit: COUNT
Statistic: SUM
CONTACTS_QUEUED
Unit: COUNT
Statistic: SUM
CONTACTS_TRANSFERRED_IN
Unit: COUNT
Statistic: SUM
CONTACTS_TRANSFERRED_IN_FROM_QUEUE
Unit: COUNT
Statistic: SUM
CONTACTS_TRANSFERRED_OUT
Unit: COUNT
Statistic: SUM
CONTACTS_TRANSFERRED_OUT_FROM_QUEUE
Unit: COUNT
Statistic: SUM
HANDLE_TIME
Unit: SECONDS
Statistic: AVG
HOLD_TIME
Unit: SECONDS
Statistic: AVG
INTERACTION_AND_HOLD_TIME
Unit: SECONDS
Statistic: AVG
INTERACTION_TIME
Unit: SECONDS
Statistic: AVG
OCCUPANCY
Unit: PERCENT
Statistic: AVG
QUEUE_ANSWER_TIME
Unit: SECONDS
Statistic: AVG
QUEUED_TIME
Unit: SECONDS
Statistic: MAX
SERVICE_LEVEL
You can include up to 20 SERVICE_LEVEL metrics in a request.
Unit: PERCENT
Statistic: AVG
Threshold: For ThresholdValue , enter any whole number from 1 to 604800 (inclusive), in seconds. For Comparison , you must enter LT (for "Less than").
(dict) --
Contains information about a historical metric. For a description of each metric, see Historical Metrics Definitions in the Amazon Connect Administrator Guide .
Name (string) --
The name of the metric.
Threshold (dict) --
The threshold for the metric, used with service level metrics.
Comparison (string) --
The type of comparison. Only "less than" (LT) comparisons are supported.
ThresholdValue (float) --
The threshold value to compare.
Statistic (string) --
The statistic for the metric.
Unit (string) --
The unit for the metric.
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.
integer
The maximum number of results to return per page.
dict
Response Syntax
{
'NextToken': 'string',
'MetricResults': [
{
'Dimensions': {
'Queue': {
'Id': 'string',
'Arn': 'string'
},
'Channel': 'VOICE'|'CHAT'|'TASK',
'RoutingProfile': {
'Id': 'string',
'Arn': 'string'
},
'RoutingStepExpression': 'string'
},
'Collections': [
{
'Metric': {
'Name': 'CONTACTS_QUEUED'|'CONTACTS_HANDLED'|'CONTACTS_ABANDONED'|'CONTACTS_CONSULTED'|'CONTACTS_AGENT_HUNG_UP_FIRST'|'CONTACTS_HANDLED_INCOMING'|'CONTACTS_HANDLED_OUTBOUND'|'CONTACTS_HOLD_ABANDONS'|'CONTACTS_TRANSFERRED_IN'|'CONTACTS_TRANSFERRED_OUT'|'CONTACTS_TRANSFERRED_IN_FROM_QUEUE'|'CONTACTS_TRANSFERRED_OUT_FROM_QUEUE'|'CONTACTS_MISSED'|'CALLBACK_CONTACTS_HANDLED'|'API_CONTACTS_HANDLED'|'OCCUPANCY'|'HANDLE_TIME'|'AFTER_CONTACT_WORK_TIME'|'QUEUED_TIME'|'ABANDON_TIME'|'QUEUE_ANSWER_TIME'|'HOLD_TIME'|'INTERACTION_TIME'|'INTERACTION_AND_HOLD_TIME'|'SERVICE_LEVEL',
'Threshold': {
'Comparison': 'LT',
'ThresholdValue': 123.0
},
'Statistic': 'SUM'|'MAX'|'AVG',
'Unit': 'SECONDS'|'COUNT'|'PERCENT'
},
'Value': 123.0
},
]
},
]
}
Response Structure
(dict) --
NextToken (string) --
If there are additional results, this is the token for the next set of results.
The token expires after 5 minutes from the time it is created. Subsequent requests that use the token must use the same request parameters as the request that generated the token.
MetricResults (list) --
Information about the historical metrics.
If no grouping is specified, a summary of metric data is returned.
(dict) --
Contains information about the historical metrics retrieved.
Dimensions (dict) --
The dimension for the metrics.
Queue (dict) --
Information about the queue for which metrics are returned.
Id (string) --
The identifier of the queue.
Arn (string) --
The Amazon Resource Name (ARN) of the queue.
Channel (string) --
The channel used for grouping and filters.
RoutingProfile (dict) --
Information about the routing profile assigned to the user.
Id (string) --
The identifier of the routing profile.
Arn (string) --
The Amazon Resource Name (ARN) of the routing profile.
RoutingStepExpression (string) --
The expression of a step in a routing criteria.
Collections (list) --
The set of metrics.
(dict) --
Contains the data for a historical metric.
Metric (dict) --
Information about the metric.
Name (string) --
The name of the metric.
Threshold (dict) --
The threshold for the metric, used with service level metrics.
Comparison (string) --
The type of comparison. Only "less than" (LT) comparisons are supported.
ThresholdValue (float) --
The threshold value to compare.
Statistic (string) --
The statistic for the metric.
Unit (string) --
The unit for the metric.
Value (float) --
The value of the metric.