Interaction Event Feeds Reference Guide

Overview

In Symbee Connect, data about user usage and contact center interactions can be optionally configured to be sent to Amazon Kinesis Streams in your account. This is configured through the Symbee Connect Administration Portal. See here.

The data is separated into the following 4 types of events:

EVENT TYPE	DESCRIPTION
Interaction Events	An event for each Interaction (Voice, Webchat, SMS, Email, Preview, etc.) handled by an Agent, created once the Agent has concluded the interaction (after Wrap is complete).
Work Code Types	Events, associated with Interaction events above – one for each Work Code selected by the agent (if you have Work Codes enabled) for the interaction.
User Events	Basic events for each Symbee Connect user, denoting user Login, user Logout, and Heartbeat events during their login session.
Extended Agent Events	For Omnichannel enabled Agents, an event for every agent state change, including (when in a WORKING or WRAP state) the Interactions currently being worked.

These events can be the basis of custom integrations via Amazon Kinesis and Lambda to your back end systems if needed, or custom reporting, and are also used by some other optional Symbee Connect features (like Interaction Search).

These events are also consumed by the Symbee Connect Business Intelligence solution.

The Symbee Connect Data Feeds and Reporting CloudFormation AWS CloudFormation template (downloaded through the Administration Portal) automates the setup of these event feeds into your AWS Account by establishing:

An Amazon Kinesis Stream for each event type
An associated Amazon Kinesis Firehose attached to each respective Kinesis Stream that saves a copy of each event delivered to an S3 Bucket (see next)
An Amazon S3 Bucket for reporting event retention (name starting with sc_reporting) where a copy of each event is saved for your retention purposes (you can set up S3 retention policies to either keep or purge the data based on your needs)

The following diagram depicts the resources established by the Symbee Connect Data Feeds and Reporting CloudFormation:

Enabling Symbee Connect Data Event Feeds

Within your Symbee Connect account you can configure multiple Environments if you have multiple Amazon Connect instances. When you enable the Event Feeds, they are enabled on a per-environment basis.

Refer to Enabling Reporting and Event Data Feeds for a Step by Step on downloading and running the Symbee Connect Data Feeds and Reporting CloudFormation.

Interaction Events - General Formatting

The following sections describe the data within each type of event.

All events published on the Symbee Connect Data Feeds and Reporting Kinesis Streams have the following common characteristics:

All events are published to Amazon Kinesis in JSON (JavaScript Object Notation) format. Examples of each event JSON are provided in the respective following sections
All JSON event types have a common property named ActivityType that indicates the type of event it is. For example:

"ActivityType": "INTERACTION_TRACE_RECORD",

This is to support having a single Lambda capable of handling multiple Symbee Connect event types to be attached to multiple Streams.

The possible ActivityType values are currently:
- INTERACTION_TRACE_RECORD
- WORK_CODES
- USER_USAGE
- EXTENDED_AGENT_EVENTS
All date/time value fields are always represented as UTC (Universal Coordinated Time) values
All duration value fields are represented as milliseconds, unless otherwise specified

Data Description - Interaction Events

When enabled, Interaction Events, one for each call or task, are published at the conclusion of every interaction (Voice, Webchat, SMS, Email, Preview, etc.) handled by an Agent, and are published shortly after the Agent has concluded the interaction (after Wrap is complete).

Throughout documentation Interactions can also be referred to as Tasks. The terms Interaction and Task are synonymous, unless otherwise stated.

For Amazon native Interactions (Voice, Amazon Delivered Chat, and Generic Tasks) interactions, Amazon Connect will publish an Amazon Connect CTR record to Kinesis with complete details of all calls, chats and tasks (normal Amazon Connect behavior), whether they are handled by an agent or not. If the Amazon delivered Voice call, Chat, or Task was handled by a Symbee Connect enabled agent, Symbee Connect will also publish a pairing Interaction Event for the same contact/interaction.

The Symbee Connect Interaction feed then additionally publishes events for all other omnichannel interaction types beyond voice (chats, emails, etc.) that were not delivered through Amazon Connect.

Event Example

{
    "ActivityType": "INTERACTION_TRACE_RECORD",
    "TaskId": "32628905-a1bd-4d7b-977d-9ae4b500b086",
    "PlatformId": "AWS Connect",
    "CompanyId": "abccompany",
    "Environment": "prod",
    "OriginTaskId": "",
    "GatewayTaskId": "9e108fff-f369-4921-87fe-7d1656006dd4",
    "OriginGatewayTaskId": "",
    "TaskType": "WEBCHAT",
    "TaskInitiationMethod": "INBOUND_QUEUE",
    "DeliveryProvider": "SYMBEE"
    "GatewayWorkHandle": "482",
    "Username": "cmiller",
    "UserReportHierarchy": "MidWest|Servicing|GTocata",
    "SkillQueueName": "custservice-webchat",
    "FarEndAddress": "John Smith",
    "NearEndAddress": "",
    "TransferredToAddress": "",
    "MediaLocation": "sc-reporting-prod-999123456789/ChatTranscripts/2019/02/28/9e108fff-f369-4921-87fe-7d1656006dd4",
    "MediaLocationType": "S3",
    "InitiationTimestamp": "2019-02-28T01:04:48Z",
    "QueuedTimestamp": "2019-02-28T01:04:48Z",
    "AssignedTimestamp": "2019-02-28T01:04:50Z",
    "ConnectedTimestamp": "2019-02-28T01:04:52Z"
    "WrapTimestamp": "2019-02-28T01:05:43Z",
    "CompletedTimestamp": "2019-02-28T01:05:54Z",
    "QueuedDurationInMillis": 1934,
    "ActiveDurationInMillis": 48674,
    "ParkedDurationInMillis": 0,
    "WrapDurationInMillis": 11215,
    "Attributes": {
        "Email": "jsmith@gmail.com",
        "Phone": "5551232100",
        "FullName": "John Smith"
        "SubscriberId": "001619723”
    }
}

Event Field Descriptions

ActivityType

See [Interaction Events - General Formatting

PlatformId

Will always contain a value of "AWS Connect".

CompanyId, Environment

Your Symbee Connect Company Alias and Environment.

TaskType

The type of Interaction or Task described by this event. Currently valid values are:

VOICE
EMAIL
ROUTED_EMAIL
WEBCHAT
SMS
SMS_PINPOINT
SMS_WEBHOOK
PREVIEW_DIAL
SOCIAL_WHATSAPP
SOCIAL_LINE
SOCIAL_FBMESSENGER
SOCIAL_TWITTERDM
SOCIAL_OTHER
INSTANT_MESSAGE
UC_CALL
GENERIC_TASK

TaskInitiationMethod

Indicates the direction and style of how the task originated. Currently valid values are:

INBOUND_FORCED : Inbound contact assigned/dictated by Amazon Connect
INBOUND_QUEUE : Inbound interaction queued and routed through the Symbee Connect ACD
OUTBOUND_FORCED ; Outbound contact initiated by the user through an Amazon Connect channel
OUTBOUND_REQUESTED : Outbound interaction initiated via a Symbee Connect delivered channel
OUTBOUND_AUTO : Outbound initiated via external system (e.g. Dialer) and agent-less (self service)
OUTBOUND_AUTO_AGENT : Outbound initiated via external system (e.g. Dialer) and delivered to Agent
BRIDGE : Inbound (Chime delivered) call that was immediately bridged with another external party)
FORWARD : Inbound (Chime delivered) call that was immediately forwarded to another external party)

DeliveryProvider

The distribution engine used to route, queue, and deliver the task. Currently used values are SYMBEE, AMAZON, and SMARTDIAL.

TaskId

The unique identifier of the task within Symbee Connect.

OriginTaskId

If the task was transferred or initiated as a direct result of another associated Task, the Id of the previous task that originated this task. Otherwise will be empty-string (“”).

GatewayTaskId

The unique identifier of the interaction within the respective back-end Symbee Connect Task Gateway (based on TaskType) that this task represents. For Voice interactions (and other Amazon Connect delivered tasks – for example Amazon-Delivered Chats and Generic Tasks), this value is guaranteed to match the ContactId value reported in the Amazon Connect Contact Trace Record (CTR) for the same call.

OriginGatewayTaskId

If the task was transferred or initiated as a direct result of another associated Task, the back-end Symbee Connect Task Gateway unique identifier of the previous task that originated this task. Otherwise will be empty-string (“”).

Username

The user-identifier of the Agent the task was assigned to. This value is guaranteed to match the Username value reported in Amazon Connect Contact Trace Records (CTR’s) for Amazon Connect delivered contacts. An event with no username defined (“”) indicates the interaction was either automated, or did not progress enough to reach agent assignment.

UserReportHierarchy

If you have configured a User Reporting Hierarchy in Symbee Connect and the user identified in Username is assigned the hierarchy, this is a pipe-delimited string representing the reporting hierarchy for the user. Otherwise will be empty-string (“”).

SkillQueueName

Identifies the SkillQueue the Task was queued, routed, and assigned through.

For Voice interactions (and other Amazon Connect delivered tasks – for example Amazon-Delivered Chats and Generic Tasks) this value will match the Queue Identifier configured in Amazon Connect.

For Voice interactions initiated via Enghouse SmartDial, this value will contain the SmartDial List Name the call was initiated from.

For all other omnichannel task types, this is the SkillQueue Id configured within Symbee Connect.

FarEndAddress

The identifier of the far end customer party associated with the Task. For Voice tasks, this will be the callers ANI or Calling Party Number. For SMS tasks, this will be the customers subscriber number (mobile phone number). For Webchats this will be the collected “Name” of the customer or user requesting the Webchat. For Emails this will be the customers email address.

NearEndAddress

For Voice tasks, this will be the Dialed Number or DNIS. For SMS tasks this will be the SMS short-code or long-code (phone number) the customer initialed texted to start the conversation. For Emails, this will be the email address the customer originally sent the email into. Not relevant for some Task Types – if irrelevant will be empty-string (“”).

TransferredToAddress

If the task did not result in a transfer this will be empty-string (“”). A non-empty value indicates the task resulted in being transferred – the value indicating where the call was transferred to.

MediaLocation

Not relevant for some Task Types – if irrelevant will be empty-string (“”). For chat type tasks (e.g. Webchat’s, SMS, Social messaging), if Chat Transcripts has been enabled (see section 2), this will contain the location of the transcript for the chat. (Refer to Appendix A – Chat Transcript for an example of a Chat Transcript)

MediaLocationType

If MediaLocation contains a value, indicates the type of location. Current valid values are “S3” indicating an Amazon S3 bucket name and associated S3 object path.

InitiationTimestamp

The date/time (in UTC) the task first became known to Symbee Connect.

QueuedTimestamp

For tasks not delivered through Amazon Connect, the date/time (in UTC) the task first entered the Symbee Connect SkillQueue.

AssignedTimestamp

The date/time (in UTC) the task first delivered to the Agent.

ConnectedTimestamp

A date/time (in UTC).

For automatically Initiated tasks (TaskInitiationMethod of OUTBOUND_AUTO or OUTBOUND_AUTO_AGENT), the time the automated system connected with the customer
For all other tasks, the time the user accepted and was connected with the far end party

WrapTimestamp

The date/time (in UTC) the task entered the wrap (often known as After Contact Work or ACW) state.

CompletedTimestamp

The date/time (in UTC) the task completed ended (after any wrap time is completed).

QueuedDurationInMillis

The duration in milliseconds the task was in the queued state prior to being assigned to an agent. For voice tasks this value will always be zero. Refer to the Amazon Connect CTR if you require total queued time for Voice calls.

ActiveDurationInMillis, WrapDurationInMillis, ParkedDurationInMillis

The Active, Wrap, and Parked durations are all millisecond values and combined provide the total time the agent worked the task. If Symbee Connect multiple-task-handling is configured, an agent can be working multiple tasks at the same time but only 1 task can ever be the “focus” task. A task is in the parked state and clocks time against the parked duration if it is in the background, rather than clocking time against either the active or in wrap duration.

Attributes

Attributes are optional, and if none are present Attributes will be null. If present Attributes contains a map of key / value pairs. For voice tasks, Attributes will contain any user-defined Contact Attribute values initially set during Amazon Connect Contact Flows prior to the call being delivered to the agent. For Webchat tasks, Attributes will contain the names and collected values from any configured pre-chat survey form fields.

Data Description - Work Code Events

When enabled, Work Code Events, one for each work code selected by an agent for a task, are published at the conclusion of each interaction being handled by the Agent and are published shortly after the Agent has concluded the interaction (after Wrap is complete).

Work Code events are always associated with interaction tasks, with the association being zero to many – a task may not have any associated work code events (if work codes aren’t configured or are not selected), or a single task may result in multiple work code events (if multiple codes are selected for the task – 1 event for each).

Work Codes can be used with both voice tasks (Amazon Connect phone calls) as well as non-voice omnichannel task types (chats, emails, etc.). For work code events associated with voice tasks, the GatewayTaskId field value will match the ContactId value in the Amazon Contact Trace Record (CTR).

Event Example

{
    "ActivityType": "WORK_CODES",
    "PlatformId": "AWS Connect",
    "CompanyId": "abccompany",
    "Environment": "prod",
    "WorkGroupName": "Chat",
    "WorkGroupDescription": "Chat",
    "WorkCodeName": "Password Change",
    "WorkCodeDescription": "Password Change",
    "Username": "cmiller",
    "UserReportHierarchy": "MidWest|Servicing|GTocata",
    "QueueName": "custservice-webchat",
    "CreatedDate": "2019-02-28T09:04:30Z",
    "GatewayTaskId": "c7d7cf6a-7136-4310-9798-5c27754cfb08",
    "TaskType": "WEBCHAT"
}

Event Field Descriptions

ActivityType

See Interaction Events - General Formatting

PlatformId, CompanyId, Environment

Your Symbee Connect Company Alias and Environment.

TaskType

The type of Interaction the work code event is related to. Currently valid values are:

VOICE
EMAIL
ROUTED_EMAIL
WEBCHAT
SMS
SMS_PINPOINT
SMS_WEBHOOK
PREVIEW_DIAL
SOCIAL_WHATSAPP
SOCIAL_LINE
SOCIAL_FBMESSENGER
SOCIAL_TWITTERDM
SOCIAL_OTHER
INSTANT_MESSAGE
UC_CALL
GENERIC_TASK

GatewayTaskId

The unique identifier of the interaction within the respective back-end Symbee Connect Task Gateway (based on TaskType) that this saved Work Code is associated with. For Voice Tasks, this value is guaranteed to match the ContactId value reported in the Amazon Connect Contact Trace Record (CTR) for the same call. This will match the value of the GatewayTaskId reported in the Interaction Event.

QueueName

The SkillQueue code the Task associated with the saved work code was queued, routed, and assigned through. For Voice Tasks this value will match the Queue Identifier configured in Amazon Connect. For all other omnichannel task types, this is the SkillQueue Id configured within Symbee Connect.

WorkGroupName

Work Codes are configured in Work Code Groups within Symbee Connect. A string containing the name of the Work Code Group the saved work code is within.

WorkGroupDescription

The description of the Work Code Group the saved work code is within.

WorkCodeName

The name of the work code.

WorkCodeDescription

The description of the saved work code.

Username

The user-identifier of the Agent handling the task associated with this work code. This value is guaranteed to match the Username value reported in Amazon Connect Contact Trace Records (CTR’s).

UserReportHierarchy

CreatedDate

The date/time (in UTC) the work code was saved.

Data Description - User Usage Events

When enabled, User Usage Events are published that denote basic user login and user logout activity, and heartbeat events throughout the duration of a user’s logged in session.

Event Example

{
    "ActivityType": "USER_USAGE",
    "UsageEntryTime": "2019-02-28T01:06:01Z",
    "PlatformId": "AWS Connect",
    "CompanyId": "abccompany",
    "Environment": "prod",
    "ProductId": "SymbeeEngage",
    "Username": "cmiller",
    "UserReportHierarchy": "MidWest|Servicing|GTocata",
    "UsageActionCode": "BEGIN",
}

Event Field Descriptions

ActivityType

See Interaction Events - General Formatting

PlatformId, CompanyId, Environment

Your Symbee Connect Company Alias and Environment.

ProductId

The ID or the AWS Marketplace Product this usage will be metered against.

UsageEntryTime

The date/time (in UTC) the user usage event occurred.

Username

The identifier of the user the usage event is associated with. This value is guaranteed to match the Username value reported in Amazon Connect Contact Trace Records (CTR’s).

UserReportHierarchy

UsageActionCode

The action being reported by this user usage event (either BEGIN, ALIVE, or END). A BEGIN event denotes a user login, END denotes user logout, and ALIVE events are published periodically throught the user’s login session.

Data Description - Extended Agent Events

When enabled, Extended Agent Events are published for every Symbee Connect Omnichannel-enabled agent, for every agent state change that occurs.

Each event reports the state transition type, which can be one of the following:

Each event reports the state transition type, which can be one of the following (most events being of type STATE_CHANGE):

LOGIN
LOGOUT
STATE_CHANGE
TIMEOUT

Each STATE_CHANGE transition event reports details of the current state being transitioned to, the previous state that was transitioned from, and the duration of time between the two states (see the PreviousStateDurationMS field description below).

Additionally, if either of the states reported is a “working” state, details of the currently in-focus task at that point are also reported.

Event Example

{
    "ActivityType": "EXTENDED_AGENT_EVENTS",
    "PlatformId": "AWS Connect",
    "CompanyId": "abccompany",
    "Environment": "prod",
    "Username": "cmiller",
    "UserReportHierarchy": "MidWest|Servicing|GTocata",
    "AgentSessionId": "5ee2141b-035c-4fe3-b4b9-2e455e2be13c",
    "EventType": "STATE_CHANGE",
    "CurrentState": "WRAP",
    "CurrentStateReason": "",
    "CurrentStateTimestamp": "2019-02-28T23:06:10Z",
    "CurrentTaskCount": 1,
    "CurrentFocusTaskId": "8e422782-faf5-4679-9823-787011f5653f",
    "CurrentFocusGatewayTaskId": "567f9838-e81f-4a9b-b627-2af9914d4dd9",
    "CurrentFocusTaskType": "WEBCHAT",
    "CurrentFocusTaskInitMethod": "INBOUND_QUEUE",
    "CurrentFocusTaskState": "WRAP",
    "PreviousState": "WORKING",
    "PreviousStateReason": "",
    "PreviousStateTimestamp": "2019-02-28T23:03:52Z",
    "PreviousStateDurationMS": 138024,
    "PreviousTaskCount": 1,
    "PreviousFocusTaskId": "8e422782-faf5-4679-9823-787011f5653f",
    "PreviousFocusGatewayTaskId": "567f9838-e81f-4a9b-b627-2af9914d4dd9",
    "PreviousFocusTaskType": "WEBCHAT",
    "PreviousFocusTaskInitMethod": "INBOUND_QUEUE",
    "PreviousFocusTaskState": "ACTIVE"
}

Event Field Descriptions

ActivityType

See Interaction Events - General Formatting

PlatformId, CompanyId, Environment

Your Symbee Connect Company Alias and Environment.

Username

The identifier of the user the extended agent event is associated with. This value is guaranteed to match the Username value reported in Amazon Connect Contact Trace Records (CTR’s).

UserReportHierarchy

AgentSessionId

A unique identifier denoting the associated agent’s login session.

EventType

The type of state transition being reported. Valid values are:

LOGIN
LOGOUT
STATE_CHANGE
TIMEOUT

CurrentState

The current agent state just transitioned to. Valid values are:

UNKNOWN
UNAVAILABLE
IDLE
RESERVING
RESERVED
WORKING
WRAP
PENDING_UNAVAILABLE
LOGGED_OFF

CurrentStateReason

If CurrentState is either UNAVAILABLE or PENDING_UNAVAILABLE, the associated unavailable reason (e.g. Break, Lunch, Meeting, etc.). Unavailable reasons match Agent Status’s configured within Amazon Connect.

CurrentStateTimestamp

The date/time (in UTC) of the agent transition to the reported current state.

CurrentTaskCount

The number of tasks currently assigned to the agent at the time of the state transition being reported.

CurrentFocusTaskId

The unique Identifier of the currently in-focus task within Symbee Connect at the time the transition is being reported.

CurrentFocusGatewayTaskId

The unique identifier of the task within the respective back-end Symbee Connect Task Gateway (based on TaskType) for the currently in-focus task. For Voice Tasks, this value is guaranteed to match the ContactId value reported in the Amazon Connect Contact Trace Record (CTR) for the same call.

CurrentFocusTaskType

The type of the currently in-focus task. Currently valid values are:

VOICE
EMAIL
ROUTED_EMAIL
WEBCHAT
SMS
SMS_PINPOINT
SMS_WEBHOOK
PREVIEW_DIAL
SOCIAL_WHATSAPP
SOCIAL_LINE
SOCIAL_FBMESSENGER
SOCIAL_TWITTERDM
SOCIAL_OTHER
INSTANT_MESSAGE
UC_CALL
GENERIC_TASK

CurrentFocusTaskInitMethod

The direction and style of the currently in-focus task. Currently valid values are:

INBOUND_FORCED
INBOUND_QUEUE
OUTBOUND_FORCED
OUTBOUND_REQUESTED
OUTBOUND_AUTO
OUTBOUND_AUTO_AGENT

CurrentFocusTaskState

The state of the currently in-focus task. Valid values are:

ALERTING
ACTIVE
WRAP
PARKED

PreviousState, PreviousStateReason, PreviousStateTimestamp, PreviousTaskCount, PreviousFocusTaskId, PreviousFocusGatewayTaskId, PreviousFocusTaskType, PreviousFocusTaskInitMethod, PreviousFocusTaskState

All the Previous… fields contain the same types of values described for the equivalent Current… fields above, except they represent the previous agent state that was being transitioned from.

PreviousStateDurationMS

The duration of time in milliseconds between the previous state, and the current state being reported.

Chat Transcripts

If Chat transcripts are enabled (see Section 2, step 4), when each Interaction Event (refer to Section 4) is generated, if the Interaction is one of the Chat types (WEBCHAT, SMS, INSTANT_MESSAGE, or SOCIAL), the resulting Interaction Event will have its MediaLocation attributes referencing an S3 bucket location of where the associated Chat Transcript was saved.

Symbee Connect Chat Transcripts are saved to S3 in JSON (JavaScript Object Notation) format. Each transcript is stored in a separate S3 object/file.

Chat Transcript Example

{
    "ActivityType": "CHAT_TRANSCRIPT",
    "SessionId": "de04e5ec-81ae-4046-b5d8-a1c42b6f1af3",
    "Transcript": [
    {
        "Member": "Johnny Customer",
        "Timestamp": "2019-05-01 00:46:06",
        "Direction": "Inbound",
        "Message": "Hi, can I get my password reset please?"
    },
    {
        "Member": "Sandy",
        "Timestamp": "2019-05-01 00:46:15",
        "Direction": "Outbound",
        "Message": "Hi, you are chatting with Sandy."
    },
    {
        "Member": "Sandy",
        "Timestamp": "2019-05-01 00:46:25",
        "Direction": "Outbound",
        "Message": "I see you are looking for a password reset. No problem."
    },
    {
        "Member": "Sandy",
        "Timestamp": "2019-05-01 00:46:34",
        "Direction": "Outbound",
        "Message": "What is your User Id?"
    },
    {
        "Member": "Johnny Customer",
        "Timestamp": "2019-05-01 00:46:46",
        "Direction": "Inbound",
        "Message": "jcustomer1"
    },
    {
        "Member": "Sandy",
        "Timestamp": "2019-05-01 00:47:31",
        "Direction": "Outbound",
        "Message": "Ok. Password is reset, your one-time code is: 128751. Please try it now."
    },
    {
        "Member": "Johnny Customer",
        "Timestamp": "2019-05-01 00:48:48",
        "Direction": "Inbound",
        "Message": "Perfect. Thank you!"
    }, 
    {
        "Member": "Sandy",
        "Timestamp": "2019-05-01 00:48:55",
        "Direction": "Outbound",
        "Message": "No problem. Is there anything else I can assist with?"
    },
    {
        "Member": "Johnny Customer",
        "Timestamp": "2019-05-01 00:49:02",
        "Direction": "Inbound",
        "Message": "No that’s it. Thanks."
    },
    {
        "Member": "Sandy",
        "Timestamp": "2019-05-01 00:49:10",
        "Direction": "Outbound",
        "Message": "Ok. Thanks for contacting the Service Desk. Have a great day."
    }
    ]
}