Amazon Connect contact events - Amazon Connect

Amazon Connect contact events

Amazon Connect allows you to subscribe to a near real-time stream of contact (voice calls, chat, and task) events (for example, call is queued) in your Amazon Connect contact center.

You can use contact events to create analytics dashboards to monitor and track contact activity, integrate into workforce management (WFM) solutions to better understand contact center performance, or to integrate applications that react to events (for example, call disconnected) in real-time.

Subscribe to Amazon Connect contact events

Amazon Connect contact events are published using Amazon EventBridge, and can be enabled in a couple of steps for your Amazon Connect instance in the Amazon EventBridge console by creating a new rule. Although events are not ordered, they have a timestamp which enables you to consume the data.

Events are emitted on a best effort basis.

To subscribe to Amazon Connect contact events:

  1. In the Amazon EventBridge console, choose Create rule.

  2. On the Default rule detail page, assign a name to the rule, choose Rule with an event pattern, and then choose Next, as shown in the following image.

    
                        The define rule detail page in the EventBridge console.
  3. On the Build event pattern page, under Event source, verify that AWS events or EventBridge partner events is selected.

  4. Under Sample event type, choose AWS events, and then choose Amazon Connect Contact Event from the dropdown box, as shown in the following image.

    
                        The sample event section, sample event type is AWS events.
  5. For Creation method choose Use pattern form. In the Event pattern section, choose AWS services, Amazon Connect, Amazon Connect Contact Event, and then choose Next, as shown in the following image.

    
                        The Creation method and event pattern sections of the default rule
                            detail page.
  6. On the Select target(s) page, you can then select a target of your choice, which includes a Lambda function, SQS queue, or SNS topic. For information about configuring targets, Amazon EventBridge targets.

  7. Optionally configure tags. On the Review and create page, choose Create rule.

For more information about configuring rules, see Amazon EventBridge rules in the Amazon EventBridge User Guide.

Contact events data model

Contact events are generated in JSON. For each event type, a JSON blob is sent to the target of your choice, as configured in the rule. The following contact events are available:

  • AMD_DISABLED - Answering machine detection is disabled.

  • INITIATED - A voice call, chat, or task is initiated or transferred.

  • CONNECTED_TO_SYSTEM - The contact has established media (for example, it was answered by a person or by voicemail). This event is generated for any of the AnsweringMachineDetectionStatus codes.

    Note

    This event is generated for outbound calls (including Amazon Connect outbound campaigns) tasks, and chats.

  • CONTACT_DATA_UPDATED - One or more of the following contact properties were updated on a voice call, chat, or task: scheduled timestamp (task only), user-defined attributes and tags, routing criteria is updated or step is expired, and if Contact Lens is enabled for a given contact.

  • QUEUED - A voice call, chat, or task is queued to be assigned to an agent.

  • CONNECTED_TO_AGENT - A voice call, chat, or task is connected to an agent.

  • DISCONNECTED - A voice call, chat, or task is disconnected. For outbound calls, the dial attempt is not successful, the attempt is connected but the call is not picked up, or the attempt results in a SIT tone.

    A disconnect event is when:

    • A chat, or task is disconnected.

    • A task is disconnected as a result of a flow action.

    • A task expires. The task is automatically disconnected if it is not completed in 7 days.

  • PAUSED - An active task contact was paused.

  • RESUMED - A paused task contact was resumed.

AgentInfo

The AgentInfo object includes the following properties:

AgentArn

The Amazon Resource Name (ARN) for the agent account.

Type: ARN

HierarchyGroups

The agent hierarchy group for the agent.

Type: ARN

AttributeCondition

An object to specify the predefined attribute condition.

Name

The name of predefined attribute.

Type: String

Length: 1-64

Value

The value of predefined attribute.

Type: String

Length: 1-64

ComparisonOperator

The operator of the condition.

Type: String

Valid values: NumberGreaterOrEqualTo

ProficiencyLevel

The proficiency level of the condition.

Type: Float

Valid values: 1.0, 2.0, 3.0, 4.0 and 5.0

Campaign

Information associated with a campaign.

Type: Campaign object

Contact event

The Contact object includes the following properties:

ContactId

The identifier for the contact.

Type: String

Length: 1-256

InitialContactId

The identifier of the initial contact.

Type: String

Length: 1-256

RelatedContactId

The contactId that is related to this contact.

Type: String

Length: Minimum of 1. Maximum of 256.

PreviousContactId

The original identifier of the contact that was transferred.

Type: String

Length: 1-256

Channel

The type of channel.

Type: VOICE, CHAT, or TASK

InstanceArn

Amazon Resource Name (ARN) for the Amazon Connect instance in which the agent's user account is created.

Type: ARN

InitiationMethod

Indicates how the contact was initiated.

Valid values:

  • INBOUND: The customer initiated voice (phone) contact with your contact center.

  • OUTBOUND: Represents an agent-initiated outbound voice call from the Contact Control Panel (CCP). This initiation method calls the StartOutboundVoiceContact API.

  • TRANSFER: The contact was transferred by an agent to another agent or to a queue, using quick connects in the CCP. This results in a new contact record being created.

  • CALLBACK: The customer was contacted as part of a callback flow. For more information about the InitiationMethod in this scenario, see About queued callbacks in metrics.

  • API: The contact was initiated with Amazon Connect by API. This could be an outbound contact you created and queued to an agent, using the StartOutboundVoiceContact API, or it could be a live chat that was initiated by the customer with your contact center, where you called the StartChatContact API, or it could be a tasks initiated by the customer by calling the StartTaskContact API.

  • QUEUE_TRANSFER: While the contact is one queue, and was then transferred into another queue using a flow block.

  • EXTERNAL_OUTBOUND: An agent initiated voice (phone) contact with an external participant to your contact center using either quick connect in the CCP or a flow block.

  • MONITOR: A supervisor initiated monitor on an agent. The supervisor can silently monitor the agent and customer, or barge the conversation.

  • DISCONNECT: When a Set disconnect flow block is triggered, it specifies which flow to run after a disconnect event.

    A disconnect event is when:

    • A chat, or task is disconnected.

    • A task is disconnected as a result of a flow action.

    • A task expires. The task is automatically disconnected if it is not completed in 7 days.

    When the disconnect event occurs, the corresponding content flow runs. If a new contact is created while running a disconnect flow, then the initiation method for that new contact is DISCONNECT.

DisconnectReason code

Indicates how the contact was terminated. This is available for the contacts of outbound campaigns in which the media connection failed.

Valid values:

  • OUTBOUND_DESTINATION_ENDPOINT_ERROR: Current configurations do not allow this destination to be dialed (for example, calling an endpoint destination from an ineligible instance).

  • OUTBOUND_RESOURCE_ERROR: Instance has insufficient permissions to make outbound calls or necessary resources were not found.

  • OUTBOUND_ATTEMPT_FAILED: There was an unknown error, invalid parameter, or insufficient permissions to call the API.

  • EXPIRED: Not enough agents available, or not enough telecom capacity for such calls.

AnsweringMachineDetectionStatus

Indicates how an outbound campaign call is actually disposed if the contact is connected to Amazon Connect.

Type: String

Valid values:

  • HUMAN_ANSWERED: The number dialed was answered by a person.

  • VOICEMAIL_BEEP: The number dialed was answered by voicemail with a beep.

  • VOICEMAIL_NO_BEEP: The number dialed was answered by a voicemail with no beep.

  • AMD_UNANSWERED: The number dialed kept ringing, but the call was not picked up.

  • AMD_UNRESOLVED: The number dialed was connected but the answering machine detection could not determine whether the call was picked up by a person or voicemail.

  • AMD_NOT_APPLICABLE: The call disconnected before ringing, and there was no media to detect.

  • SIT_TONE_BUSY: The number dialed was busy

  • SIT_TONE_INVALID_NUMBER: The number dialed was not a valid number.

  • SIT_TONE_DETECTED: A special information tone (SIT) was detected.

  • FAX_MACHINE_DETECTED: A fax machine was detected.

  • AMD_ERROR: The number dialed was connected, but there was an error in answering machine detection.

EventType

The type of event published.

Type: String

Valid values: INITIATED, CONNECTED_TO_SYSTEM, CONTACT_DATA_UPDATED, QUEUED, CONNECTED_TO_AGENT, DISCONNECTED

UpdatedProperties

The type of property updated.

Type: String

Valid values: ScheduledTimestamp, UserDefinedAttributes, ContactLens.ConversationalAnalytics.Configuration, Tags

AgentInfo

The agent the contact was assigned to.

Type: AgentInfo object

QueueInfo

The queue the contact was placed in.

Type: QueueInfo object

ContactLens

Contact Lens information if Contact Lens is enabled on the flow.

Type: For more information about the ContactLens object, see the UpdateContactRecordingBehavior action in the Flow language section of the Amazon Connect API Reference.

SegmentAttributes

A set of system defined key-value pairs stored on individual contact segments using an attribute map. The attributes are standard Amazon Connect attributes and can be accessed in flows. Attribute keys can include only alphanumeric, -, and _ characters.

This field can be used to show channel subtype. For example, connect:Guide or connect:SMS.

Type: SegmentAttributes

Members: SegmentAttributeName, SegmentAttributeValue

Tags

Tags associated with the contact. This contains both AWS generated and user-defined tags.

Type: String to string map

CustomerVoiceActivity

The CustomerVoiceActivity object includes the following properties:

GreetingStartTimestamp

The date and time that measures the beginning of the customer greeting from an outbound voice call, in UTC time.

Type: String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

GreetingEndTimestamp

The date and time that measures the end of the customer greeting from an outbound voice call, in UTC time.

Type: String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

Expiry

An object to specify the expiration of a routing step.

DurationInSeconds

The number of seconds to wait before expiring the routing step.

Type: Integer

Min value: 0

ExpiryTimestamp

The timestamp indicating when the routing step expires.

Type: String (yyyy-mm-ddThh:mm:ssZ)

Expression

A tagged union to specify expression for a routing step.

AndExpression

List of routing expressions which will be AND-ed together.

Type: Expression

Min value: 0

OrExpression

List of routing expressions which will be OR-ed together.

Type: Expression

AttributeCondition

An object to specify the predefined attribute condition.

Type: AttributeCondition

QueueInfo

The QueueInfo object includes the following properties:

QueueArn

The Amazon Resource Name (ARN) for the queue.

Type: String

QueueType

The type of queue.

Type: String

RoutingCriteria

List of routing criteria. Each time the routing criteria is updated on a contact, it will be added to this list.

ActivationTimestamp

The timestamp indicating when the routing criteria is set to active. A routing criteria is activated when contact is transferred to a queue.

ActivationTimestamp will be set on routing criteria for contacts in agent queue even though Routing criteria is never activated for contacts in agent queue.

Type: String (yyyy-mm-ddThh:mm:ssZ)

Index

Information about the index of the routing criteria.

Type: Integer

Min value: 0

Steps

List of routing steps.

Type: List of Step objects

Length: 1-5

Steps

When Amazon Connect does not find an available agent meeting the requirements in a step for a given step duration, the routing criteria will move on to the next step sequentially until a join is completed with an agent. When all steps are exhausted, the contact will be offered to any agent in the queue.

Status

Represents status of the Routing step.

Type: String

Valid Values: EXPIRED, ACTIVE, JOINED, INACTIVE, DEACTIVATED, INTERRUPTED

Expression

An object to specify the expression of a routing step..

Type: Expression

Expiry

An object to specify the expiration of a routing step.

Type: Expiry

Contact timestamps

InitiationTimestamp

The date and time this contact was initiated, in UTC time.

Type: String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

ConnectedToSystemTimestamp

The date and time the customer endpoint connected to Amazon Connect, in UTC time.

EnqueueTimestamp

The date and time the contact was added to the queue, in UTC time.

Type: String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

ConnectedToAgentTimestamp

The date and time the contact was connected to the agent, in UTC time.

Type: String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

DisconnectTimestamp

The date and time that the customer endpoint disconnected from Amazon Connect, in UTC time

Type: String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

ScheduledTimestamp

The date and time when this contact was scheduled to trigger the flow to run, in UTC time. This is supported only for the task channel.

Type: String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

GreetingStartTimestamp

The date and time that measures the beginning of the customer greeting from an outbound voice call, in UTC time.

Type: String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

GreetingEndTimestamp

The date and time that measures the end of the customer greeting from an outbound voice call, in UTC time.

Type: String (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

Sample to stop streaming an event type

The following sample shows how to stop streaming a CONTACT_DATA_UPDATED event from Amazon Connect to EventBridge.

{ "source": ["aws.connect"], "detail-type": ["Amazon Connect Contact Event"], "detail": { "eventType": [{ "anything-but": ["CONTACT_DATA_UPDATED"] }] }

Sample contact event for when a voice call is connected to an agent

{ "version": "0", "id": "abcabcab-abca-abca-abca-abcabcabcabc", "detail-type": "Amazon Connect Contact Event", "source": "aws.connect", "account": "111122223333", "time": "2021-08-04T17:43:48Z", "region": "your-region", "resources": [ "arn:aws:...", "contactArn", "instanceArn" ], "detail": { "initiationTimestamp":"2021-08-04T17:17:53.000Z", "contactId":"11111111-1111-1111-1111-111111111111", "channel":"VOICE", "instanceArn":"arn:aws::connect:your-region:123456789012:instance/12345678-1234-1234-1234-123456789012", "initiationMethod":"INBOUND", "eventType":"CONNECTED_TO_AGENT", "agentInfo":{ "agentArn":"arn:aws::connect:your-region:123456789012:instance/12345678-1234-1234-1234-123456789012/agent/12345678-1234-1234-1234-123456789012", "connectedToAgentTimestamp":"2021-08-04T17:29:09.000Z", "hierarchyGroups": { "level1": { "arn": "arn:aws:connect:your-region:012345678901:instance/12345678-1234-1234-1234-123456789012/agent-group/abcdefgh-1234-1234-1234-12345678901a", }, "level2": { "arn": "arn:aws:connect:your-region:012345678901:instance/12345678-1234-1234-1234-123456789012/agent-group/abcdefgh-1234-1234-1234-12345678901b", }, "level3": { "arn": "arn:aws:connect:your-region:012345678901:instance/12345678-1234-1234-1234-123456789012/agent-group/abcdefgh-1234-1234-1234-12345678901c", }, "level4": { "arn": "arn:aws:connect:your-region:012345678901:instance/12345678-1234-1234-1234-123456789012/agent-group/abcdefgh-1234-1234-1234-12345678901d", }, "level5": { "arn": "arn:aws:connect:your-region:012345678901:instance/12345678-1234-1234-1234-123456789012/agent-group/abcdefgh-1234-1234-1234-12345678901e", } } } }, "queueInfo": { "queueType":"type", "queueArn":"arn:aws::connect:your-region:123456789012:instance/12345678-1234-1234-1234-123456789012/queue/12345678-1234-1234-1234-123456789012", "enqueueTimestamp":"2021-08-04T17:29:04.000Z" }, "tags": { "aws:connect:instanceId":"12345678-1234-1234-1234-123456789012", "aws:connect:systemEndpoint":"+11234567890" } } }

Sample contact event for when a voice call is disconnected

The following sample event shows a contact that has a user-defined tag with Dept as the key. Note that queueInfo is not included in events received by EventBridge when initiationMethod is OUTBOUND.

{ "version": "0", "id": "the event ID", "detail-type": "Amazon Connect Contact Event", "source": "aws.connect", "account": "111122223333", "time": "2021-08-04T17:43:48Z", "region": "your-region", "resources": [ "arn:aws:...", "contactArn", "instanceArn" ], "detail": { "eventType": "DISCONNECTED", "contactId": "11111111-1111-1111-1111-111111111111", "initialContactId": "11111111-2222-3333-4444-555555555555", "previousContactId": "11111111-2222-3333-4444-555555555555", "channel": "Voice", "instanceArn": "arn:aws::connect:your-region:123456789012:instance/12345678-1234-1234-1234-123456789012", "initiationMethod": "OUTBOUND", "initiationTimestamp":"2021-08-04T17:17:53.000Z", "connectedToSystemTimestamp":"2021-08-04T17:17:55.000Z", "disconnectTimestamp":"2021-08-04T17:18:37.000Z", "agentInfo": { "agentArn": "arn", "connectedToAgentTimestamp":"2021-08-04T17:29:09.000Z", "hierarchyGroups": { "level1": { "arn": "arn:aws:connect:your-region:012345678901:instance/12345678-1234-1234-1234-123456789012/agent-group/abcdefgh-1234-1234-1234-12345678901a", }, "level2": { "arn": "arn:aws:connect:your-region:012345678901:instance/12345678-1234-1234-1234-123456789012/agent-group/abcdefgh-1234-1234-1234-12345678901b", }, "level3": { "arn": "arn:aws:connect:your-region:012345678901:instance/12345678-1234-1234-1234-123456789012/agent-group/abcdefgh-1234-1234-1234-12345678901c", }, "level4": { "arn": "arn:aws:connect:your-region:012345678901:instance/12345678-1234-1234-1234-123456789012/agent-group/abcdefgh-1234-1234-1234-12345678901d", }, "level5": { "arn": "arn:aws:connect:your-region:012345678901:instance/12345678-1234-1234-1234-123456789012/agent-group/abcdefgh-1234-1234-1234-12345678901e", } } }, "CustomerVoiceActivity": { "greetingStartTimestamp":"2021-08-04T17:29:20.000Z", "greetingEndTimestamp":"2021-08-04T17:29:22.000Z", }, "tags": { "aws:connect:instanceId":"12345678-1234-1234-1234-123456789012", "aws:connect:systemEndpoint":"+11234567890", "Dept":"Finance" } } }

Sample event for when contact properties are updated

{ "version": "0", "id": "the event ID", "detail-type": "Amazon Connect Contact Event", "source": "aws.connect", "account": "the account ID", "time": "2021-08-04T17:43:48Z", "region": "your-region", "resources": [ "arn:aws:...", "contactArn", "instanceArn" ], "detail": { "eventType": "CONTACT_DATA_UPDATED", "contactId": "the contact ID", "channel": "CHAT", "instanceArn": "arn:aws:connect:us-west-2:the account ID:instance/the instance ID", "initiationMethod": "API", "queueInfo": { "queueArn": "arn:aws:connect:us-west-2:the account ID:instance/the instance ID/queue/the queue ID", "enqueueTimestamp": "2023-10-24T02:39:15.240Z", "queueType": "STANDARD" }, "agentInfo": { "agentArn": "arn:aws:connect:us-west-2:the account ID:instance/the instance ID/agent/the agent ID", "connectedToAgentTimestamp": "1970-01-01T00:00:00.001Z", "hierarchyGroups": { "level1": { "arn": "arn:aws:connect:us-west-2:the account ID:instance/the instance ID/agent-group/the agent group ID" }, "level2": { "arn": "arn:aws:connect:us-west-2:the account ID:instance/the instance ID/agent-group/the agent group ID" }, "level3": { "arn": "arn:aws:connect:us-west-2:the account ID:instance/the instance ID/agent-group/the agent group ID" }, "level4": { "arn": "arn:aws:connect:us-west-2:the account ID:instance/the instance ID/agent-group/the agent group ID" } } }, "updatedProperties": ["ContactLens.ConversationalAnalytics.Configuration"], "initiationTimestamp": "2023-10-24T02:39:15.154Z", "connectedToSystemTimestamp": "1970-01-01T00:00:00.001Z", "tags": { "aws:connect:instanceId": "the instance ID" }, "contactLens": { "conversationalAnalytics": { "configuration": { "enabled": true, "channelConfiguration": { "analyticsModes": ["PostContact"] }, "languageLocale": "en-US", "redactionConfiguration": { "behavior": "Enable", "policy": "RedactedAndOriginal", "entities": ["EMAIL"], "maskMode": "EntityType" } } } } } }

Sample contact event for when a voice call is connected to an agent using routing criteria

{ "version": "0", "id": "abcabcab-abca-abca-abca-abcabcabcabc", "detail-type": "Amazon Connect Contact Event", "source": "aws.connect", "account": "111122223333", "time": "2021-08-04T17:43:48Z", "region": "your-region", "resources": [ "arn:aws:...", "contactArn", "instanceArn" ], "detail": { "ContactId": "12345678-1234-1234-1234-123456789012", "Channel": "VOICE", "InstanceArn": "arn:aws::connect:us-west-2:123456789012:instance/12345678-1234-1234-1234-123456789012", "InitiationMethod": "INBOUND", "EventType": "CONNECTED_TO_AGENT", "AgentInfo": { "AgentArn": "arn:aws::connect:us-west-2:123456789012:instance/12345678-1234-1234-1234-123456789012/agent/12345678-1234-1234-1234-123456789012", "ConnectedToAgentTimestamp": "2021-08-04T17:29:09.000Z" }, "QueueInfo": { "QueueType": "type", "QueueArn": "arn:aws::connect:us-west-2:123456789012:instance/12345678-1234-1234-1234-123456789012/queue/12345678-1234-1234-1234-123456789012", "EnqueueTimestamp": "2021-08-04T17:29:04.000Z" }, "tags": { "aws:connect:instanceId":"12345678-1234-1234-1234-123456789012", "aws:connect:systemEndpoint":"+11234567890" }, "RoutingCriteria": [{ "ActivationTimestamp": "2021-08-04T17:29:04.000Z", "Index": 0, "Steps": [{ "Status": "JOINED", "Expiry": { "DurationInSeconds": 60, }, "Expression": { "OrExpression": [{ "AttributeCondition": { "Name": "Technology", "ComparisonOperator": "NumberGreaterOrEqualTo", "ProficiencyLevel": 2.0, "Value": "AWS Kinesis" } }, { "AttributeCondition": { "Name": "Language", "ComparisonOperator": "NumberGreaterOrEqualTo", "ProficiencyLevel": 4.0, "Value": "English" } }], "AndExpression": [{ "AttributeCondition": { "Name": "Language", "ComparisonOperator": "NumberGreaterOrEqualTo", "ProficiencyLevel": 2.0, "Value": "Spanish" } }] } }] }] } }

Sample event for when routing step expires on a contact

{ "version": "0", "id": "the event ID", "detail-type": "Amazon Connect Contact Event", "source": "aws.connect", "account": "the account ID", "time": "2021-08-04T17:43:48Z", "region": "your-region", "resources": [ "arn:aws:...", "contactArn", "instanceArn" ], "detail": { "eventType":"CONTACT_DATA_UPDATED", "contactId":"12345678-1234-1234-1234-123456789012", "channel":"CHAT", "instanceArn":"arn:aws::connect:us-west-2:123456789012:instance/12345678-1234-1234-1234-123456789012", "initiationMethod":"API", "queueInfo":{ "queueArn":"arn:aws:connect:us-west-2:123456789012:instance/12345678-1234-1234-1234-123456789012/queue/12345678-1234-1234-1234-123456789012", "enqueueTimestamp":"2023-11-01T18:33:03.062Z", "queueType":"STANDARD" }, "updatedProperties":["RoutingCriteria.Step.Status"], "initiationTimestamp":"2023-11-01T18:33:00.716Z", "connectedToSystemTimestamp":"2023-11-01T18:33:01.736Z", "tags":{ "aws:connect:instanceId":"12345678-1234-1234-1234-123456789012" }, "routingCriteria":{ "steps":[{ "expiry":{ "durationInSeconds":50, "expiryTimestamp":"2023-11-01T18:34:54.275Z" }, "expression":{ "attributeCondition":{ "name":"Location", "value":"AZ", "proficiencyLevel":3.0, "comparisonOperator":"NumberGreaterOrEqualTo" } }, "status":"EXPIRED" }, { "expiry":{ "durationInSeconds":10 }, "expression":{ "attributeCondition":{ "name":"Language", "value":"Spanish", "proficiencyLevel":4.0, "comparisonOperator":"NumberGreaterOrEqualTo" } }, "status":"ACTIVE" }, { "expression":{ "attributeCondition":{ "name":"Language", "value":"Spanish", "proficiencyLevel":1.0, "comparisonOperator":"NumberGreaterOrEqualTo" } }, "status":"INACTIVE" }], "activationTimestamp":"2023-11-01T18:34:04.275Z", "index":1 } } }