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"
}
Field name Field type Description
Type string "AgentSessionStart"
BusNo string (integer) A string representing the business unit number
AgentId string (integer) A string representing the agent ID number
SessionId string A string identifying the agent session on the platform. Note that this is NOT the same as the "session ID" used by the API.
StationPhoneNumber string A string representing the station phone number for the agent (without formatting)
StationCallerId string A string representing the "caller ID" presented to called parties when the agent calls them.
DialerCampaign string A string representing the "dialer campaign" (or automated outbound skill) the agent is logged into (if applicable – will be empty if they are not logged into an outbound skill/campaign.)
DialerCampaignStartTime string (date) The ISO8601-formatted date/time (in UTC time) that the dialer campaign started (if the agent is logged into a campaign/skill – this vale has no meaning if the agent is not logged into a campaign.)
SupervisorPermissionLevel string (integer) N/A
CanMask string (boolean) A string representing a Boolean value ("True" or "False") indicating if the agent should be able to mask calls.
AgentSchedulePermission string (boolean)
ScoreRecordingsPermission string (boolean)
HideAgentStatePermission string (boolean)
CanMultiPartyConference string (boolean) A string representing a Boolean value ("True" or "False") indicating if the agent and agent's business unit have permissions to perform "multi party conferencing".

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": ""
}
Field name Field type Description
Type string "AgentSessionEnd"
Success string (boolean) String representing a Boolean value. Indicates that the agent session has ended cleanly.
Message string Any platform message related to the session end (almost always blank).

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"
}
Field name Field type Description
Type string "RemoteAgentSessionEnd"
Message string Any platform message related to the remote session end.

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"
}
Field name Field type Description
Type string "AgentState"
CurrentState string A text description of the agent's state. Can be one of the following:
  • LoggedOut
  • LoggedIn
  • Available
  • Unavailable
  • InboundContact
  • OutboundContact
  • InboundConsult
  • OutboundConsult
  • Dialer
CurrentOutReason string If the agent's state is "Unavailable", there may be an associated "outstate reason" (a.k.a. "unavailable code"). Unavailable codes are configured in Central and are often used for things like "lunch", "break", etc. If the agent's Unavailable state is associated with an outstate reason, the description will be in this field.
NextStates array of objects This is a collection of state objects that represent the agent's next state(s). If the agent is Available, there is no "next state", and this array can be ignored. If the agent is in an ACW Unavailable state, this will contain the next state (when ACW ends). If the agent is on a call, this may contain one or two states. If the skill the call is associated with is an ACW skill, it will contain the ACW state (next) and the state that will follow ACW (next-next). The agent will automatically be placed in the ACW state. Any state change requests that occur when the agent is on a call will affect the agent's next state (or next-next state, if the next state is an ACW state).
NextStates[x].State string The "next" state description.
NextStates[x].OutReason string If the "next" state is an Unavailable state with an outstate reason (a.k.a. unavailable code), this will contain the outstate reason.
StartTimeUTC string (date) This field is a string that contains an ISO8601 date that indicates when the agent's state began.
IsACW string (boolean) A String representation of a Boolean value (True or False) that indicates whether the state is an ACW state or not.
AcwTimeout string (integer) A string that represents the number of seconds that the ACW state is configured to timeout. Note that some ACW skills are configured without a timeout (where a disposition response is required before the call can completely end.)

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"
}
Field name Field type Description
Type string "AgentLeg"
AgentLegId string The "contact ID" for the agent leg script. This can be helpful in situations where a single app is managing multiple agent sessions. This ID will be valid from the time the agent leg is "dialing", until it is disconnected.
Status string The status of the agent leg. Will be "Dialing", "Active", or "Disconnected".
FinalState string (boolean) Indicates whether the state is the final state for the agent leg "contact". This will only be "true" for the "Disconnected" status event.

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"
}
Field name Field type Description
Type string "AgentError"
Command string Not Used – You can ignore this field.
ResultCode string This is the result code that indicates why there was an error on the agent leg. Possible values for this field are listed below.
ContactID string (boolean) The "contact ID" for the agent leg script. This can be helpful in situations where a single app is managing multiple agent sessions. This ID will be valid from the time the agent leg is "dialing", until it is disconnected.
Target string This will always be "AgentLeg", indicating an error for the agent leg.
ErrorLevel string A string indicating the severity of the error.

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

"ResultCode" values:

  • NA
  • AgentLegAlreadyActive
  • Succeeded
  • Failed
  • CallAbandoned
  • Active
  • NoAnswer
  • Busy
  • BadNumber
  • Error
  • InvalidCallLeg
  • InvalidCallCount
  • InvalidStationID
  • InvalidWorkItem
  • JoinFailed
  • LinkFailed
  • InitiateConferenceFailed
  • InvalidState
  • Rejected
  • MissingRoomID
  • TransferComplete
  • Dropped
  • NoPorts
  • AgentLinkTimeout
  • AgentCancelled
  • LoginFailed
  • CampaignClosed
  • DialerActive
  • DialerSuppressed
  • AnsweringMachine
  • Fax

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"
}
Field name Field type Description
Type string "NaturalCallingSkillList"
Empty string (boolean) A string representing a Boolean value (True or False) that indicates whether the list is completely empty or not.

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": ""
}
Field name Field type Description
Type string "CallContactEvent"
ContactID string (integer) The unique contact ID for this contact. This will be unique on the platform. Note that this value will change each time the call is transferred – the receiving agent will have a different contact ID. It is possible to store the "master contact ID" (the contact ID of the original call, allowing you reference CRM or database data about the call. The master Contact ID can be stored in a script variable, which will be delivered as a "screen pop variable".
Status string This is the current status of the contact. The possible values for Status can be found below.
OriginalState string (boolean) Not used – you can ignore this field.
CallType string A string that indicates the call type. The possible values for CallType can be found below.
DNIS string The phone number the caller dialed.
ANI string The phone number the caller dialed from.
Skill string The name of the skill the call was routed to (or placed on, for outbound calls)
IsInbound string (boolean) A string that represents a Boolean value (True or False) indicating whether the call is an inbound call or not. (If it's not inbound, it's outbound).
StartTimeUTC string (date) A string that is an ISO8601-formatted date/time that shows when the contact started. This will always be in UTC time.
LastStateChangeTimeUTC string (date) A string that is an ISO8601-formatted date/time that shows when the current status of the call was set. This will always be in UTC time (related to the server time).
ScreenPopUrl string A string that represents a URL that should be opened in a browser and displayed to the agent. This can be used to convey screen pop data to the agent. In some cases, you can use this field to simply transfer data to the agent application without actually displaying a web page.
DisconnectCode string A string that represents a disconnect reason if an outbound call failed, or other error that may occur on a call. Various disconnect codes have various causes, and these will be documented in future versions of this documentation. The possible values for DisconnectCode can be found below.
IsLogging string (boolean) A string that represents a Boolean value (True or False) that indicates whether the call is being recorded (a.k.a. "logged"). This value will only show "true" if the agent has requested that the call be recorded. If call recording/logging is initiated through an IVR script or by an administrator (through the Central admin web site or through the Admin API), this value will NOT indicate that the call is being recorded.
Timeout string (integer) Not Used – you can ignore this field.
AllowDispositions string (boolean) A string that represents a Boolean value (true or false) that indicates whether or not this contact can be dispositioned.
Label string Not used – you can ignore this field.
IsLinked string (boolean) A string representing a Boolean value (true or false) that indicates whether or not this call is the "linked" call for a Personal Connection outbound dialer campaign. If the ratio of outbound call attempts is greater than 1:1 (meaning more than one outbound call is being placed concurrently for each agent), the agent session will receive CallContactEvent notices for each of the outbound calls that are assigned to the agent. The agent's voice path will only be linked to one of the calls, however. This field indicates which of the calls the agent is listening to. This allows you to do a screen pop or display data to the agent about the call that is deemed "most likely to be connected next".
TimeZones string Not used – you can ignore this field.
FinalState string (boolean) String representing a Boolean (true or false) that indicates whether the call is completed. When the voice path for a call is torn down, the agent session will receive a "Disconnected" status in a CallContactEvent. But if the agent is moved into an Unavailable/ACW state, the contact will still be "active" in the system, and the FinalState property of the CallContactEvent will be "false". Time will be counted towards the overall handle time for the contact during this phase. When the ACW state finally ends, the contact will be completely closed out, and the agent will receive a Disconnected status event with the FinalState property set to "true".
OtherInformation string A string that contains HTML data that should be displayed to the agent when they receive CallContactEvent notices for Personal Connection outbound dialer calls. If the call was requeued to the dialer as a "callback", the original handling agent is able to enter "callback notes" for the call. These should be displayed to the next agent to handle the call record. In addition, dialer list entries can have values that are considered "custom values" that should be displayed to the agent. The callback notes and custom field display values are delivered in the OtherInformation field as HTML data.
BlendingToSkillName string If blending is enabled on the platform, the agent session may be automatically logged into and out of a Personal Connection outbound skill campaign. It is possible to move the agent out of a Personal Connection campaign, and to deliver a call for a skill that the agent is not directly assigned to handle. In this scenario, the skill name is provided in the contact event so that it can be displayed to the agent (or used for other reasons).

"Status" values:

  • Incoming
  • Ringing
  • Dialing
  • Active
  • Holding
  • Joined
  • Disconnected
  • CallBackDisconnected
  • Preview
  • Masking
  • NaturalCallRinging
  • NaturalCallAMD
  • NaturalCallDialing

"CallType" values:

  • Regular
  • AgentLeg
  • ReskillProxy
  • Consult
  • PersonalQueue
  • Dialer
  • TakeOver
  • NaturalCalling

"DisconnectCode" values:

  • NA
  • AgentLegAlreadyActive
  • Succeeded
  • Failed
  • CallAbandoned
  • Active
  • NoAnswer
  • Busy
  • BadNumber
  • Error
  • InvalidCallLeg
  • InvalidCallCount
  • InvalidStationID
  • InvalidWorkItem
  • JoinFailed
  • LinkFailed
  • InitiateConferenceFailed
  • InvalidState
  • Rejected
  • MissingRoomID
  • TransferComplete
  • Dropped
  • NoPorts
  • AgentLinkTimeout
  • AgentCancelled
  • LoginFailed
  • CampaignClosed
  • DialerActive
  • DialerSuppressed
  • AnsweringMachine
  • Fax

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"
    }
Field name Field type Description
Type string "WorkItemContactEvent"
ContactID string (boolean) A string representing a Boolean value (True or False) that indicates whether the skill is configured to allow a "continue" request to queue the transfer to the skill even though it is closed.
Status
WorkItemId
WorkItemPayload
WorkItemType
AgentId
SkillId
StartTimeUTC
LastStateChangeTimeUTC
ScreenPopUrl
ScreenPopUrlVariables
RefusalTimeout
FinalState

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": ""
}

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"
}
Field name Field type Description
Type string "HoursOfOperation"
ShowContinueReskill string (boolean) A string representing a Boolean value (True or False) that indicates whether the skill is configured to allow a "continue" request to queue the transfer to the skill even though it is closed.