Classes

MessagingClient

Methods

connect()
connect(): Promise<void>;

Opens the real-time connection and begins event delivery: conversations, rings, agent-state changes, and the account-wide message stream all start here.

Throws if create() has not resolved yet.

Returns

Promise<void>

create()
static create(options: InitOptions): Promise<CreateResult>;

Authenticates and prepares a ready-to-use client. Fetches account context (privileges, features, user profile) so the returned session already has real permissions and displayName — no need to call getSession() after connect(). If account context is unavailable, create() still succeeds and permissions default to all-false and permissionsReady: false.

Parameters
Parameter Type
options InitOptions
Returns

Promise<CreateResult>

the client instance and the fully-resolved session. Call client.connect() afterward to open the real-time connection.

disconnect()
disconnect(): Promise<void>;

Gracefully closes the connection and clears THIS account/client's persisted token, then notifies other tabs of the same account/client to tear down too. Other accounts' sessions are untouched. Emits a session/end event once teardown completes.

Returns

Promise<void>

dispatch()
dispatch<P>(payload: P): Promise<DispatchReturnMap[P["action"]]>;

Invokes an action by name — the only way to call an SDK action; there is no separate per-action method. payload.action selects the operation and DispatchReturnMap types the resolved value for that action (void for most side-effecting actions; a typed value for actions like agent-state/get or messages/query). Rejects with a UmsError on a UMS failure, or with an AuthenticationError if the token has already expired.

Type Parameters
Type Parameter
P extends DispatchPayload
Parameters
Parameter Type
payload P
Returns

Promise<DispatchReturnMap[P["action"]]>

getSession()
getSession(): SessionObject | null;

Returns the session object — already enriched with real permissions and displayName by the time create() resolves, since create() fetches account context internally before returning. connect() does not change the session further; calling getSession() before or after connect() returns the same data. Returns null if create() has not been called.

The returned object is a frozen deep copy, not the live internal session — callers cannot mutate it or affect subsequent getSession() calls.

Returns

SessionObject | null

on()
on(options: OnOptions): void;

Registers the global event callback. All SDK events are delivered here.

There is only one callback slot: calling on() again replaces the previous callback rather than adding a second listener. Events emitted before a callback is registered are dropped, not queued — call on() before connect() so no early events (e.g. the initial connection/status) are missed.

Parameters
Parameter Type
options OnOptions
Returns

void

Interfaces

AccountUser

Extends

  • Pick<UserConfiguration, | "userTypeId" | "isApiUser" | "resetMfaSecret" | "managerOf" | "fullName" | "profileIds" | "pid" | "deleted" | "maxChats" | "skillIds" | "loginName" | "isEnabled" | "nickname" | "id" | "memberOf" | "email" | "employeeId">

Properties

Property Type Inherited from
deleted boolean Pick.deleted
email string Pick.email
employeeId string Pick.employeeId
fullName string Pick.fullName
id number Pick.id
isApiUser boolean Pick.isApiUser
isEnabled boolean Pick.isEnabled
lobIds number[] -
loginName string Pick.loginName
managerOf UserConfigurationAgentGroup[] Pick.managerOf
maxAsyncChats number -
maxChats number Pick.maxChats
memberOf UserConfigurationAgentGroup Pick.memberOf
nickname string Pick.nickname
pid string Pick.pid
profileIds number[] Pick.profileIds
resetMfaSecret boolean Pick.resetMfaSecret
skillIds number[] Pick.skillIds
userTypeId number Pick.userTypeId

AccountUsersGetAction

Properties

Property Type
action "account/users"
value? undefined

AgentAvailabilityGetAction

Properties

Property Type
action "account/agent-availability"
value object
value.restrictedAgents? string[]
value.skillId number

AgentAvailabilityRecord

A single agent entry from the skill-scoped, presence-filtered agent availability query.

Properties

Property Modifier Type
agentCurrentStatus readonly string
agentId readonly string
agentName readonly string
agentSkills readonly object[]

AgentConfiguration

Derived agent/account configuration — the real capability each privilege, AC feature, and site setting combination produces, not a flat 1:1 mirror of the raw values (those are available unfiltered on SessionObject.privileges/.features/.siteSettings). Replaces the earlier acFeatures/siteSettings split.

Properties

Property Modifier Type Description
agentList readonly boolean Privilege 1574 (VIEW_AGENT_LIST) — can see agent list (used by account/users and account/agent-availability).
agentNotTypingTimeout readonly number Site setting le.site.messaging.agentNotTypingTimeout — timeout before the typing indicator clears.
agentSetConsumerProfileEnabled readonly boolean Feature Messaging.AgentSetConsumerProfile + privilege 1750 (UPDATE_CONSUMER_PROFILE_VIA_API) — pairs with profile/set.
allConversations readonly boolean Privilege 10 (VIEW_ALL_CHATS) — can see all conversations, not just own.
allowLinkRendering readonly boolean Feature Messaging.AllowLinksRendering.
authenticatedChatEnabled readonly boolean Feature Common.Authenticated_Chat.
autoAccept readonly boolean Site setting messaging.routing.autoaccept — ring auto-accept is enabled for this agent.
autoCloseMinimalValue readonly number Site setting messaging.conv.autoclose.minimalValue — floor on the auto-close threshold above.
autoCloseTimeSec readonly number Site setting messaging.conv.autoclose.time.sec — seconds of inactivity before UMS auto-closes a conversation. Contested (see docs) — may become a conversation event instead in a future revision.
automatedConversationSummaryEnabled readonly boolean Feature Messaging.Automated_Conversation_Summary + privilege 1906 (VIEW_AUTOMATED_CONVERSATION_SUMMARY).
botMuteNotification readonly boolean Site setting messaging.bot.mute.notification.
canSendHyperlinks readonly boolean Feature Messaging.Agent_Link_Sending.
canSetManualSla readonly boolean Privilege 1741 (SET_MANUAL_SLA) — matches upstream's own agent-level gate; the per-skill hide check is a separate, conversation-scoped decision the caller makes with hideSlaTimerPerSkill/hideSlaTimerSkillList.
canUpdateConsumerProfileViaApi readonly boolean Privilege 1750 (UPDATE_CONSUMER_PROFILE_VIA_API) — exposed standalone too, but already gating agentSetConsumerProfileEnabled above.
consumerMessageChannelIndicatorEnabled readonly boolean Feature Messaging.Consumer_Message_Channel_Indicator.
controlReturnToQueueEnabled readonly boolean Feature Common.ControlReturnToQueue — the master toggle already gating conversation/to-queue; exposed standalone too.
conversationEventsInTranscript readonly ConversationEventsInTranscriptPermissions Feature Messaging.Conversation_Events_In_Transcript + 7 individual event-type privileges.
conversationIdleTimeMinutes readonly number Site setting le.agent.messaging.conversationIdleTime.minutes — minutes of inactivity before a conversation is considered idle.
conversationTimersEnabled readonly boolean Feature Messaging.Conversation_Timers.
defaultResponseTime readonly ResponseTimeTarget Site settings messaging.default.response.time + .time.unit — default SLA response-time target.
displayMcsInConversation readonly boolean Feature Messaging.Display_MCS_In_Conversation.
fetchClosedConversationInterval readonly number Site setting le.ui.fetchClosedConversationDataInterval.
fetchOngoingConversationInterval readonly number Site setting le.ui.fetchOngoingConversationDataInterval.
hideHistoryConversationsInTranscriptForSkills readonly boolean Site setting messaging.hide.history.conversations.in.transcript.for.skills.
hideSlaTimerPerSkill readonly boolean Feature Messaging.hideSLATimerPerSkill — pairs with hideSlaTimerSkillList below for the per-skill combination.
hideSlaTimerSkillList readonly boolean Site setting messaging.hideSLATimerSkillList — pairs with hideSlaTimerPerSkill above.
isCtrlEnterFeatureEnabled readonly boolean Feature Messaging.isCtrlEnterFeatureEnabled.
maxAgentNotesLength readonly number Site setting messaging.agent.notes.max.length — max character length for conversation/set-summary-note.
messagesLazyPageSize readonly number Site setting messaging.conversation.lazyPageSize — page size for lazily-loaded message history.
messagingPinnedConversations readonly boolean Site setting messaging.pinned.conversations.
pinnedConversationsEnabled readonly boolean Feature Messaging.Pinned_Conversations.
prioritizedResponseTime readonly ResponseTimeTarget Site settings messaging.default.response.prioritized.time + .time.prioritized.unit — prioritized-queue SLA response-time target.
privateMessages readonly boolean Feature Messaging.Private_Messages — account has private/whisper messaging enabled.
recentlyClosedConversationDays readonly number Site setting le.agent.recentlyClosedConversationDays — retention window for recently-closed conversations.
richContent readonly boolean Feature Common.RichContent — account has rich/structured content enabled.
richTextFormattingEnabled readonly boolean Feature Messaging.Rich_Text_Formatting.
sameSkillTransferPrevention readonly boolean Site setting messaging.transferBySkill.preventTransferToSameSkill — exclude the current skill from transfer-to-skill targets.
showReadIndicationBelowMessage readonly boolean Site setting le.agent.messaging.show.read.indication.below.message — placement of the delivered/read indicator.
smartCapacityDefaultSec readonly number Site setting messaging.smart.capacity.fresh.agent.pending.time.sec — default smart-capacity pending time.
smartCapacityPerSkill readonly SmartCapacityPerSkill Site setting messaging.smart.capacity.per.skill.definition — per-skill smart-capacity overrides.
smartComposeEnabled readonly boolean Feature Messaging.Smart_Compose (readiness flag — underlying AI Assist API is Phase 1, not yet built).
smartReplyEnabled readonly boolean Feature Messaging.Smart_Reply (readiness flag — underlying AI Assist API is Phase 1, not yet built).
smartRewriteEnabled readonly boolean Feature Messaging.Smart_Rewrite (readiness flag — underlying AI Assist API is Phase 1, not yet built).
stepUpNotification readonly boolean Site setting messaging.stepUpNotifications.
takeoverEnabled readonly boolean Feature Common.Takeover_Conversation + privilege 1731 (TAKEOVER) — the real combination already gating conversation/takeover (Phase 2); exposed standalone too.
transferToAgent readonly TransferToAgentPermissions Per-target-status transfer-to-agent access (privileges 1766/1767/1768, gated by feature Messaging.Transfer_To_Agent).
transferToAgentFeatureEnabled readonly boolean Feature Messaging.Transfer_To_Agent — the master toggle already gating transferToAgent.* above; exposed standalone too.
urgentResponseTime readonly ResponseTimeTarget Site settings messaging.default.response.urgent.time + .time.urgent.unit — urgent-priority SLA response-time target.

AgentIdpCallbackConfig

Properties

Property Type
accountId? string
clientId? string
redirectUri? string
url? string

AgentPermissions

Structured permissions for the authenticated agent, available on SessionObject.permissions after create().

  • actions — whether the agent may invoke each dispatch() action. The mapped type { [K in DispatchAction]: boolean } is TypeScript-enforced: every action must have an entry, so it can never silently drift from the dispatch surface.
  • configuration — derived agent/account capabilities, each built from its real privilege/feature/site-setting combination rather than a flat 1:1 mirror.

Check SessionObject.permissionsReady before trusting these values.

Properties

Property Modifier Type
actions readonly object
actions.account/agent-availability public boolean
actions.account/skill-availability public boolean
actions.account/skills public boolean
actions.account/users public boolean
actions.agent-state/custom-away-reasons public boolean
actions.agent-state/get public boolean
actions.agent-state/set public boolean
actions.conversation/accept public boolean
actions.conversation/chat-state public boolean
actions.conversation/close public boolean
actions.conversation/filter-history-conversations public boolean
actions.conversation/get-consumer-conversations public boolean
actions.conversation/join public boolean
actions.conversation/join-as-reader public boolean
actions.conversation/leave public boolean
actions.conversation/reject public boolean
actions.conversation/resume public boolean
actions.conversation/search-by-id public boolean
actions.conversation/set-sla public boolean
actions.conversation/set-summary-note public boolean
actions.conversation/takeover public boolean
actions.conversation/to-queue public boolean
actions.conversation/transfer public boolean
actions.message/send public boolean
actions.message/status public boolean
actions.messages/query public boolean
actions.profile/get public boolean
actions.profile/set public boolean
configuration readonly AgentConfiguration

AgentProfile

Profile data specific to an Agent.

Extends

  • BaseUserProfile

Indexable

[key: string]: unknown

Catch-all for any other fields returned by UMS.

Properties

Property Modifier Type Description Inherited from
active? readonly boolean Whether the agent account is currently active. -
authenticatedData? readonly Record<string, unknown> Authenticated data associated with the profile. BaseUserProfile.authenticatedData
avatarUrl? readonly string URL to the user's avatar image. BaseUserProfile.avatarUrl
createdTs? readonly number Epoch timestamp (ms) when the profile was created. BaseUserProfile.createdTs
email? readonly string Public email address. BaseUserProfile.email
employeeId? readonly string Internal employee ID. -
firstName? readonly string First name of the user. BaseUserProfile.firstName
id? readonly string Unique identifier for the agent (often matches userId). -
lastUpdatedTs? readonly number Epoch timestamp (ms) when the profile was last updated. BaseUserProfile.lastUpdatedTs
maxSlots? readonly number Maximum number of simultaneous conversations. -
nickName? readonly string Nickname of the user. BaseUserProfile.nickName
permissionGroups? readonly readonly string[] IDs of permission groups assigned to the agent. -
privateData? readonly object Private contact information. BaseUserProfile.privateData
privateData.contacts? readonly readonly Record<string, unknown>[] Private contacts list. -
privateData.email? readonly string Private email address. -
privateData.mail? readonly string Private email address as returned by UMS (the actual wire-format key). -
privateData.mobileNum? readonly string Private mobile number. -
skillIds? readonly readonly string[] IDs of skills assigned to the agent. -
userId? readonly string Unique identifier for the user. BaseUserProfile.userId
userTypeId? readonly number User type identifier. -

AgentSession

Properties

Property Modifier Type Description
accountId readonly string Account ID
agentId readonly string Agent's user ID (accountId.shortId format)
csrf readonly string CSRF token from the Login Service
expiresAt? readonly number Unix epoch seconds when the token expires (if available)
idToken? readonly string Sentinel OIDC id_token JWT (present after IDP auth; contains sub = numeric agentId)
refreshToken? readonly string Sentinel opaque refresh token (present after IDP auth, absent for SSO sessions)
sessionId readonly string LP session ID
token readonly string Bearer token for UMS and REST API requests

AgentStateChangeEvent

Properties

Property Modifier Type
type readonly "agent-state/change"
value readonly AgentStateValue

AgentStateGetAction

Properties

Property Type
action "agent-state/get"
value? undefined

AgentStateSetAction

Properties

Property Type
action "agent-state/set"
value object
value.reasonId? string
value.state "ONLINE" | "AWAY" | "BACK_SOON"

AgentStateValue

Properties

Property Modifier Type Description
agentId readonly string -
reasonId? readonly string The custom away reason's id, when state is 'AWAY' and UMS reports one. '-1' means "no custom reason" (the default). Not present for other states.
state readonly AgentState -

AllConversationsFilter

Properties

Property Type
agentGroupIds? number[]
agentIds? number[]
agentSurveySearch? object
agentSurveySearch.answerKeywords? string[]
agentSurveySearch.pendingAgentSurvey? boolean[]
agentSurveySearch.questionKeywords? string[]
agentSurveySearch.surveyId? string[]
alertedMcsValues? string[]
cappingConfiguration? string
contentToRetrieve? string[]
conversationId? string
csat? TimeRangeFilter
duration? TimeRangeFilter
keyword? string
latestAgentIds? number[]
latestConversationQueueState? string
latestSkillIds? number[]
limit? number
offset? number
responseTime? TimeRangeFilter
sdeSearch? object
sdeSearch.cartStatus? string
sdeSearch.customerInfo? string
sdeSearch.lead? string
sdeSearch.marketingCampaignInfo? string
sdeSearch.personalInfo? string
sdeSearch.purchase? string
sdeSearch.searchContent? string
sdeSearch.serviceActivity? string
sdeSearch.userUpdate? string
sdeSearch.vehicleOfInterest? string
sdeSearch.viewedProduct? string
sdeSearch.visitorError? string
skillIds? string[]
start? TimeRangeFilter
status? string[]
summary? string

AuthErrorEvent

Properties

Property Modifier Type
type readonly "auth/error"
value readonly AuthErrorValue

AuthErrorValue

Properties

Property Modifier Type
code readonly "TOKEN_EXPIRED" | "TOKEN_INVALID" | "REFRESH_FAILED"
message readonly string

AuthSessionTakenOverEvent

Properties

Property Modifier Type
type readonly "auth/session-taken-over"
value readonly object
value.accountId public string
value.clientId public string

CampaignInfo

Properties

Property Modifier Type
campaignId readonly string
engagementId readonly string

ChatStateValue

Properties

Property Modifier Type
conversationId readonly string
participantId readonly string
state readonly "ACTIVE" | "COMPOSING"

ClientProperties

Client/device info UMS attaches to an originator (browser, OS, SDK integration version, enabled features, etc.). The field set varies by client type and UMS may add fields over time without notice, so known fields are documented here while the raw response is preserved via an index signature.

Indexable

[key: string]: unknown

Properties

Property Modifier Type
appId? readonly string
browser? readonly string
browserVersion? readonly string
deviceFamily? readonly string
features? readonly readonly string[]
integration? readonly string
integrationVersion? readonly string
ipAddress? readonly string
os? readonly string
osVersion? readonly string
timeZone? readonly string
type? readonly string

ConnectionStatusEvent

Properties

Property Modifier Type
type readonly "connection/status"
value readonly ConnectionStatusValue

ConnectionStatusValue

Value of the connection/status event — mirrors the SDK transport ConnectionStatus.

Properties

Property Modifier Type Description
attempt? readonly number -
delayMs? readonly number -
reason? readonly string -
reconnected? readonly boolean True when status is connected as the result of a reconnect (not the initial connect).
status readonly "connected" | "reconnecting" | "disconnected" | "failed" -

ConsumerProfile

Profile data specific to a Consumer.

Extends

  • BaseUserProfile

Indexable

[key: string]: unknown

Catch-all for any other fields returned by UMS.

Properties

Property Modifier Type Description Inherited from
acr? readonly string Authentication Context Class Reference. -
authenticatedData? readonly Record<string, unknown> Authenticated data associated with the profile. BaseUserProfile.authenticatedData
avatarUrl? readonly string URL to the user's avatar image. BaseUserProfile.avatarUrl
claims? readonly Record<string, unknown> Authentication claims or Structured Data Entities (e.g. under lp_sdes). -
createdTs? readonly number Epoch timestamp (ms) when the profile was created. BaseUserProfile.createdTs
description? readonly string Public description or bio. -
email? readonly string Public email address. BaseUserProfile.email
firstName? readonly string First name of the user. BaseUserProfile.firstName
lastName? readonly string Last name of the user. -
lastUpdatedTs? readonly number Epoch timestamp (ms) when the profile was last updated. BaseUserProfile.lastUpdatedTs
mobileNumber? readonly string Public mobile phone number. -
nickName? readonly string Nickname of the user. BaseUserProfile.nickName
privateData? readonly object Private contact information. BaseUserProfile.privateData
privateData.contacts? readonly readonly Record<string, unknown>[] Private contacts list. -
privateData.email? readonly string Private email address. -
privateData.mail? readonly string Private email address as returned by UMS (the actual wire-format key). -
privateData.mobileNum? readonly string Private mobile number. -
userId? readonly string Unique identifier for the user. BaseUserProfile.userId

Conversation

Properties

Property Modifier Type
accountId readonly string
campaignInfo? readonly CampaignInfo
createdAt readonly number
id readonly string
lastMessage? readonly LastMessage
lastUpdatedAt readonly number
mainDialog readonly Dialog
note? readonly string
originContext? readonly Record<string, unknown>
postSurveyDialog? readonly Dialog
skillId? readonly string
sla readonly ConversationSla
stage readonly ConversationStage
unreadCount? readonly number

ConversationAcceptAction

Properties

Property Type
action "conversation/accept"
value object
value.conversationId string

ConversationChatStateAction

Properties

Property Type
action "conversation/chat-state"
value object
value.conversationId string
value.state "ACTIVE" | "COMPOSING" | "PAUSE"

ConversationChatStateEvent

Properties

Property Modifier Type
type readonly "conversation/chat-state"
value readonly ChatStateValue

ConversationCloseAction

Properties

Property Type
action "conversation/close"
value string

ConversationEventsInTranscriptPermissions

Which transfer/join/takeover/close event types this agent may see in a conversation transcript. Feature Messaging.Conversation_Events_In_Transcript gates all 7 together; each individual flag is a separate LP privilege on top of that gate.

Properties

Property Modifier Type Description
agentTransfer readonly boolean Privilege 1894 (VIEW_AGENT_TRANSFER_EVENTS_IN_TRANSCRIPT).
autoUnassigned readonly boolean Privilege 1908 (VIEW_CONVERSATION_AUTO_UNASSIGNED_EVENTS_IN_TRANSCRIPT).
backToQueue readonly boolean Privilege 1895 (VIEW_BACK_TO_QUEUE_EVENTS_IN_TRANSCRIPT).
close readonly boolean Privilege 1907 (VIEW_CONVERSATION_CLOSED_EVENTS_IN_TRANSCRIPT).
join readonly boolean Privilege 1896 (VIEW_JOIN_EVENTS_IN_TRANSCRIPT).
skillTransfer readonly boolean Privilege 1893 (VIEW_SKILL_TRANSFER_EVENTS_IN_TRANSCRIPT).
takeover readonly boolean Privilege 1897 (VIEW_TAKEOVER_EVENTS_IN_TRANSCRIPT).

ConversationIdOptions

Properties

Property Type
conversationId string

ConversationJoinAction

Properties

Property Type
action "conversation/join"
value string

ConversationLeaveAction

Properties

Property Type
action "conversation/leave"
value object
value.conversationId string
value.dialogId? string
value.role "MANAGER" | "READER"
value.shouldJoinAsReader? boolean

ConversationRejectAction

Properties

Property Type
action "conversation/reject"
value string

ConversationResumeAction

Properties

Property Type
action "conversation/resume"
value ResumeConversationOptions

ConversationRingEvent

Properties

Property Modifier Type
type readonly "conversation/ring"
value readonly RingValue

ConversationSearchByIdAction

Properties

Property Type
action "conversation/search-by-id"
value object
value.contentToRetrieve? string[]
value.conversationId string

ConversationSearchResult

Properties

Property Type
_metadata? Record<string, unknown>
conversationHistoryRecords Record<string, unknown>[]

ConversationSetSlaAction

Properties

Property Type
action "conversation/set-sla"
value object
value.conversationId string
value.time? number

ConversationSla

Properties

Property Modifier Type Description
isUrgent readonly boolean -
time readonly number Server timestamp (epoch ms) at which the SLA expires; 0 once the conversation is closed, -1 if unknown.
type readonly ConversationSlaType -

ConversationsUpdateEvent

Properties

Property Modifier Type
type readonly "conversations/update"
value readonly ConversationUpdateValue

ConversationTakeoverAction

Properties

Property Type
action "conversation/takeover"
value TakeoverConversationOptions

ConversationToQueueAction

Properties

Property Type
action "conversation/to-queue"
value string

ConversationTransferAction

Properties

Property Type
action "conversation/transfer"
value TransferConversationOptions

ConversationUpdateValue

Properties

Property Modifier Type
conversation readonly Conversation
previousConsumerId? readonly string
type readonly "delete" | "upsert"

CreateResult

Result of MessagingClient.create — the authenticated client and its session.

Properties

Property Modifier Type
client readonly MessagingClient
session readonly SessionObject

CustomAwayReasonOption

Properties

Property Modifier Type
deleted readonly boolean
enabled readonly boolean
id readonly string
state readonly string
text readonly string

CustomAwayReasonsGetAction

Properties

Property Type
action "agent-state/custom-away-reasons"
value? undefined

Dialog

Properties

Property Modifier Type
closedAt? readonly number
createdAt readonly number
id readonly string
messages readonly readonly Message[]
participants readonly readonly Participant[]
state readonly DialogState
type readonly DialogType

DispatchReturnMap

Properties

Property Type
account/agent-availability AgentAvailabilityRecord[]
account/skill-availability Record<number, SkillAvailability>
account/skills Skill[]
account/users AccountUser[]
agent-state/custom-away-reasons CustomAwayReasonOption[]
agent-state/get AgentStateValue
agent-state/set void
conversation/accept void
conversation/chat-state void
conversation/close void
conversation/filter-history-conversations ConversationSearchResult
conversation/get-consumer-conversations ConversationSearchResult
conversation/join void
conversation/join-as-reader void
conversation/leave void
conversation/reject void
conversation/resume string
conversation/search-by-id ConversationSearchResult
conversation/set-sla void
conversation/set-summary-note void
conversation/takeover void
conversation/to-queue void
conversation/transfer void
message/send void
message/status void
messages/query object
messages/query.messages MessageEvent[]
messages/query.statuses Record<number, Record<string, MessageStatus>>
profile/get UserProfile
profile/set void

FilterHistoryConversationsAction

Properties

Property Type
action "conversation/filter-history-conversations"
value? AllConversationsFilter

GetConsumerConversationsAction

Properties

Property Type
action "conversation/get-consumer-conversations"
value object
value.consumerId string
value.contentToRetrieve? string[]
value.status? string[]

GetMessagesOptions

Properties

Property Type
conversationId string
dialogId? string

GetUserProfileOptions

Properties

Property Type
userId? string

HostedFileContent

Properties

Property Modifier Type
caption? readonly string
fileType readonly string
relativePath readonly string
type readonly "file"

InitOptions

Properties

Property Type
accountId string
callbackUrl string
clientId string

LastMessage

Properties

Property Modifier Type
contentType? readonly string
dialogId readonly string
message? readonly string
messageAudience? readonly "ALL" | "AGENTS_AND_MANAGERS"
originatorId readonly string
originatorRole? readonly string
sequence readonly number
serverTimestamp readonly number

Message

Properties

Property Modifier Type
content readonly MessageContent
conversationId readonly string
deliveryStatus? readonly DeliveryStatus
dialogId readonly string
participant readonly Participant
sentAt readonly number
sequence readonly number

MessageEvent

Properties

Property Modifier Type Description
conversationId readonly string -
dialogId readonly string -
event readonly MessageEventPayload -
messageAudience? readonly "ALL" | "AGENTS_AND_MANAGERS" -
metadata? readonly unknown Arbitrary UMS metadata attached to this message event (JsonNode on the wire — shape is not fixed), if any.
originatorClientProperties? readonly ClientProperties Client/device info of the originator, as reported by UMS on this event.
originatorId readonly string -
originatorMetadata? readonly OriginatorMetadata Full originator identity/role/client-properties as reported by UMS on this event.
originatorRole? readonly string The originator's role at the time this event was sent (e.g. CONSUMER, ASSIGNED_AGENT, MANAGER).
sequence readonly number -
serverTimestamp readonly number -

MessageEventPayload

A live inbound or outbound message event on a conversation.

Properties

Property Modifier Type
chatState? readonly string
contentType? readonly string
message? readonly unknown
quickReplies? readonly QuickReplies
sequenceList? readonly number[]
status? readonly MessageStatus
type readonly string

MessageReceiveEvent

Properties

Property Modifier Type
type readonly "message/receive"
value readonly MessageReceiveValue

MessageReceiveValue

Properties

Property Modifier Type Description
content readonly object -
content.content? public Record<string, unknown> -
content.quickReplies? public QuickReplies -
content.text? public string -
content.type public string -
conversationId readonly string -
dialogId readonly string -
messageAudience? readonly "ALL" | "AGENTS_AND_MANAGERS" -
metadata? readonly unknown Arbitrary UMS metadata attached to this message (JsonNode on the wire — shape is not fixed), if any.
originatorClientProperties? readonly ClientProperties Client/device info of the originator, as reported by UMS on this message.
originatorId readonly string -
originatorMetadata? readonly OriginatorMetadata Full originator identity/role/client-properties as reported by UMS on this message.
originatorRole? readonly string The originator's role at the time this message was sent (e.g. CONSUMER, ASSIGNED_AGENT, MANAGER).
sequence readonly number -
serverTimestamp readonly number -

MessageSendAction

Properties

Property Type
action "message/send"
value SendMessageOptions

MessagesQueryAction

Properties

Property Type
action "messages/query"
value GetMessagesOptions

MessageStatusAction

Properties

Property Type
action "message/status"
value object
value.conversationId string
value.sequences number[]
value.status "READ" | "DELIVERED"

MessageStatusReceiveEvent

Properties

Property Modifier Type
type readonly "message/status/receive"
value readonly MessageStatusValue

MessageStatusValue

Properties

Property Modifier Type Description
conversationId readonly string -
participantId readonly string The participant who reported this status (the AcceptStatusEvent originator).
sequences readonly number[] -
status readonly MessageStatus -

OnOptions

Properties

Property Type
callback (event: CallbackEvent) => void

OriginatorMetadata

Identity and client info of the participant who originated a message event.

Properties

Property Modifier Type
clientProperties? readonly ClientProperties
id readonly string
role readonly string

Participant

Properties

Property Modifier Type
id readonly string
role readonly ParticipantRole
state readonly ParticipantState

ProfileGetAction

Properties

Property Type
action "profile/get"
value? GetUserProfileOptions

ProfileSetAction

Properties

Property Type
action "profile/set"
value SetUserProfileOptions

QuickReplies

Properties

Property Modifier Type
itemsPerRow readonly number
replies readonly readonly QuickReplyButton[]
type? readonly "quickReplies"

QuickReplyButton

Indexable

[key: string]: unknown

ResponseTimeTarget

A numeric SLA/response-time target paired with its configured unit.

Exposed as a raw configured value, not an event — see the open thread linked from docs/dispatch-action-permissions.md about whether auto-close/SLA timing should instead be a conversation event the UI reacts to.

Properties

Property Modifier Type
unit readonly string
value readonly number

ResumeConversationOptions

Properties

Property Type Description
brandId string -
campaignInfo? CampaignInfo -
consumerId string -
conversationId string The origin (closed) conversation ID.
message SendMessageOptions Message to send in the newly created conversation.
originContext? Record<string, unknown> -
skillId? number -

RichContent

Properties

Property Modifier Type
content readonly Record<string, any>
quickReplies? readonly QuickReplies
type readonly "rich"

RingValue

Properties

Property Modifier Type
conversationId readonly string
skillId? readonly string

SdkErrorEvent

Properties

Property Modifier Type
type readonly "error"
value readonly object
value.message readonly string

SendChatStateOptions

Properties

Property Type
conversationId string
state "ACTIVE" | "COMPOSING" | "PAUSE"

SendMessageOptions

Properties

Property Type
content MessageSendContent
conversationId string
messageAudience? "ALL" | "AGENTS_AND_MANAGERS"

SendMessageStatusOptions

Properties

Property Type
conversationId string
sequences number[]
status "READ" | "DELIVERED"

SessionEndEvent

Properties

Property Modifier Type
type readonly "session/end"
value readonly object
value.message readonly string

SessionObject

Properties

Property Modifier Type Description
accountId readonly string -
agentId readonly string -
displayName readonly string Agent's full name from LP user record
features readonly Readonly<Record<string, boolean>> Raw AC feature flags for this account (compoundFeatureID → enabled), unfiltered — the same source AgentPermissions.configuration derives its feature-gated fields from. Empty until permissionsReady is true.
loginName readonly string Agent's login name (email) from LP user record
permissions readonly AgentPermissions Structured permissions — populated during create(). Check permissionsReady before trusting these values.
permissionsReady readonly boolean true when account context loaded successfully during create() and permissions reflect real values. false when the fetch failed — all permissions default to false and the UI should warn the user.
privileges readonly readonly number[] Raw LP privilege codes held by this agent (e.g. [10, 1574, 1766]), unfiltered — the same source AgentPermissions.configuration derives its privilege-gated fields from. Empty until permissionsReady is true.
roles readonly string[] Agent role names e.g. ['Agent'] or ['Agent Manager']
siteSettings readonly Readonly<Record<string, string>> Raw site settings for this account (dotted key → string value), unfiltered — the same source AgentPermissions.configuration's settings fields are coerced from. Empty until permissionsReady is true.

SetAgentStateOptions

Properties

Property Type Description
reasonId? string Only meaningful when state is 'AWAY'; ignored otherwise.
state "ONLINE" | "AWAY" | "BACK_SOON" 'OFFLINE' is intentionally omitted — agents cannot set themselves offline via the SDK.

SetSummaryNoteAction

Properties

Property Type
action "conversation/set-summary-note"
value object
value.conversationId string
value.note string

SetUserProfileOptions

Properties

Property Type
avatarUrl? string
backgndImgUri? string
description? string
email? string
firstName? string
lastName? string
phone? string
userId string

Skill

Properties

Property Type
canTransfer boolean
dateUpdated string
deleted boolean
description string
id number
maxWaitTime number
name string
skillOrder number
skillRoutingConfiguration unknown[]

SkillAvailability

Live online/away agent counts for a single skill, from the Manager Workspace availability API.

Properties

Property Modifier Type
awayAgents? readonly number
onlineAgents readonly number

SkillAvailabilityGetAction

Properties

Property Type
action "account/skill-availability"
value? undefined

SkillsGetAction

Properties

Property Type
action "account/skills"
value? undefined

SmartCapacityPerSkill

Parsed value of site setting messaging.smart.capacity.per.skill.definition.

Properties

Property Modifier Type
smartCapacityParametersList readonly readonly SmartCapacitySkillOverride[]

SmartCapacitySkillOverride

One skill's smart-capacity override, from site setting messaging.smart.capacity.per.skill.definition.

Properties

Property Modifier Type
skillId readonly number
smartCapacityFreshAgentPendingTimeSec readonly number

TakeoverConversationOptions

Properties

Property Type Description
agentId string Fully-qualified accountId.agentId of the agent taking over as ASSIGNED_AGENT.
conversationId string -
dialogId string -
ownerId string | undefined Fully-qualified accountId.agentId of the current assigned agent being removed.

TextContent

Properties

Property Modifier Type
quickReplies? readonly QuickReplies
text readonly string
type readonly "text"

TimeRangeFilter

Properties

Property Type
from number
to number

TransferConversationOptions

Properties

Property Type Description
conversationId string -
metadata? object[] UMS metadata to attach to the transfer request (e.g. ActionReason).
target | { id: string; type: "skill"; } | { id: string; skillId?: string; type: "agent"; } -

TransferToAgentPermissions

Per-target-status transfer-to-agent access, derived from LP privileges 1766/1767/1768.

Properties

Property Modifier Type Description
away readonly boolean Privilege 1767 (TRANSFER_TO_AWAY_AGENT).
backSoon readonly boolean Same privilege as online — LP does not distinguish online from back-soon targets.
offline readonly boolean Privilege 1768 (TRANSFER_TO_OFFLINE_AGENT).
online readonly boolean Privilege 1766 (TRANSFER_TO_ONLINE_AND_BACK_SOON_AGENT).

UserConfigurationAgentGroup

Properties

Property Type
agentGroupId number
assignmentDate string

Type Aliases

AgentState

type AgentState = "ONLINE" | "OFFLINE" | "AWAY" | "BACK_SOON";

CallbackEvent

type CallbackEvent = 
  | ConnectionStatusEvent
  | AuthErrorEvent
  | AuthSessionTakenOverEvent
  | SdkErrorEvent
  | SessionEndEvent
  | ConversationsUpdateEvent
  | ConversationRingEvent
  | AgentStateChangeEvent
  | MessageReceiveEvent
  | ConversationChatStateEvent
  | MessageStatusReceiveEvent;

A typed SDK callback event delivered to the on({ callback }) handler.

Narrow on type to access the strongly-typed value:

ConnectionStatus

type ConnectionStatus = 
  | {
  status: "connected";
}
  | {
  attempt: number;
  delayMs: number;
  status: "reconnecting";
}
  | {
  reason: string;
  status: "disconnected";
}
  | {
  attempts: number;
  lastError: Error;
  status: "failed";
};

ConversationSlaType

type ConversationSlaType = "manual" | "auto";

ConversationStage

type ConversationStage = "OPEN" | "CLOSE";

DeliveryStatus

type DeliveryStatus = "SENT" | "ACCEPT" | "READ";

DialogState

type DialogState = "OPEN" | "CLOSE";

DialogType

type DialogType = "MAIN" | "POST_SURVEY" | "OTHER";

DispatchAction

type DispatchAction = DispatchPayload["action"];

Union of every valid dispatch() action key.

DispatchPayload

type DispatchPayload = 
  | AgentStateGetAction
  | AgentStateSetAction
  | ConversationAcceptAction
  | ConversationChatStateAction
  | ConversationCloseAction
  | ConversationJoinAction
  | ConversationLeaveAction
  | ConversationJoinAsReaderAction
  | ConversationRejectAction
  | ConversationToQueueAction
  | MessageSendAction
  | MessageStatusAction
  | MessagesQueryAction
  | ConversationResumeAction
  | ProfileGetAction
  | ProfileSetAction
  | ConversationSearchByIdAction
  | GetConsumerConversationsAction
  | ConversationTransferAction
  | SkillsGetAction
  | AccountUsersGetAction
  | SkillAvailabilityGetAction
  | AgentAvailabilityGetAction
  | SetSummaryNoteAction
  | FilterHistoryConversationsAction
  | CustomAwayReasonsGetAction
  | ConversationTakeoverAction
  | ConversationSetSlaAction;

The unified action payload dispatched from the UI to the SDK.

Supports the following actions:

MESSAGE_STATUS_LEVELS

type MESSAGE_STATUS_LEVELS = Record<MessageStatus, number>;

Monotonic ranking used to resolve multiple statuses on the same (sequence, participant): the higher level wins and status never downgrades. ERROR/NACK intentionally outrank READ/VIEWED so a delivery failure supersedes a read state. COMMAND_* are command results, not delivery levels — given a level only so the map is total over MessageStatus.

MessageContent

type MessageContent = 
  | TextContent
  | RichContent
  | HostedFileContent;

MessageSendContent

type MessageSendContent = 
  | {
  quickReplies?: QuickReplies;
  text: string;
  type: "text";
}
  | {
  content: Record<string, unknown>;
  quickReplies?: QuickReplies;
  type: "rich";
};

MessageStatus

type MessageStatus = 
  | "LOADING"
  | "SENT"
  | "ACCEPT"
  | "READ"
  | "VIEWED"
  | "ERROR"
  | "NACK"
  | "COMMAND_ERROR"
  | "COMMAND_SUCCESS";

Inbound message acknowledgement status, as reported by UMS on AcceptStatusEvent. Mirrors the Agent Workspace status vocabulary. The SDK passes through whatever UMS sends.

Statuses are ordered from lowest to highest delivery level — use MESSAGE_STATUS_LEVELS to compare them numerically.

Value Meaning
LOADING Being sent by the client
SENT Accepted by the server
ACCEPT Delivered to the consumer device (equivalent to DELIVERED in outbound requests)
READ Read by the consumer
VIEWED Viewed (Rich Content)
ERROR Failed to send
NACK Negative acknowledgement from the server
COMMAND_ERROR UMS command failed
COMMAND_SUCCESS UMS command succeeded

Note: the outbound request vocabulary (sendMessageStatus) uses 'READ' | 'DELIVERED', which is distinct — DELIVERED maps to the inbound ACCEPT.

ParticipantRole

type ParticipantRole = "CONSUMER" | "ASSIGNED_AGENT" | "MANAGER" | "SYSTEM" | "READER";

ParticipantState

type ParticipantState = "ACTIVE" | "INACTIVE";

UserProfile

type UserProfile = ConsumerProfile & AgentProfile;

Unified profile data for an agent or consumer, as returned by the backend (WS or REST), with no field curation. The WS and REST paths, and consumer vs. agent profiles, don't all return the same fields, and UMS may add fields over time without notice.

This interface provides documentation for known fields while maintaining the raw response via an index signature.

Functions

completeAgentIdpAuth()

function completeAgentIdpAuth(config?: AgentIdpCallbackConfig): Promise<AgentSession>;

Parameters

Parameter Type
config AgentIdpCallbackConfig

Returns

Promise<AgentSession>