05 Events

Notes:

Events describe “what happened” (server-pushed or locally emitted by the SDK).

Event constants are exposed via AgentSDK.EventType (or an equivalent enum).

Each event payload typically contains an eventType string to identify the event.

Types in 06-Types.md are the source of truth. This document provides field-level payload tables and practical notes for integration.

1. Subscribe to events (on/off/once)

const { EventType } = AgentSDK;

const onStatus = (e) => console.log('agentStatus', e);
AgentSDK.on(EventType.AGENT_STATUS, onStatus);

AgentSDK.once(EventType.SESSION_INIT, () => console.log('session init'));

// Cleanup on unload
AgentSDK.off(EventType.AGENT_STATUS, onStatus);

2. Event catalog (common)

Scenario	Event name (`eventType`)	`EventType` constant
Agent status	`agentStatus`	`AGENT_STATUS`
Preview outbound: start dialing customer	`previewObCallStart`	`PREVIEW_OBCALL_START`
Preview outbound: customer ringing	`previewObCallRinging`	`PREVIEW_OBCALL_RINGING`
Preview outbound: bridged	`previewObCallBridge`	`PREVIEW_OBCALL_BRIDGE`
Preview outbound: result	`previewObCallResult`	`PREVIEW_OBCALL_RESULT`
Consult started	`atxferStart`	`ATXFER_START`
Consult connected	`atxferLink`	`ATXFER_LINK`
Consult ended (resume/hangup/cancel)	`atxferEnded`	`ATXFER_ENDED`
Consult failed	`atxferError`	`ATXFER_ERROR`
Consult three-way result	`threewayAtxferResult`	`THREEWAY_ATXFER_RESULT`
Consult three-way ended	`atxferThreewayUnlink`	`ATXFER_THREEWAY_UNLINK`
Consult transfer completed	`completeAtxferResult`	`COMPLETE_ATXFER_RESULT`
Ringing	`ringing`	`RINGING`
Session init/terminate	`sessionInit` / `sessionTerminate`	`SESSION_INIT` / `SESSION_TERMINATE`
SIP session init/terminate	`sipSessionInit` / `sipSessionTerminate`	`SIP_SESSION_INIT` / `SIP_SESSION_TERMINATE`
Reconnect attempt	`reconnectAttempt`	`RECONNECT_ATTEMPT`
Queue status (supervisor)	`queueStatus`	`QUEUE_STATUS`
Silent monitoring (result/link/unlink)	`spyResult` / `spyLink` / `spyUnlink`	`SPY_RESULT` / `SPY_LINK` / `SPY_UNLINK`
Three-way (result/link/unlink)	`threewayResult` / `threewayLink` / `threewayUnlink`	`THREEWAY_RESULT` / `THREEWAY_LINK` / `THREEWAY_UNLINK`
Whisper coaching (result/link/unlink)	`whisperResult` / `whisperLink` / `whisperUnlink`	`WHISPER_RESULT` / `WHISPER_LINK` / `WHISPER_UNLINK`
Barge-in (result/link/unlink)	`bargeResult` / `bargeLink` / `bargeUnlink`	`BARGE_RESULT` / `BARGE_LINK` / `BARGE_UNLINK`
Force disconnect result	`disconnectResult`	`DISCONNECT_RESULT`
Force offline result	`setOfflineResult`	`SET_OFFLINE`
Extension state	`extenState`	`EXTENSTATE`
IVR interaction return	`interactReturn`	`INTERACT_RETURN`
Softphone disconnected	`sipDisconnected`	`SIP_DISCONNECTED`
Real-time transcription	`transcript`	`TRANSCRIPT`
Scheduled callback	`orderCallBack`	`ORDER_CALLBACK`
Ping (latency / network)	`ping`	`PING`
WebRTC stats (per second in-call)	`webrtcStats`	`WEBRTC_STATS`

3. Payloads (field-level)

Tip: state/stateAction values are defined in 08-State-Machine-stateAction.md. For stricter typing, use 06-Types.md.

3.1 agentStatus (Agent status)

Emitted when the agent state changes.

Field	Type	Description
eventType	string	Always `agentStatus`
tenantId	string	Tenant ID
agentNo	string	Agent ID
status	object	Agent status object (`state/stateAction/initialStatus/deviceStatus/...`)

Example shape:

{
  eventType: 'agentStatus',
  tenantId: 't1',
  agentNo: '0001',
  status: {
    state: 'idle',
    stateAction: 'idle',
    initialStatus: 1,
    deviceStatus: 0
    // When deviceStatus=2/3/4, may include callType/uniqueId/mainUniqueId, etc.
  }
}

3.2 previewObCallStart (Preview outbound: start dialing customer)

Field	Type	Description
eventType	string	Always `previewObCallStart`
tenantId	string	Tenant ID
agentNo	string	Agent ID
customerNumber	string	Customer number
customerNumberType	number	`0` landline; `1` mobile
obClidAreaCode	string	Customer area code
mainUniqueId	string	Main call unique id
requestUniqueId	string	Request unique id
obClid	string	Outbound caller ID

3.3 previewObCallRinging (Preview outbound: customer ringing)

Field	Type	Description
eventType	string	Always `previewObCallRinging`
tenantId	string	Tenant ID
agentNo	string	Agent ID
customerNumber	string	Customer number
customerNumberType	number	`0` landline; `1` mobile
obClidAreaCode	string	Customer area code
state	string	Agent state (`offline/invalid/idle/busy/calling/ringing/talking/wrapup`)
stateAction	string	State action (see `08-State-Machine-stateAction.md`)
mainUniqueId	string	Main call unique id

3.4 previewObCallBridge (Preview outbound: bridged)

Field	Type	Description
eventType	string	Always `previewObCallBridge`
tenantId	string	Tenant ID
agentNo	string	Agent ID
customerNumber	string	Customer number
customerNumberType	number	`0` landline; `1` mobile
obClidAreaCode	string	Customer area code
channel	string	Channel name
destChannel	string	Destination channel name
mainUniqueId	string	Main call unique id

3.5 previewObCallResult (Preview outbound: result)

Field	Type	Description
eventType	string	Always `previewObCallResult`
tenantId	string	Tenant ID
agentNo	string	Agent ID
customerNumber	string	Customer number
result	string	`success` connected; `error` failed (e.g., cancelled)
uniqueId	string	Call unique id
obClid	string	Outbound caller ID

3.6 ringing

Field	Type	Description
eventType	string	Always `ringing`
tenantId	string	Tenant ID
agentNo	string	Agent ID
callType	number	1 inbound; 2 WebCall; 4 preview outbound; 5 predictive outbound; 6 outbound; 9 internal call; 11 SIP access
channel	string	Channel name
mainUniqueId	string	Main call unique id
uniqueId	string	Per-leg unique id
customerNumber	string	Customer number
customerAreaCode	string	Area code
customerProvince	string	Province
customerCity	string	City
subCallType	number	Sub-type (101/102/103/...) used to differentiate transfer/consult/monitoring, etc.
hotline	string	Hotline
numberTrunk	string	Trunk
queueNo	string	Queue number
chanVariables	object	Custom variables

3.7 Consult events: atxferStart / atxferLink / atxferEnded / atxferError

atxferStart (Consult started)

Field	Type	Description
eventType	string	Always `atxferStart`
tenantId	string	Tenant ID
agentNo	string	Agent ID
channel	string	Channel name
destChannel	string	Destination channel name
state	string	Agent state
stateAction	string	State action
mainUniqueId	string	Main call unique id

atxferLink (Consult connected)

Field	Type	Description
eventType	string	Always `atxferLink`
tenantId	string	Tenant ID
agentNo	string	Agent ID
channel	string	Channel name
target	string	Consult target
targetType	number	0 PSTN; 1 agent; 2 extension
state	string	Agent state
stateAction	string	State action

atxferEnded (Consult ended: resume/hangup/cancel)

Field	Type	Description
eventType	string	Always `atxferEnded`
tenantId	string	Tenant ID
agentNo	string	Agent ID
target	string	Consult target
targetType	number	0 PSTN; 1 agent; 2 extension
hangupSide	number	Who hung up (consult party vs agent/customer)
state	string	Agent state
stateAction	string	State action

atxferError (Consult failed)

Field	Type	Description
eventType	string	Always `atxferError`
tenantId	string	Tenant ID
agentNo	string	Agent ID
state	string	Agent state
stateAction	string	State action

3.8 threewayAtxferResult / atxferThreewayUnlink / completeAtxferResult

threewayAtxferResult (Consult three-way result)

Field	Type	Description
eventType	string	Always `threewayAtxferResult`
tenantId	string	Tenant ID
agentNo	string	Agent ID
target	string	Consult target
targetType	number	0 PSTN; 1 agent; 2 extension
state	string	Agent state
stateAction	string	State action

atxferThreewayUnlink (Consult three-way ended)

Field	Type	Description
eventType	string	Always `atxferThreewayUnlink`
tenantId	string	Tenant ID
agentNo	string	Agent ID
target	string	Consult target
targetType	number	0 PSTN; 1 agent; 2 extension
state	string	Agent state
stateAction	string	State action

completeAtxferResult (Consult transfer completed)

Field	Type	Description
eventType	string	Always `completeAtxferResult`
tenantId	string	Tenant ID
agentNo	string	Agent ID
target	string	Consult target
targetType	number	0 PSTN; 1 agent; 2 extension
state	string	Agent state
stateAction	string	State action

3.9 reconnectAttempt

Emitted when the SDK is about to attempt a reconnect. Max attempts: 20. After that, the agent should re-login.

Field	Type	Description
eventType	string	Always `reconnectAttempt`
attempt	number	Attempt number (starting at 1)
code	number	`0` reconnected; `-1` disconnected
firstAttemptTs	number	Timestamp (ms) when reconnect loop started
maxAttempts	number	Max attempts (fixed at 20)
sinceFirstAttemptMs	number	Elapsed time since first attempt (ms)

3.10 queueStatus (Supervisor)

Field	Type	Description
eventType	string	Always `queueStatus`
queueStatus	object	Map: `{ "<queueNo>": { queueParams, agentStatuses, queueEntries } }`

See queue types in 06-Types.md.

3.11 spyResult / spyLink / spyUnlink (Silent monitoring)

spyResult

Field	Type	Description
eventType	string	Always `spyResult`
tenantId	string	Tenant ID
agentNo	string	Agent ID
spiedCno	string	Target agent ID
initiator	string	Monitoring initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension
uniqueId	string	Call unique id
result	string	`success` or `error`

spyLink

Field	Type	Description
eventType	string	Always `spyLink`
tenantId	string	Tenant ID
agentNo	string	Agent ID
spiedCno	string	Target agent ID
initiator	string	Monitoring initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension
result	string	`success` or `error`
channel	string	Channel name

spyUnlink

Field	Type	Description
eventType	string	Always `spyUnlink`
tenantId	string	Tenant ID
agentNo	string	Agent ID
spiedCno	string	Target agent ID
initiator	string	Monitoring initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension

3.12 threewayResult / threewayLink / threewayUnlink (Supervisor three-way)

threewayResult

Field	Type	Description
eventType	string	Always `threewayResult`
tenantId	string	Tenant ID
agentNo	string	Agent ID
threewayedCno	string	Target agent ID
initiator	string	Initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension
uniqueId	string	Call unique id
result	string	`success` or `error`

threewayLink

Field	Type	Description
eventType	string	Always `threewayLink`
tenantId	string	Tenant ID
agentNo	string	Agent ID
threewayedCno	string	Target agent ID
initiator	string	Initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension
channel	string	Channel name

threewayUnlink

Field	Type	Description
eventType	string	Always `threewayUnlink`
tenantId	string	Tenant ID
agentNo	string	Agent ID
threewayedAgentNo	string	Target agent ID
initiator	string	Initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension

3.13 whisperResult / whisperLink / whisperUnlink (Whisper coaching)

whisperResult

Field	Type	Description
eventType	string	Always `whisperResult`
tenantId	string	Tenant ID
agentNo	string	Agent ID
whisperedCno	string	Target agent ID
initiator	string	Initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension
uniqueId	string	Call unique id
result	string	`success` or `error`

whisperLink

Field	Type	Description
eventType	string	Always `whisperLink`
tenantId	string	Tenant ID
agentNo	string	Agent ID
whisperedCno	string	Target agent ID
initiator	string	Initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension
channel	string	Channel name

whisperUnlink

Field	Type	Description
eventType	string	Always `whisperUnlink`
tenantId	string	Tenant ID
agentNo	string	Agent ID
whisperedAgentNo	string	Target agent ID
initiator	string	Initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension

3.14 bargeResult / bargeLink / bargeUnlink (Barge-in)

bargeResult

Field	Type	Description
eventType	string	Always `bargeResult`
tenantId	string	Tenant ID
agentNo	string	Agent ID
bargedAgentNo	string	Target agent ID
initiator	string	Initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension
uniqueId	string	Call unique id
result	string	`success` or `error`

bargeLink

Field	Type	Description
eventType	string	Always `bargeLink`
tenantId	string	Tenant ID
agentNo	string	Agent ID
bargedAgentNo	string	Target agent ID
initiator	string	Initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension
channel	string	Channel name

bargeUnlink

Field	Type	Description
eventType	string	Always `bargeUnlink`
tenantId	string	Tenant ID
agentNo	string	Agent ID
bargedCno	string	Target agent ID
initiator	string	Initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension

3.15 disconnectResult (Force disconnect result)

Field	Type	Description
eventType	string	Always `disconnectResult`
tenantId	string	Tenant ID
agentNo	string	Agent ID
disconnectorCno	string	Target agent ID
initiator	string	Initiator
initiatorType	number	0 PSTN; 1 agent; 2 extension
uniqueId	string	Call unique id
result	string	`success` or `error`

3.16 setOfflineResult (Force offline result)

Field	Type	Description
eventType	string	Always `setOfflineResult`
tenantId	string	Tenant ID
agentNo	string	Agent ID
initiator	string	Who forced offline (supervisor agentNo or admin name)
code	string	`0` success; `-1` failure
message	string	Message (commonly `ok`)

3.17 orderCallBack (Scheduled callback)

This event exists (eventType=orderCallBack, EventType.ORDER_CALLBACK), but the current source documentation does not provide a field-level payload contract.

Recommended approach:

Treat it as a pass-through event and branch on eventType=orderCallBack
If you must rely on concrete fields, confirm the payload contract with the backend team before integration

3.18 extenState (Extension state)

Field	Type	Description
eventType	string	Always `extenState`
state	string	`Reachable` / `Unreachable`
registerState	string	`Registered` / `Unregistered`
registerTime	string	Registration time (e.g., `2024-01-01 10:54:19`)
expirationTime	string	Expiration time
extenIp	string	Phone IP
URI	string	Registration URI
extenNo	string	Extension number
tenantId	string	Tenant ID

3.19 interactReturn (IVR interaction return)

Field	Type	Description
eventType	string	Always `interactReturn`
tenantId	string	Tenant ID
agentNo	string	Agent ID
returnVariables	object	Return variables (provided via `transferIvr`)

3.20 sipDisconnected (Softphone disconnected)

Emitted when the softphone connection is interrupted. In most cases, the agent should re-login / recreate the softphone session.

3.21 transcript (Real-time transcription)

Naming note: legacy docs may mention transcriptEvent or rasr. The SDK public eventType is transcript.

Field	Type	Description
eventType	string	Always `transcript`
text	string	Transcribed sentence text
role	number	`1` agent side; `2` customer side
transcriptTime	number	Absolute timestamp (ms) when text is generated
beginTime	number	Relative begin time from recording start (ms)
endTime	number	Relative end time from recording start (ms)
finished	number	`1` finished; `0` in progress
sentenceIndex	number	Index, starting from 0
sentenceType	string	`intermediateResult` / `sentenceEnd`
mainUniqueId	string	Main call unique id
sentenceBeginTimestamp	number	Timestamp (ms) when engine started for the sentence (returned with `sentenceEnd`)
sentenceEndTimestamp	number	Timestamp (ms) when final text returned (returned with `sentenceEnd`)

3.22 ping (Latency / network quality)

Field	Type	Description
eventType	string	Always `ping`
latencyTime	number	Ping latency in ms
networkState	number	Network quality bucket derived from latency

3.23 webrtcStats (WebRTC call stats)

Requires webrtcStats=true in setup() (or tenant-side enablement). Emitted once per second during a softphone call.

The payload is large; treat it as WebrtcStatsEvent from 06-Types.md. Key fields include:

iceState, dtlsState
packetsSent/packetsReceived, packetsState
jitter, rtt, packetLossRate
sentNetworkQuality, receivedNetworkQuality

4. Typical sequences

For key event sequences (preview outbound / consult flows), see 10-Key-Flows-Sequence-Diagrams.md.