The headless web SDK provides events that you can listen to in order to handle
specific actions or updates within your application. You can add and remove
event listeners using the .on and .off methods.
const handleReady = () => {
console.log("**** client is ready")
}
client.on("ready", handleReady)
// client.off("ready", handleReady)
General events
The following are general events for the SDK
ready
Emit when the client is ready for communication.
client.on("ready", () => {
})
authenticated
Emit when the client has authenticated with the user's token.
client.on("authenticated", () => {
})
Chat events
The following are chat session specific events.
chat.ongoing
Emit when there is an ongoing chat.
client.on("chat.ongoing", (chat) => {
console.log(chat)
})
chat.updated
Emit when the chat instance has updated.
client.on("chat.updated", (chat) => {
// the `chat` property on `client` has updated
console.log(chat)
})
chat.message
Emit when there is a new message.
client.on("chat.message", message => {
console.log(message)
})
The message type:
interface MessageResponse {
$index: number;
$sid: string;
$timestamp: Date;
$userType: string;
$userId: number;
type: string;
content?: string;
event?: string;
file?: File;
// extra parameters
}
chat.memberJoined
Emit when a new member joins the conversation.
client.on("chat.memberJoined", (identity) => {
console.log(identity)
})
chat.memberLeft
Emit when a member leaves the conversation.
client.on("chat.memberLeft", (identity) => {
console.log(identity)
})
chat.typingStarted
Emit when a member starts typing.
client.on("chat.typingStarted", (identity) => {
console.log(identity)
})
chat.typingEnded
Emit when a member stops typing.
client.on("chat.typingEnded", (identity) => {
console.log(identity)
})
chat.connected
Emit when the chat is connected with the conversation provider.
client.on("chat.connected", () => {
console.log("connected")
})
In rare cases there might be latency issues that cause a message to be sent in a
chat before the SDK joins the chat. When this occurs you can use
fetchMessages to get all existing messages in a conversation after a chat
has connected. See the following code sample:
client.on("chat.connected", async () = {
const messages = await
client.fetchMessages()
})
chat.disconnected
Emit when the chat is disconnected from the conversation provider.
client.on("chat.disconnected", () => {
console.log("disconnected")
})
chat.dismissed
Emit when the chat's status is changed to dismissed.
client.on("chat.dismissed", () => {
console.log("dismissed")
})
chat.timeout
Emit when the chat is ended, with the reason being timeout.
client.on("chat.timeout", () => {
console.log("timeout")
})
chat.ended
Emit when the chat is ended.
client.on("chat.ended", () => {
console.log("ended")
})
chat.destroyed
Emit when destroyChat is called.
client.on("chat.destroyed", () => {
console.log("destroyed")
})
Chat check-in
The following are chat check-in events.
checkIn
Confirms the end-user's presence in queue.
Method signature
checkIn(): Promise<CheckInResponse>
Return value
Returns a CheckInResponse object.
Interfaces
interface CheckInResponse {
chat_id: number;
check_in_status: CheckInStatus;
check_in_at?: string;
}
enum CheckInStatus {
CONFIRMED = 'confirmed',
EXITED = 'exited',
PENDING = 'pending',
REQUESTED = 'requested',
SKIPPED = 'skipped',
TIMED_OUT = 'timed_out',
}
Example
try {
const response = await client.checkIn()
} catch (error) {
// handle error
}
exitCheckIn
Removes the user from the check-in queue.
Method signature
exitCheckIn(): Promise<CheckInResponse>
Return value
Returns a CheckInResponse object.
Interfaces
interface CheckInResponse {
chat_id: number;
check_in_status: CheckInStatus;
check_in_at?: string;
}
enum CheckInStatus {
CONFIRMED = 'confirmed',
EXITED = 'exited',
PENDING = 'pending',
REQUESTED = 'requested',
SKIPPED = 'skipped',
TIMED_OUT = 'timed_out',
}
notifyCheckInState
Notifies the backend of the check-in dialog visibility state.
Method signature
notifyCheckInState(data: CheckInVisibilityStateRequest): Promise<void>
Return value
Returns a CheckInResponse object.
Interfaces
interface CheckInVisibilityStateRequest {
widget_minimized?: boolean;
tab_inactive?: boolean;
}
**Example**
try {
const visibilityState = {
widget_minimized: true,
tab_inactive: false,
}
await client.notifyCheckInState(visibilityState)
} catch (error) {
// handle error
}
rejoinChat
Places the user back in queue after failure to confirm check-in.
Method signature
rejoinChat(): Promise<CheckInResponse>
Return value
Returns a CheckInResponse object.
Interfaces
interface CheckInResponse {
chat_id: number;
check_in_status: CheckInStatus;
check_in_at?: string;
}
enum CheckInStatus {
CONFIRMED = 'confirmed',
EXITED = 'exited',
PENDING = 'pending',
REQUESTED = 'requested',
SKIPPED = 'skipped',
TIMED_OUT = 'timed_out',
}
Example
try {
const response = await client.rejoinChat()
} catch (error) {
// handle error
trackCheckInEvent
Signals to the backend when certain events have been triggered by the UI. This is used when the check-in dialog has been displayed to the end-user.
Method signature
trackCheckInEvent(): Promise<void>
Example
try {
await client.trackCheckInEvent()
} catch (error) {
// handle error
Cobrowse events
The following are events specific to Co-browse:
cobrowse.request
Emit when an end-user or agent requests to start a Co-browse session.
client.on("cobrowse.request", { from } => {
console.log("request by", from)
})
cobrowse.loaded
Emit when a Co-browse session is loaded.
client.on("cobrowse.loaded", session => {
console.log("cobrowse session", session)
})
cobrowse.updated
Emit when a Co-browse session is updated.
client.on("cobrowse.updated", session => {
console.log("cobrowse session", session)
})
cobrowse.ended
Emit when a Co-browse session is ended.
client.on("cobrowse.ended", session => {
console.log("cobrowse session", session)
})