Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors Examples See Also

GetContactMetrics

Retrieves contact metric data for a specified contact.

Use cases

Following are common use cases for position in queue and estimated wait time:

Customer-Facing Wait Time Announcements - Display or announce the estimated wait time and position in queue to customers before or during their queue experience.
Callback Offerings - Offer customers a callback option when the estimated wait time or position in queue exceeds a defined threshold.
Queue Routing Decisions - Route incoming contacts to less congested queues by comparing estimated wait time and position in queue across multiple queues.
Self-Service Deflection - Redirect customers to self-service options like chatbots or FAQs when estimated wait time is high or position in queue is unfavorable.

Important things to know

Metrics are only available while the contact is actively in queue.
For more information, see the Position in queue metric in the Amazon Connect Administrator Guide.

Endpoints: See Amazon Connect endpoints and quotas.

Request Syntax


POST /metrics/contact HTTP/1.1
Content-type: application/json

{
   "ContactId": "string",
   "InstanceId": "string",
   "Metrics": [ 
      { 
         "Name": "string"
      }
   ]
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

ContactId

The identifier of the contact in this instance of Amazon Connect.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 250.

Pattern: ^(arn:(aws|aws-us-gov):connect:[a-z]{2}-[a-z]+-[0-9]{1}:[0-9]{1,20}:instance/)?[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: Yes

InstanceId

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

Type: String

Length Constraints: Minimum length of 1. Maximum length of 250.

Pattern: ^(arn:(aws|aws-us-gov):connect:[a-z]{2}-[a-z]+-[0-9]{1}:[0-9]{1,20}:instance/)?[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$

Required: Yes

Metrics

A list of contact level metrics to retrieve.Supported metrics include POSITION_IN_QUEUE (the contact's current position in the queue) and ESTIMATED_WAIT_TIME (the predicted time in seconds until the contact is connected to an agent)

Type: Array of ContactMetricInfo objects

Array Members: Minimum number of 1 item.

Required: Yes

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "Arn": "string",
   "Id": "string",
   "MetricResults": [ 
      { 
         "Name": "string",
         "Value": { ... }
      }
   ]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Arn

The ARN of the contact for which metrics were retrieved.

Type: String

Id

The unique identifier of the contact for which metrics were retrieved. This matches the ContactId provided in the request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

MetricResults

A list of metric results containing the calculated values for each requested metric. Each result includes the metric name and its corresponding value. For example, POSITION_IN_QUEUE returns a numeric value representing the contact's position in queue, and ESTIMATED_WAIT_TIME returns the predicted wait time in seconds.

Type: Array of ContactMetricResult objects

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You do not have sufficient permissions to perform this action.

HTTP Status Code: 403

InternalServiceException

Request processing failed because of an error or failure with the service.

Message: The message.

HTTP Status Code: 500

InvalidParameterException

One or more of the specified parameters are not valid.

Message: The message about the parameters.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

Message: The message about the request.
Reason: Reason why the request was invalid.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource was not found.

Message: The message about the resource.

HTTP Status Code: 404

ThrottlingException

The throttling limit has been exceeded.

HTTP Status Code: 429

Examples

Example request to retrieve position in queue and estimated wait time

Following is an example of retrieving the position in queue and estimated wait time for a contact.


{
     "InstanceId":"12345678-1234-5678-aabb-123456abcdef",
     "ContactId":"12345678-1234-5678-aabb-123456abcdef",
     "Metrics":[ { "Name": "POSITION_IN_QUEUE"}, { "Name": "ESTIMATED_WAIT_TIME"} ]
     }

Example response with the position in queue and estimated wait time

Following is an example response. In this case, the contact is number 3 in the queue with an estimated wait time of 120 seconds.


{
     "Id":"12345678-1234-5678-aabb-123456abcdef",
     "Arn":"arn:aws:connect:us-east-1:123456789012:instance/12345678-1234-5678-aabb-123456abcdef/contact/12345678-1234-5678-aabb-123456abcdef",
     "MetricResults":[ { "Name": "POSITION_IN_QUEUE","Value":{"Number":3.00}}, { "Name": "ESTIMATED_WAIT_TIME","Value":{"Number":120.00}}]
     }