Agent Session Events

Agent events are events that pertain to the agent session itself.

AgentSessionStart

The AgentSessionStart event is received when an agent session is first started or joined. You can also receive an AgentSessionStart event if you request events using an old session ID. The AgentSessionStart event contains information about the agent session, and may be accompanied by several other events that describe the agent session and contact states (if you join an existing session, or use an old session ID).

{
    "Type": "AgentSessionStart",
    "BusNo": "4500",
    "AgentId": "12214",
    "SessionId": "58070815",
    "StationPhoneNumber": "8013203420",
    "StationCallerId": "8013203200",
    "DialerCampaign": "",
    "DialerCampaignStartTime": "2013-09-10T19:16:33.000Z",
    "SupervisorPermissionLevel": "4",
    "CanMask": "True",
    "AgentSchedulePermission": "True",
    "ScoreRecordingsPermission": "True",
    "HideAgentStatePermission": "",
    "CanMultiPartyConference": "True"
}

AgentSessionEnd

The AgentSessionEnd event is received when the agent session ends. Note that shortly after the session ends, the event queue for the session is cleared out (including this event). If your application is polling using the "comet" design patter, you should receive this event as soon as it occurs. If you are polling or using some other model, you may miss this event. Note that attempting to use an agent session ID for a session that has ended will result in a "409 Session Ended" HTTP status.

{
    "Type": "AgentSessionEnd",
    "Success": "True",
    "Message": ""
}

RemoteAgentSessionEnd

This event is delivered if the agent session was ended by an administrator. Administrators can request that an agent session end through the Central administration web site, or through an application that uses the "remote session end" API call.

This event will be followed by a normal "AgentSessionEnd" event.

{
    "Type": "RemoteAgentSessionEnd",
    "Message": "RemoteLogoff"
}

AgentState

The AgentState event will be delivered when the agent's state is changed. This can happen because the agent session requests the change, or because a call or contact is being delivered to the agent, or it can happen automatically when a contact ends (the agent will be moved to their "next" state.)

{
    "Type": "AgentState",
    "CurrentState": "Unavailable",
    "CurrentOutReason": "",
    "NextStates": [
        {
            "State": "Unavailable",
            "OutReason": ""
        }
    ],
    "StartTimeUTC": "2013-09-10T20:05:37.000Z",
    "IsAcw": "False",
    "AcwTimeout": "0"
}

AgentLeg

AgentLeg events are events related to the agent station associated with a session. There are three "Status" events for the agent leg: Dialing, Active, and Disconnected.

{
    "Type": "AgentLeg",
    "AgentLegId": "2200339882",
    "Status": "Dialing",
    "FinalState": "False"
},
{
    "Type": "AgentLeg",
    "AgentLegId": "2200339884",
    "Status": "Active",
    "FinalState": "False"
},
{
    "Type": "AgentLeg",
    "AgentLegId": "2200339882",
    "Status": "Disconnected",
    "FinalState": "True"
}

AgentLegError

This event is generated when an error occurs on the agent leg.

{
    "Type": "AgentError",
    "Command": "ReadyAgentLeg",
    "ResultCode": "BadNumber",
    "ContactID": "-1",
    "Target": "AgentLeg",
    "ErrorLevel": "Medium"
}

NOTE: The "AgentError" event can also be received with outbound phone calls, if an error occurs on the outbound call leg.

"ResultCode" values:

Low List Notification

This event pertains to the Personal Connection dialer product. If the agent is logged into a Personal Connection outbound skill, and the platform senses that the volume of numbers to be called on its list is "running low", a notification is sent to the agent (and all other agents logged into the skill). You can use this event to display a "low list volume" notice to the agent. Some call centers use this notification to prompt agents to notify a manager, or to log out of the skill.

{
    "Type": "NaturalCallingSkillList",
    "Empty": "True"
}

Call Contact Events are events that are related to phone calls that are either routed to the agent (inbound, or dialer-generated outbound), or placed by the agent (manual outbound).

There is only one "call contact event" structure. The event structure contains a "Status" field that identifies the status of the contact. For instance, you will receive an "Incoming" status when a call is first being routed to the agent (while the agent leg is being called). You will receive an "Active" status when a call is finally connected to the agent leg. You will receive a "Disconnected" status when the call is ended by either the agent or the caller. There are other call statuses you can receive. The structure of the event is the same for each of them.

CallContactEvent

{
    "Type": "CallContactEvent",
    "ContactID": "1569815",
    "Status": "Dialing",
    "OriginalState": "False",
    "CallType": "Regular",
    "DNIS": "4000010001",
    "ANI": "8013203200",
    "Skill": "1507",
    "IsInbound": "False",
    "StartTimeUTC": "2013-09-11T05:03:24.000Z",
    "LastStateChangeTimeUTC": "2013-09-11T05:03:24.000Z",
    "ScreenPopUrl": "",
    "DisconnectCode": "NA",
    "IsLogging": "False",
    "Timeout": "",
    "AllowDispositions": "True",
    "Label": "",
    "IsLinked": "False",
    "TimeZones": "",
    "FinalState": "False",
    "OtherInformation": "",
    "BlendingToSkillName": ""
}

WorkItemContactEvent

These events are similar to CallContactEvent notices. WorkItemContactEvent notices occur when the status of a work item contact changes.

    {
        "Type": "WorkItemContactEvent",
        "ContactID": "1569819",
        "Status": "Incoming",
        "WorkItemId": "3920",
        "WorkItemPayload": 
            "{\"queries\":[{\"query\":\"SELECT ID FROM case WHERE Priority='Low'\"}]}",
        "WorkItemType": "Testing",
        "AgentId": "1218",
        "SkillId": "1528",
        "StartTimeUTC": "2013-09-11T05:15:44.000Z",
        "LastStateChangeTimeUTC": "2013-09-11T05:15:44.000Z",
        "ScreenPopUrl": "http://www.microsoft.com?variable2=Jose&variable3=90",
        "ScreenPopUrlVariables": [
			{
				"variable2": "Jose"
			},
			{
				"variable3": "90"
			}
        ],
        "RefusalTimeout": "45"
        "FinalState": "False"
    }

Indicator

{
    "Type": "Indicator",
    "Name": "IndTest",
    "ImageUri": "https://www.example.com/images/computer.png",
    "ActionType": "OpenURL",
    "ActionUri": "http://www.incontact.com/",
    "ToolTip": "test123",
    "IndicatorState": "On"
}

PageOpen

{
    "Type": "PageOpen",
    "ContactID": "1569819",
    "Action": "OPEN",
    "PageUri": "http://eng-ngpcl07/WebScripting/Default.aspx?id=1218&__ContactID=1569819&__bus_no=199&__type=OPEN"
}

ChatContactEvent

{
    "Type": "ChatContactEvent",
    "ContactID": "1569822",
    "RoomId": "2",
    "Status": "Incoming",
    "Skill": "1509",
    "StartTime": "2013-09-11T05:30:39.000Z",
    "LastStateChangeTime": "2013-09-11T05:30:39.000Z",
    "ScreenPopUrl": "",
    "RefusalTimeout": "45",
    "IsActive": "True",
    "Messages": [
    {
        "Text": "asdf",
        "TimeStamp": "2013-09-11T05:30:40.750Z",
        "PartyType": "Client"
    }
    ],
    "FinalState": "False"
}

ChatTextEvent

{
    "Type": "ChatText",
    "RoomId": "2",
    "Label": "CustomAgentLabel",
    "Message": "Test",
    "PartyType": "Agent",
    "TimeStamp": "2013-09-11T05:32:10.000Z"
{
}
    "Type": "ChatText",
    "RoomId": "2",
    "Label": "CustomCallerLabel",
    "Message": "Test Test Test",
    "PartyType": "Client",
    "TimeStamp": "2013-09-11T05:32:36.000Z"
{
}
    "Type": "ChatText",
    "RoomId": "2",
    "Label": "SystemSaysHello",
    "Message": "$Localized:ChatSessionEnded",
    "PartyType": "System",
    "TimeStamp": "2013-09-11T05:33:09.000Z"
}

TakeOver

{
    "Type": "TakeOver",
    "ContactID": "TargetContactID",
    "TakeOverDate": "2013-09-11T07:23:26.632Z"
}

Monitoring an Agent

{
    "Type": "SupervisorContact",
    "ContactID": "6550071587",
    "Status": "Active",
    "OriginalState": "False",
    "CallType": "Regular",
    "DNIS": "9991638000",
    "ANI": "+748596215382",
    "Skill": "50883",
    "IsInbound": "False",
    "StartTimeUTC": "2013-09-11T07:32:03.000Z",
    "LastStateChangeTimeUTC": "2013-09-11T07:32:04.000Z",
    "ScreenPopUrl": "",
    "DisconnectCode": "NA",
    "IsLogging": "False",
    "Timeout": "",
    "AllowDispositions": "False",
    "Label": "",
    "IsLinked": "False",
    "TimeZones": "",
    "FinalState": "False",
    "OtherInformation": ""
}
{
    "Type": "SupervisorMonitor",
    "MonitorStartTime": "2013-09-11T07:32:10.000Z",
    "TargetAgentId": "9011",
    "FinalState": "False"
}

Take Over an Agent's Call

{
    "Type": "CallContactEvent",
    "ContactID": "6550071591",
    "Status": "Active",
    "OriginalState": "False",
    "CallType": "TakeOver",
    "DNIS": "9991638000",
    "ANI": "011748596215382",
    "Skill": "50883",
    "IsInbound": "True",
    "StartTimeUTC": "2013-09-11T07:33:57.000Z",
    "LastStateChangeTimeUTC": "2013-09-11T07:33:57.000Z",
    "ScreenPopUrl": "",
    "DisconnectCode": "NA",
    "IsLogging": "False",
    "Timeout": "",
    "AllowDispositions": "True",
    "Label": "",
    "IsLinked": "False",
    "TimeZones": "",
    "FinalState": "False",
    "OtherInformation": "",
    "BlendingToSkillName": ""
}

Custom Events

Custom events are events that you create and add into the agent event stream. It gives you a method of communicating or passing data from the VC to services that consume the event stream. This is a useful option if the existing events don't quite fit your use case.

An agent event stream is established with an agent session. An agent session begins when the agent launches their agent application.

You ask contacts their favorite color in the IVR. You package and pass this selection as a custom event named FavoriteColor. You also have a companion service running with your agent application that listens for the FavoriteColor event. This lets you pass the contact's color selection to the companion service. The service then displays the color inside the agent application.

The following are highlights about custom events:

• You can pass data as a string in the event.

• You can create custom events using either an API or the CustomEvent action in a Studio script.

• You can generate custom events in response to actions like OnAnswer or during pre-agent actions (if the agent ID is supplied).

• You can consume the agent event stream with the get-next-event API or Get Next Event Studio action.

• Because services typically already consume the agent event stream, this can be a convenient method of sharing data without needing to stand up your own custom endpoint.

• Custom events are often used for small scope apps or microservices.

• You can find custom events by opening the browser's developer tools in CXone Agent.

Create Custom Events

To create a custom event via API or Studio action, both options have the same requirements:

• Name the event.

• Assign a target agent in the agentId parameter or Target Agent property of the Studio action. You can use the ID from the AgentId variable. This is automatically populated after the OnAnswer event. If you want to send a custom event before an agent is assigned, you must still supply an agent ID.
• Set the persistInMemory field. If the agent is logged out, this determines whether they will receive the event after logging back in.
• Populate the Data field, which is the payload as a string.

Below is an example of creating a custom event using the custom-event API. For an example of using the CustomEvent action in a Studio script, see the online help.

Example curl:

curl -X PUT "https://api-$AREA.$DOMAIN/incontactapi/services/v30.0/agents/$AGENT_ID/custom-event?eventName=From_Postman&persistInMemory=false&data=Sent_from_Postman"

Request Type: PUT

Fields:

HoursOfOperation

This event will be delivered if a transfer request is made to a skill queue that is configured with hours of operation, and if the current time is outside of those hours. The platform will send this event to indicate that the skill is currently "closed" per the configuration, and will indicate whether or not the skill is configured to allow a "continue" request, which will queue the transfer to the skill even though it is closed.

{
    "Type": "HoursOfOperation",
    "ShowContinueReskill": "True"
}