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 are consumed by the Symbee Connect Analytics solution, but via Amazon Kinesis and Lambda can also be used as the means of integration into other solutions.

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

In addition to the above, one further Amazon S3 Bucket for reporting event delivery to the Symbee Connect Analytics solution is also established (name starting with sc_reporting_delivery) and is used as a drop-box for pick-up of the data – data is not retained in this bucket, but rather deleted as soon as processed.

The following diagram depicts the resources established by the Symbee Connect Reporting and Analytics AWS CloudFormation:

Enabling Symbee Connect 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.

  1. Log into the Symbee Connect Administration Portal.

  2. From the home page after login, ensure you have selected the appropriate Environment in the top navigation bar.

  3. From the Function Menu, select Symbee Connect Integration and then select Reporting Configuration.
  4. Select which Event types you want to be published and then click Save:



Run CloudFormation

Download Reporting and Analytics CloudFormation

If this is the first Symbee Connect CloudFormation you have run, you will need to run the Integrations CloudFormation first. For step by step instructions click here. For more information about AWS Cloudformations click here.

  1. Log into the Symbee Connect Administration Portal.
  2. If you have more than one Environment configured within your Company in Symbee Connect, make sure you have the appropriate one selected. This can be found on the Navigation bar to the left of the Function menu.
  3. Then click on the main Function menu in the top navigation bar, and click on Feature Integrations (CloudFormations) in the Company Environment Configuration section.
  4. From the Feature Integrations (AWS CloudFormations) page, scroll down and locate the Reporting and Analytics CloudFormation, and click the download link to download and save the CloudFormation script.
  5. You will be prompted with a Save As dialog screen. Save the file locally to your PC for use in the following steps.

Run Symbee Connect Amazon Pinpoint SMS CloudFormation

  1. Log Into your AWS Management Console.

  2. Make sure you are in the correct AWS region for where you want to deploy (top right of the Navigation bar) – the same region as your Amazon Connect instance.

  3. Navigate to the CloudFormation console (under Management and Governance, on the Services menu).

  4. From the CloudFormations console, select Stacks in the left-hand navigation bar, and select Create Stack and select With new resources (standard) from the dropdown box.

  5. You will be presented the “Create Stack” view for creating/deploying a new CloudFormation script (known as a stack):

  6. Under the Prepare Template section, select Template is Ready

  7. Under Specify Template, select Upload a template file

  8. Under Upload a template file, click Choose File

  9. In the resulting file selector, find and upload the file you saved from above.

  10. Click Next at the bottom



  11. In the Specify Stack Details screen, complete the fields as follows:

  12. Stack Name: Enter a name appropriately. We suggest using your Symbee Connect Environment (e.g. dev, prod, etc.) in the name for better organization, in case you have CloudFormations for multiple Symbee Connect Environments Connect being deployed into the same AWS Account.
    For example:
    companyalias-environment-pinpoint

  13. LambdaDistroBucket: This is the Symbee Connect Lambdas S3 bucket where the Pinpoint Lambda will uploaded from. Select the bucket name from the drop-down that matches the AWS region you are running the CloudFormation in
  14. LambdaSourceFile: Select from the dropdown, there will be only 1 value to pick from
  15. SecretsManagerRegion: Enter the name of the AWS region where the initial Symbee Connect Integration CloudFormation was run in (see section 2.2 above).
    Examples: us-east-1, us-west-2, eu-central-1, etc.

  16. Click Next.

  17. On the next Configure stack options screen, accept all the defaults, and click Next.

  18. On the next Review testing screen, scroll to the bottom Capabilities section, check the “I acknowledge that AWS CloudFormation might create IAM resources with custom names.” Checkbox, and finally click Create Stack.


Interaction Events - General Formatting

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

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

​ "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.



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

The only used valid is “AWS Connect”. For future use.

CompanyId, Environment

Your Symbee Connect Company Alias and Environment.

TaskType

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


TaskInitiationMethod

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


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).


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:


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

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 (“”).


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

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 (“”).


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):

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

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 (“”).


AgentSessionId

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


EventType

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


CurrentState

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


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:


CurrentFocusTaskInitMethod

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


CurrentFocusTaskState

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


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."
    }
    ]
}