@microsoft/omnichannel-chat-sdk 1.11.9-main.e5288e0 → 2.0.0-main.3932063
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +84 -11
- package/lib/OmnichannelChatSDK.d.ts +38 -0
- package/lib/OmnichannelChatSDK.js +273 -39
- package/lib/OmnichannelChatSDK.js.map +1 -1
- package/lib/config/settings.d.ts +2 -2
- package/lib/config/settings.js +2 -2
- package/lib/config/settings.js.map +1 -1
- package/lib/core/ChatSDKError.d.ts +11 -1
- package/lib/core/ChatSDKError.js +10 -0
- package/lib/core/ChatSDKError.js.map +1 -1
- package/lib/core/ChatSDKExceptionDetails.d.ts +6 -0
- package/lib/core/StartChatOptionalParams.d.ts +10 -0
- package/lib/core/messaging/ACSClient.d.ts +7 -0
- package/lib/core/messaging/ACSClient.js +216 -12
- package/lib/core/messaging/ACSClient.js.map +1 -1
- package/lib/core/messaging/OmnichannelStreamingMessage.d.ts +13 -0
- package/lib/core/messaging/OmnichannelStreamingMessage.js +3 -0
- package/lib/core/messaging/OmnichannelStreamingMessage.js.map +1 -0
- package/lib/core/messaging/OnStreamingMessageOptionalParams.d.ts +8 -0
- package/lib/core/messaging/OnStreamingMessageOptionalParams.js +3 -0
- package/lib/core/messaging/OnStreamingMessageOptionalParams.js.map +1 -0
- package/lib/core/messaging/PolicyViolation.d.ts +8 -0
- package/lib/core/messaging/PolicyViolation.js +3 -0
- package/lib/core/messaging/PolicyViolation.js.map +1 -0
- package/lib/core/messaging/StreamingMetadata.d.ts +11 -0
- package/lib/core/messaging/StreamingMetadata.js +3 -0
- package/lib/core/messaging/StreamingMetadata.js.map +1 -0
- package/lib/index.d.ts +5 -1
- package/lib/index.js.map +1 -1
- package/lib/telemetry/MessageSource.d.ts +1 -0
- package/lib/telemetry/MessageSource.js +1 -0
- package/lib/telemetry/MessageSource.js.map +1 -1
- package/lib/telemetry/TelemetryEvent.d.ts +23 -1
- package/lib/telemetry/TelemetryEvent.js +23 -0
- package/lib/telemetry/TelemetryEvent.js.map +1 -1
- package/lib/tsconfig.tsbuildinfo +1 -1
- package/lib/utils/createOmnichannelMessage.js +27 -1
- package/lib/utils/createOmnichannelMessage.js.map +1 -1
- package/lib/utils/createOmnichannelStreamingMessage.d.ts +14 -0
- package/lib/utils/createOmnichannelStreamingMessage.js +106 -0
- package/lib/utils/createOmnichannelStreamingMessage.js.map +1 -0
- package/lib/utils/errorClassifier.d.ts +25 -0
- package/lib/utils/errorClassifier.js +75 -0
- package/lib/utils/errorClassifier.js.map +1 -0
- package/lib/utils/exceptionThrowers.d.ts +38 -4
- package/lib/utils/exceptionThrowers.js +25 -8
- package/lib/utils/exceptionThrowers.js.map +1 -1
- package/lib/utils/printers/MessagePrinterFactory.d.ts +3 -2
- package/lib/utils/printers/MessagePrinterFactory.js +6 -0
- package/lib/utils/printers/MessagePrinterFactory.js.map +1 -1
- package/lib/utils/printers/StreamingMessagePrinter.d.ts +5 -0
- package/lib/utils/printers/StreamingMessagePrinter.js +33 -0
- package/lib/utils/printers/StreamingMessagePrinter.js.map +1 -0
- package/lib/utils/printers/types/MessageType.d.ts +2 -1
- package/package.json +14 -8
package/README.md
CHANGED
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://badge.fury.io/js/%40microsoft%2Fomnichannel-chat-sdk)
|
|
4
4
|
[](https://packagephobia.com/result?p=@microsoft/omnichannel-chat-sdk)
|
|
5
|
-
](https://github.com/microsoft/omnichannel-chat-sdk/actions/workflows/npm-release.yml)
|
|
6
6
|

|
|
7
7
|
|
|
8
|
-
>
|
|
9
|
-
|
|
10
|
-
>
|
|
8
|
+
> [!IMPORTANT]
|
|
9
|
+
> * We recommend using official release versions in production as listed [here](#releases). Support will be provided only on official versions.
|
|
10
|
+
> * Microsoft provides this SDK to ensure a scaleable and secure use of our platform. Do not directly access the APIs used in this repository — you may experience breaking changes, and we will not be able to provide support for any issues.
|
|
11
11
|
|
|
12
12
|
Headless Chat SDK to build your own chat widget against Dynamics 365 Omnichannel Services.
|
|
13
13
|
|
|
@@ -34,6 +34,7 @@ Please make sure you have a chat widget configured before using this package or
|
|
|
34
34
|
- [Get Messages](#get-messages)
|
|
35
35
|
- [Send Messages](#send-messages)
|
|
36
36
|
- [On New Message](#on-new-message)
|
|
37
|
+
- [On Streaming Message](#on-streaming-message)
|
|
37
38
|
- [On Typing Event](#on-typing-event)
|
|
38
39
|
- [On Agent End Session](#on-agent-end-session)
|
|
39
40
|
- [Send Typing Event](#send-typing-event)
|
|
@@ -45,6 +46,8 @@ Please make sure you have a chat widget configured before using this package or
|
|
|
45
46
|
- [Get Voice & Video Calling](#get-voice--video-calling)
|
|
46
47
|
- [Get Post Chat Survey Context](#get-post-chat-survey-context)
|
|
47
48
|
- [Get Persistent Chat History](#get-persistent-chat-history)
|
|
49
|
+
- [Send Read Receipt](#send-read-receipt)
|
|
50
|
+
- [Get Unread Message Count](#get-unread-message-count)
|
|
48
51
|
- [Common Scenarios](#common-scenarios)
|
|
49
52
|
- [Using BotFramework-WebChat](#using-botframework-webchat)
|
|
50
53
|
- [Escalation to Voice & Video](#escalation-to-voice--video)
|
|
@@ -56,7 +59,7 @@ Please make sure you have a chat widget configured before using this package or
|
|
|
56
59
|
- [Persistent Chat History](#persistent-chat-history)
|
|
57
60
|
- [Chat Reconnect with Authenticated User](#chat-reconnect-with-authenticated-user)
|
|
58
61
|
- [Chat Reconnect with Unauthenticated User](#chat-reconnect-with-unauthenticated-user)
|
|
59
|
-
- [Best Practices for Chat Session Management: Handling Disconnections and Network
|
|
62
|
+
- [Best Practices for Chat Session Management: Handling Disconnections and Network Instability](#best-practices-for-chat-session-management-handling-disconnections-and-network-instability)
|
|
60
63
|
- [Operating Hours](#operating-hours)
|
|
61
64
|
- [Single Sign-on for Bots](/docs/scenarios/SINGLE_SIGN_ON_FOR_BOTS.md)
|
|
62
65
|
- [Sample Apps](https://github.com/microsoft/omnichannel-chat-sdk-samples)
|
|
@@ -106,22 +109,39 @@ Omnichannel offers a live chat widget (LCW) by default. You can use the Chat SDK
|
|
|
106
109
|
|
|
107
110
|
New releases are published on a regular basis to ensure the product quality.
|
|
108
111
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
_**Important Note:**_ Versions below 1.11.0 will not be supported after November 1st, 2025. Please update to recent versions to ensure you have the latest features and bug fixes.
|
|
112
|
+
For a detailed tracking of the releases, please refer to the [Changelog document](https://github.com/microsoft/omnichannel-chat-sdk/blob/main/CHANGELOG.md)
|
|
112
113
|
|
|
114
|
+
_**Important Note:**_ Versions below 1.11.0 are no longer supported after November 1st, 2025. Please update to recent versions to ensure you have the latest features and bug fixes.
|
|
113
115
|
|
|
114
116
|
| Version | Docs | Release Date | End of Support | Deprecated |
|
|
115
117
|
| -- | -- | -- | -- | -- |
|
|
118
|
+
| 2.0.0 | [Migration Guide](docs/MIGRATION_2.0.md) / [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v2.0.0) | Aug 13th 2026 | Aug 13th 2027 | |
|
|
116
119
|
| 1.11.4 | [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v1.11.4) | Jul 17th 2025 | Jul 17th 2026 | |
|
|
117
120
|
| 1.11.3 | [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v1.11.3) | Jul 14th 2025 | Jul 14th 2026 | |
|
|
118
121
|
| 1.11.2 | [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v1.11.2) | Jun 24th 2025 | Jun 24th 2026 | |
|
|
119
122
|
| 1.11.1 | [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v1.11.1) | Jun 5th 2025 | Jun 5th 2026 | |
|
|
120
123
|
| 1.11.0 | [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v1.11.0) | May 27th 2025 | May 27th 2026 | |
|
|
121
124
|
|
|
125
|
+
### Upgrade to 2.0.0
|
|
126
|
+
|
|
127
|
+
Version `2.0.0` requires Node.js `>=22.12.0`. This requirement also applies to the official OC SDK and AMS client dependencies.
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
npm install @microsoft/omnichannel-chat-sdk@2.0.0 --save-exact
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The npm `latest` dist-tag can point to a `main` prerelease. Use the exact version for production.
|
|
134
|
+
|
|
135
|
+
Regenerate the application lockfile after the update. Then run the application build and tests on Node.js 22.
|
|
136
|
+
|
|
137
|
+
Version `2.0.0` adds progressive bot-message streaming, read receipts, and unread-message counts. Existing `onNewMessage` handlers continue to receive final streaming messages.
|
|
138
|
+
|
|
139
|
+
See the [2.0 migration guide](docs/MIGRATION_2.0.md) for the complete upgrade and validation procedure.
|
|
122
140
|
|
|
123
141
|
## Installation
|
|
124
142
|
|
|
143
|
+
Node.js `>=22.12.0` is required.
|
|
144
|
+
|
|
125
145
|
```console
|
|
126
146
|
npm install @microsoft/omnichannel-chat-sdk --save
|
|
127
147
|
```
|
|
@@ -454,6 +474,38 @@ chatSDK.onNewMessage((message) => {
|
|
|
454
474
|
}, optionalParams);
|
|
455
475
|
```
|
|
456
476
|
|
|
477
|
+
### On Streaming Message
|
|
478
|
+
|
|
479
|
+
It subscribes to progressive ACS bot-message updates.
|
|
480
|
+
|
|
481
|
+
Enable streaming when you start the conversation. Then register the handler after `startChat()` completes.
|
|
482
|
+
|
|
483
|
+
```ts
|
|
484
|
+
await chatSDK.initialize();
|
|
485
|
+
await chatSDK.startChat({
|
|
486
|
+
supportsLcwStreaming: true
|
|
487
|
+
});
|
|
488
|
+
|
|
489
|
+
await chatSDK.onStreamingMessage((message) => {
|
|
490
|
+
const { streamingMessageType, streamEndReason } = message.streamingMetadata;
|
|
491
|
+
|
|
492
|
+
// Each event contains the full assembled content, not only the new text.
|
|
493
|
+
renderStreamingMessage(message.id, message.content);
|
|
494
|
+
|
|
495
|
+
if (message.policyViolation) {
|
|
496
|
+
handlePolicyViolation(message.policyViolation.result);
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
if (streamingMessageType === "final") {
|
|
500
|
+
completeStreamingMessage(message.id, streamEndReason);
|
|
501
|
+
}
|
|
502
|
+
});
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
`streamingMessageType` can be `start`, `informative`, `streaming`, or `final`. A final message also reaches existing `onNewMessage` handlers.
|
|
506
|
+
|
|
507
|
+
Calling this method before `startChat()` throws `UninitializedConversation`. If the conversation does not use ACS, this method throws `UnsupportedLiveChatVersion`.
|
|
508
|
+
|
|
457
509
|
### On Typing Event
|
|
458
510
|
|
|
459
511
|
It subscribes to an agent typing event.
|
|
@@ -607,6 +659,27 @@ It gets information on whether a queue is available, and whether there are agent
|
|
|
607
659
|
const agentAvailability = await chatSDK.getAgentAvailability();
|
|
608
660
|
```
|
|
609
661
|
|
|
662
|
+
### Send Read Receipt
|
|
663
|
+
|
|
664
|
+
Logs a particular message (and all previous messages) as read by the user. Read indicators will appear for Contact Center Representatives and Admins in the Admin Center.
|
|
665
|
+
|
|
666
|
+
Authenticated chat sends the receipt through Messaging Runtime. Unauthenticated chat sends the receipt through ACS.
|
|
667
|
+
|
|
668
|
+
```ts
|
|
669
|
+
await chatSDK.sendReadReceipt(messageId: string);
|
|
670
|
+
```
|
|
671
|
+
|
|
672
|
+
### Get Unread Message Count
|
|
673
|
+
|
|
674
|
+
Returns unread-message data for an authenticated user. An active chat session is not required. This call is **authenticated-only** — the user must be authenticated, otherwise an `UndefinedAuthToken` error is thrown.
|
|
675
|
+
|
|
676
|
+
```ts
|
|
677
|
+
const response = await chatSDK.getUnreadMessageCount();
|
|
678
|
+
|
|
679
|
+
// response.unreadMessageCount: number — Number of unread messages in the conversation
|
|
680
|
+
// response.mostRecentUnreadMessage: object | null — The most recent unread message, or null if there are none
|
|
681
|
+
```
|
|
682
|
+
|
|
610
683
|
## Common Scenarios
|
|
611
684
|
|
|
612
685
|
### Pre-Chat Survey
|
|
@@ -1302,11 +1375,11 @@ const chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, cha
|
|
|
1302
1375
|
await chatSDK.initialize();
|
|
1303
1376
|
```
|
|
1304
1377
|
|
|
1305
|
-
|
|
1378
|
+
## Releasing
|
|
1306
1379
|
|
|
1307
|
-
See [docs/RELEASING.md](docs/RELEASING.md) for
|
|
1380
|
+
See [docs/RELEASING.md](docs/RELEASING.md) for development builds, official npm and GitHub releases, release notes, and hotfixes.
|
|
1308
1381
|
|
|
1309
|
-
|
|
1382
|
+
## Contributing
|
|
1310
1383
|
|
|
1311
1384
|
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
|
1312
1385
|
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
|
|
@@ -30,7 +30,9 @@ import InitializeOptionalParams from "./core/InitializeOptionalParams";
|
|
|
30
30
|
import LiveWorkItemDetails from "./core/LiveWorkItemDetails";
|
|
31
31
|
import OmnichannelConfig from "./core/OmnichannelConfig";
|
|
32
32
|
import OmnichannelMessage from "./core/messaging/OmnichannelMessage";
|
|
33
|
+
import OmnichannelStreamingMessage from "./core/messaging/OmnichannelStreamingMessage";
|
|
33
34
|
import OnNewMessageOptionalParams from "./core/messaging/OnNewMessageOptionalParams";
|
|
35
|
+
import OnStreamingMessageOptionalParams from "./core/messaging/OnStreamingMessageOptionalParams";
|
|
34
36
|
import PostChatContext from "./core/PostChatContext";
|
|
35
37
|
import StartChatOptionalParams from "./core/StartChatOptionalParams";
|
|
36
38
|
declare class OmnichannelChatSDK {
|
|
@@ -171,7 +173,36 @@ declare class OmnichannelChatSDK {
|
|
|
171
173
|
sendMessage(message: ChatSDKMessage): Promise<OmnichannelMessage | void>;
|
|
172
174
|
onNewMessage(onNewMessageCallback: CallableFunction, optionalParams?: OnNewMessageOptionalParams): Promise<void>;
|
|
173
175
|
sendTypingEvent(): Promise<void>;
|
|
176
|
+
/**
|
|
177
|
+
* Fetches unread message count for the authenticated user.
|
|
178
|
+
* Auth-only — does not require an active chat session.
|
|
179
|
+
*/
|
|
180
|
+
getUnreadMessageCount(): Promise<object>;
|
|
181
|
+
/**
|
|
182
|
+
* Sends a read receipt for a specific message.
|
|
183
|
+
* Authenticated: calls MRT (updates NRD + forwards to ACS).
|
|
184
|
+
* Unauthenticated: calls ACS directly.
|
|
185
|
+
*/
|
|
186
|
+
sendReadReceipt(messageId: string): Promise<void>;
|
|
174
187
|
onTypingEvent(onTypingEventCallback: CallableFunction): Promise<void>;
|
|
188
|
+
/**
|
|
189
|
+
* Subscribes to ACS-driven streaming message chunks for progressive bot message rendering.
|
|
190
|
+
* Each chunk contains the full assembled text so far (not just the delta).
|
|
191
|
+
* Existing onNewMessage consumers continue receiving final messages without changes.
|
|
192
|
+
*
|
|
193
|
+
* Available only in LiveChatVersion.V2. Must call startChat() before registering.
|
|
194
|
+
*
|
|
195
|
+
* @param onStreamingMessageCallback - Called for each streaming chunk
|
|
196
|
+
* @param optionalParams - Reserved for future configuration
|
|
197
|
+
* @example
|
|
198
|
+
* chatSDK.onStreamingMessage((message) => {
|
|
199
|
+
* switch (message.streamingMetadata.streamingMessageType) {
|
|
200
|
+
* case "streaming": // Update bubble with message.content
|
|
201
|
+
* case "final": // Stream complete
|
|
202
|
+
* }
|
|
203
|
+
* });
|
|
204
|
+
*/
|
|
205
|
+
onStreamingMessage(onStreamingMessageCallback: (message: OmnichannelStreamingMessage) => void, optionalParams?: OnStreamingMessageOptionalParams): Promise<void>;
|
|
175
206
|
onAgentEndSession(onAgentEndSessionCallback: (message: IRawThread | ParticipantsRemovedEvent) => void): Promise<void>;
|
|
176
207
|
uploadFileAttachment(fileInfo: IFileInfo | File): Promise<UploadFileAttachmentResponse>;
|
|
177
208
|
downloadFileAttachment(fileMetadata: FileMetadata | IFileMetadata): Promise<Blob>;
|
|
@@ -198,6 +229,13 @@ declare class OmnichannelChatSDK {
|
|
|
198
229
|
private setCallingOptionConfiguration;
|
|
199
230
|
private setLiveChatVersionConfiguration;
|
|
200
231
|
private setWidgetSnippetBaseUrl;
|
|
232
|
+
/**
|
|
233
|
+
* Creates diagnostic data for getChatConfig errors using the error classifier
|
|
234
|
+
* @param e The error object
|
|
235
|
+
* @param clientElapsedMs Optional elapsed time in milliseconds from client's perspective
|
|
236
|
+
* @returns Diagnostic data with clientElapsedMs, online status, and cancellation reason
|
|
237
|
+
*/
|
|
238
|
+
private createGetChatConfigDiagnosticData;
|
|
201
239
|
private getChatConfig;
|
|
202
240
|
private buildConfigurations;
|
|
203
241
|
private resolveIC3ClientUrl;
|