@microsoft/omnichannel-chat-sdk 1.10.16 → 1.10.17-main.243dcc1
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 +89 -69
- package/lib/OmnichannelChatSDK.d.ts +3 -1
- package/lib/OmnichannelChatSDK.js +122 -59
- package/lib/OmnichannelChatSDK.js.map +1 -1
- package/lib/core/ChatSDKError.d.ts +5 -2
- package/lib/core/ChatSDKError.js +3 -1
- package/lib/core/ChatSDKError.js.map +1 -1
- package/lib/core/messaging/ACSClient.js +0 -1
- package/lib/core/messaging/ACSClient.js.map +1 -1
- package/lib/tsconfig.tsbuildinfo +1 -1
- package/lib/utils/exceptionThrowers.d.ts +1 -0
- package/lib/utils/exceptionThrowers.js +7 -4
- package/lib/utils/exceptionThrowers.js.map +1 -1
- package/package.json +4 -3
package/README.md
CHANGED
@@ -14,48 +14,49 @@ Headless Chat SDK to build your own chat widget against Dynamics 365 Omnichannel
|
|
14
14
|
Please make sure you have a chat widget configured before using this package or you can follow this [link](https://docs.microsoft.com/en-us/dynamics365/customer-service/add-chat-widget)
|
15
15
|
|
16
16
|
## Table of Contents
|
17
|
+
|
17
18
|
- [Live Chat Widget vs. Chat SDK](#live-chat-widget-vs-chat-sdk)
|
18
19
|
- [Releases](#releases)
|
19
20
|
- [Installation](#installation)
|
20
21
|
- [Installation on React Native](#installation-on-react-native)
|
21
22
|
- [SDK Methods](#sdk-methods)
|
22
|
-
|
23
|
-
|
24
|
-
|
25
|
-
|
26
|
-
|
27
|
-
|
28
|
-
|
29
|
-
|
30
|
-
|
31
|
-
|
32
|
-
|
33
|
-
|
34
|
-
|
35
|
-
|
36
|
-
|
37
|
-
|
38
|
-
|
39
|
-
|
40
|
-
|
41
|
-
|
42
|
-
|
43
|
-
|
44
|
-
|
45
|
-
|
23
|
+
- [Initialization](#initialization)
|
24
|
+
- [Start Chat](#start-chat)
|
25
|
+
- [End Chat](#end-chat)
|
26
|
+
- [Get Pre-Chat Survey](#get-pre-chat-survey)
|
27
|
+
- [Get Live Chat Config](#get-live-chat-config)
|
28
|
+
- [Get Current Live Chat Context](#get-current-live-chat-context)
|
29
|
+
- [Get Data Masking Rules](#get-data-masking-rules)
|
30
|
+
- [Get Chat Reconnect Context](#get-chat-reconnect-context)
|
31
|
+
- [Get Conversation Details](#get-conversation-details)
|
32
|
+
- [Get Chat Token](#get-chat-token)
|
33
|
+
- [Get Calling Token](#get-calling-token)
|
34
|
+
- [Get Messages](#get-messages)
|
35
|
+
- [Send Messages](#send-messages)
|
36
|
+
- [On New Message](#on-new-message)
|
37
|
+
- [On Typing Event](#on-typing-event)
|
38
|
+
- [On Agent End Session](#on-agent-end-session)
|
39
|
+
- [Send Typing Event](#send-typing-event)
|
40
|
+
- [Email Live Chat Transcript](#email-live-chat-transcript)
|
41
|
+
- [Get Live Chat Transcript](#get-live-chat-transcript)
|
42
|
+
- [Upload File Attachment](#upload-file-attachment)
|
43
|
+
- [Download File Attachment](#download-file-attachment)
|
44
|
+
- [Create Chat Adapter](#create-chat-adapter)
|
45
|
+
- [Get Voice & Video Calling](#get-voice--video-calling)
|
46
|
+
- [Get Post Chat Survey Context](#get-post-chat-survey-context)
|
46
47
|
- [Common Scenarios](#common-scenarios)
|
47
|
-
|
48
|
-
|
49
|
-
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
48
|
+
- [Using BotFramework-WebChat](#using-botframework-webchat)
|
49
|
+
- [Escalation to Voice & Video](#escalation-to-voice--video)
|
50
|
+
- [Pre-Chat Survey](#pre-chat-survey)
|
51
|
+
- [Post-Chat Survey](#post-chat-survey)
|
52
|
+
- [Reconnect to existing Chat](#reconnect-to-existing-chat)
|
53
|
+
- [Authenticated Chat](#authenticated-chat)
|
54
|
+
- [Persistent Chat](#persistent-chat)
|
55
|
+
- [Chat Reconnect with Authenticated User](#chat-reconnect-with-authenticated-user)
|
56
|
+
- [Chat Reconnect with Unauthenticated User](#chat-reconnect-with-unauthenticated-user)
|
57
|
+
- [Handling chat Disconnect on Mobile platform](#handling-chat-disconnect-on-mobile-platform)
|
58
|
+
- [Operating Hours](#operating-hours)
|
59
|
+
- [Single Sign-on for Bots](/docs/scenarios/SINGLE_SIGN_ON_FOR_BOTS.md)
|
59
60
|
- [Sample Apps](https://github.com/microsoft/omnichannel-chat-sdk-samples)
|
60
61
|
- [Feature Comparisons](#feature-comparisons)
|
61
62
|
- [Telemetry](#telemetry)
|
@@ -65,6 +66,7 @@ Please make sure you have a chat widget configured before using this package or
|
|
65
66
|
## Live Chat Widget vs. Chat SDK
|
66
67
|
|
67
68
|
Omnichannel offers a live chat widget (LCW) by default. You can use the Chat SDK to build your custom chat widget if:
|
69
|
+
|
68
70
|
- You want to fully customize the user interface of the chat widget to conform with your branding.
|
69
71
|
- You want to integrate Omnichannel into your mobile app using React Native.
|
70
72
|
- You want to integrate additional functionalities that LCW does not offer.
|
@@ -75,24 +77,24 @@ Omnichannel offers a live chat widget (LCW) by default. You can use the Chat SDK
|
|
75
77
|
| Feature | Live Chat Widget | Chat SDK | Notes |
|
76
78
|
| ----- | ----- | ----- | ----- |
|
77
79
|
| Bring Your Own Widget | ❌ | ✔ | |
|
78
|
-
| Web Support | ✔ | ✔
|
79
|
-
| React Native Support | ❌ | ✔ |
|
80
|
+
| Web Support | ✔ | ✔ ||
|
81
|
+
| React Native Support | ❌ | ✔ | |
|
80
82
|
| Escalation to Voice & Video | ✔ | ✔ | Only supported on Web |
|
81
83
|
| Co-browse | ✔ | 3rd party add-on | Only supported on Web |
|
82
84
|
| Screen Sharing | ✔ | 3rd party add-on | Only supported on Web |
|
83
|
-
| Authenticated Chat | ✔ | ✔ |
|
84
|
-
| Pre-chat Survey | ✔ | ✔ |
|
85
|
-
| Post-chat Survey | ✔ | ✔ |
|
86
|
-
| Download Transcript | ✔ | ✔ |
|
87
|
-
| Email Transcript | ✔ | ✔ |
|
88
|
-
| Data Masking | ✔ | ✔ |
|
89
|
-
| File Attachments | ✔ | ✔ |
|
90
|
-
| Custom Context | ✔ | ✔ |
|
91
|
-
| Proactive Chat | ✔ | BYOI **\*** |
|
92
|
-
| Persistent Chat | ✔ | ✔ |
|
93
|
-
| Chat Reconnect | ✔ | ✔ |
|
94
|
-
| Operating Hours | ✔ | ✔ |
|
95
|
-
| Get Agent Availability | ✔ | ✔ |
|
85
|
+
| Authenticated Chat | ✔ | ✔ | |
|
86
|
+
| Pre-chat Survey | ✔ | ✔ | |
|
87
|
+
| Post-chat Survey | ✔ | ✔ | |
|
88
|
+
| Download Transcript | ✔ | ✔ | |
|
89
|
+
| Email Transcript | ✔ | ✔ | |
|
90
|
+
| Data Masking | ✔ | ✔ | |
|
91
|
+
| File Attachments | ✔ | ✔ | |
|
92
|
+
| Custom Context | ✔ | ✔ | |
|
93
|
+
| Proactive Chat | ✔ | BYOI **\*** | |
|
94
|
+
| Persistent Chat | ✔ | ✔ | |
|
95
|
+
| Chat Reconnect | ✔ | ✔ | |
|
96
|
+
| Operating Hours | ✔ | ✔ | |
|
97
|
+
| Get Agent Availability | ✔ | ✔ | |
|
96
98
|
| Queue Position | ✔ | ✔ | No SDK method. Handled as *system message* |
|
97
99
|
| Average Wait Time | ✔ | ✔ | No SDK method. Handled as *system message* |
|
98
100
|
|
@@ -142,7 +144,7 @@ New releases are published on a regular basis to ensure the product quality.
|
|
142
144
|
|
143
145
|
## Installation
|
144
146
|
|
145
|
-
```
|
147
|
+
```console
|
146
148
|
npm install @microsoft/omnichannel-chat-sdk --save
|
147
149
|
```
|
148
150
|
|
@@ -151,31 +153,37 @@ npm install @microsoft/omnichannel-chat-sdk --save
|
|
151
153
|
The following steps will be required to run Omnichannel Chat SDK on React Native:
|
152
154
|
|
153
155
|
1. Install `node-libs-react-native`
|
154
|
-
|
156
|
+
|
157
|
+
```console
|
155
158
|
npm install node-libs-react-native --save-dev
|
156
159
|
```
|
157
160
|
|
158
161
|
1. Install `react-native-randomBytes`
|
159
|
-
|
162
|
+
|
163
|
+
```console
|
160
164
|
npm install react-native-randombytes --save-dev
|
161
165
|
```
|
162
166
|
|
163
167
|
1. Install `react-native-get-random-values`
|
164
|
-
|
168
|
+
|
169
|
+
```console
|
165
170
|
npm install react-native-get-random-values --save-dev
|
166
171
|
```
|
167
172
|
|
168
173
|
1. Install `react-native-url-polyfill`
|
169
|
-
|
174
|
+
|
175
|
+
```console
|
170
176
|
npm install react-native-url-polyfill --save-dev
|
171
177
|
```
|
172
178
|
|
173
179
|
1. Install `@azure/core-asynciterator-polyfill`
|
174
|
-
|
180
|
+
|
181
|
+
```console
|
175
182
|
npm install @azure/core-asynciterator-polyfill --save-dev
|
176
183
|
```
|
177
184
|
|
178
185
|
1. Update *metro.config.js* to use React Native compatible Node Core modules
|
186
|
+
|
179
187
|
```ts
|
180
188
|
module.exports = {
|
181
189
|
// ...
|
@@ -190,6 +198,7 @@ The following steps will be required to run Omnichannel Chat SDK on React Native
|
|
190
198
|
```
|
191
199
|
|
192
200
|
1. Add the following *import* on top of your entry point file
|
201
|
+
|
193
202
|
```ts
|
194
203
|
import 'node-libs-react-native/globals';
|
195
204
|
import 'react-native-get-random-values';
|
@@ -223,10 +232,14 @@ const chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, cha
|
|
223
232
|
|
224
233
|
const optionalParams = {
|
225
234
|
getLiveChatConfigOptionalParams: {
|
226
|
-
sendCacheHeaders: false
|
235
|
+
sendCacheHeaders: false,// Whether to send Cache-Control HTTP header to GetChatConfig call
|
236
|
+
useSequentialLoad: false // Whether to use sequential load for chat config, if not present, by default uses parallel load for faster initialization
|
237
|
+
|
227
238
|
}
|
228
239
|
};
|
229
240
|
|
241
|
+
|
242
|
+
// For the case when the widget doesnt have enabled support for attachments, Upload/download operations wont be supported
|
230
243
|
await chatSDK.initialize(optionalParams);
|
231
244
|
```
|
232
245
|
|
@@ -394,6 +407,7 @@ chatSDK.onNewMessage((message) => {
|
|
394
407
|
console.log(message);
|
395
408
|
}, optionalParams);
|
396
409
|
```
|
410
|
+
|
397
411
|
### On Typing Event
|
398
412
|
|
399
413
|
It subscribes to an agent typing event.
|
@@ -512,6 +526,7 @@ try {
|
|
512
526
|
}
|
513
527
|
}
|
514
528
|
```
|
529
|
+
|
515
530
|
### Get Post Chat Survey Context
|
516
531
|
|
517
532
|
It gets the participant type that should be used for the survey and both the default and bot survey details.
|
@@ -532,7 +547,7 @@ const agentAvailability = await chatSDK.getAgentAvailability();
|
|
532
547
|
|
533
548
|
### Pre-Chat Survey
|
534
549
|
|
535
|
-
> See https://docs.microsoft.com/en-us/dynamics365/customer-service/configure-pre-chat-survey?tabs=customerserviceadmincenter on how to set up pre-conversation surveys
|
550
|
+
> See <https://docs.microsoft.com/en-us/dynamics365/customer-service/configure-pre-chat-survey?tabs=customerserviceadmincenter> on how to set up pre-conversation surveys
|
536
551
|
|
537
552
|
```ts
|
538
553
|
import * as AdaptiveCards, { Action } from "adaptivecards";
|
@@ -567,7 +582,7 @@ const agentAvailability = await chatSDK.getAgentAvailability();
|
|
567
582
|
|
568
583
|
### Post-Chat Survey
|
569
584
|
|
570
|
-
> See https://docs.microsoft.com/en-us/dynamics365/customer-service/configure-post-conversation-survey?tabs=customerserviceadmincenter on how to set up post-conversation surveys
|
585
|
+
> See <https://docs.microsoft.com/en-us/dynamics365/customer-service/configure-post-conversation-survey?tabs=customerserviceadmincenter> on how to set up post-conversation surveys
|
571
586
|
|
572
587
|
> ❗ `chatSDK.getPostChatSurveyContext()` needs to be called before `chatSDK.endChat()` is called
|
573
588
|
|
@@ -626,7 +641,7 @@ messages.reverse().forEach((message: any) => renderMessage(message)); // Logic t
|
|
626
641
|
|
627
642
|
### Authenticated Chat
|
628
643
|
|
629
|
-
> See https://docs.microsoft.com/en-us/dynamics365/customer-service/create-chat-auth-settings?tabs=customerserviceadmincenter#create-a-chat-authentication-setting-record on how to set up an authenticated chat
|
644
|
+
> See <https://docs.microsoft.com/en-us/dynamics365/customer-service/create-chat-auth-settings?tabs=customerserviceadmincenter#create-a-chat-authentication-setting-record> on how to set up an authenticated chat
|
630
645
|
|
631
646
|
```ts
|
632
647
|
const chatSDKConfig = {
|
@@ -649,7 +664,7 @@ await chatSDK.initialize();
|
|
649
664
|
|
650
665
|
### Persistent Chat
|
651
666
|
|
652
|
-
> See https://docs.microsoft.com/en-us/dynamics365/customer-service/persistent-chat on how to set up persistent chat
|
667
|
+
> See <https://docs.microsoft.com/en-us/dynamics365/customer-service/persistent-chat> on how to set up persistent chat
|
653
668
|
|
654
669
|
```ts
|
655
670
|
const chatSDKConfig = {
|
@@ -673,9 +688,10 @@ await chatSDK.initialize();
|
|
673
688
|
|
674
689
|
// from this point, this acts like a persistent chat
|
675
690
|
```
|
691
|
+
|
676
692
|
### Chat Reconnect with Authenticated User
|
677
693
|
|
678
|
-
> See https://docs.microsoft.com/en-us/dynamics365/customer-service/configure-reconnect-chat?tabs=customerserviceadmincenter#enable-reconnection-to-a-previous-chat-session on how to set up chat reconnect
|
694
|
+
> See <https://docs.microsoft.com/en-us/dynamics365/customer-service/configure-reconnect-chat?tabs=customerserviceadmincenter#enable-reconnection-to-a-previous-chat-session> on how to set up chat reconnect
|
679
695
|
|
680
696
|
```ts
|
681
697
|
const chatSDKConfig = {
|
@@ -715,7 +731,7 @@ chatSDK.startChat();
|
|
715
731
|
|
716
732
|
### Chat Reconnect with Unauthenticated User
|
717
733
|
|
718
|
-
> See https://docs.microsoft.com/en-us/dynamics365/customer-service/configure-reconnect-chat?tabs=customerserviceadmincenter#enable-reconnection-to-a-previous-chat-session on how to set up chat reconnect
|
734
|
+
> See <https://docs.microsoft.com/en-us/dynamics365/customer-service/configure-reconnect-chat?tabs=customerserviceadmincenter#enable-reconnection-to-a-previous-chat-session> on how to set up chat reconnect
|
719
735
|
|
720
736
|
```ts
|
721
737
|
const chatSDKConfig = {
|
@@ -759,7 +775,7 @@ if (chatReconnectContext.reconnectId) {
|
|
759
775
|
|
760
776
|
### Operating Hours
|
761
777
|
|
762
|
-
> See https://docs.microsoft.com/en-us/dynamics365/customer-service/create-operating-hours?tabs=customerserviceadmincenter on how to set up operating hours
|
778
|
+
> See <https://docs.microsoft.com/en-us/dynamics365/customer-service/create-operating-hours?tabs=customerserviceadmincenter> on how to set up operating hours
|
763
779
|
|
764
780
|
```ts
|
765
781
|
const chatConfig = await chatSDK.getLiveChatConfig();
|
@@ -796,11 +812,12 @@ window.addEventListener("visibilitychange", async () => {
|
|
796
812
|
});
|
797
813
|
```
|
798
814
|
|
799
|
-
|
800
815
|
### Using [BotFramework-WebChat](https://github.com/microsoft/BotFramework-WebChat)
|
816
|
+
>
|
801
817
|
> :warning: Currently supported on web only
|
802
818
|
|
803
819
|
Minimum Requirement Checklist
|
820
|
+
|
804
821
|
1. [ ] Initialize ChatSDK
|
805
822
|
1. [ ] Start new conversation
|
806
823
|
1. [ ] Create Chat Adapter
|
@@ -838,9 +855,10 @@ const store = createStore(
|
|
838
855
|
```
|
839
856
|
|
840
857
|
### Escalation to Voice & Video
|
858
|
+
>
|
841
859
|
> :warning: Currently supported on web only
|
842
860
|
|
843
|
-
> See https://docs.microsoft.com/en-us/dynamics365/customer-service/call-options-visual-engagement on how to set up calling options
|
861
|
+
> See <https://docs.microsoft.com/en-us/dynamics365/customer-service/call-options-visual-engagement> on how to set up calling options
|
844
862
|
|
845
863
|
```ts
|
846
864
|
import OmnichannelChatSDK from '@microsoft/omnichannel-chat-sdk';
|
@@ -948,17 +966,19 @@ if (VoiceVideoCallingSDK) {
|
|
948
966
|
## Feature Comparisons
|
949
967
|
|
950
968
|
### Web
|
969
|
+
|
951
970
|
| | Custom Control | WebChat Control |
|
952
971
|
| --- | --- | --- |
|
953
972
|
| **Features** | | |
|
954
973
|
| Chat Widget UI | Not provided | Basic chat client provided |
|
955
974
|
| Data Masking | Embedded | Requires `Data Masking Middleware` implementation |
|
956
975
|
| Send Typing indicator | Embedded | Requires `sendTypingIndicator` flag set to `true` |
|
957
|
-
| PreChat Survey | Requires Adaptive Cards renderer | Requires Adaptive Cards renderer
|
976
|
+
| PreChat Survey | Requires Adaptive Cards renderer | Requires Adaptive Cards renderer|
|
958
977
|
| Display Attachments | Requires implementation | Basic interface provided & Customizable |
|
959
978
|
| Incoming messages handling | IC3 protocol message data | DirectLine activity data |
|
960
979
|
|
961
980
|
### React Native
|
981
|
+
|
962
982
|
| | Custom Control | Gifted Chat Control | WebChat Control |
|
963
983
|
| --- | --- | --- | --- |
|
964
984
|
| **Features** | | | Currently not supported |
|
@@ -1007,7 +1027,7 @@ await chatSDK.initialize();
|
|
1007
1027
|
|
1008
1028
|
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
1009
1029
|
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
|
1010
|
-
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com
|
1030
|
+
the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com>.
|
1011
1031
|
|
1012
1032
|
When you submit a pull request, a CLA bot will automatically determine whether you need to provide
|
1013
1033
|
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
|
@@ -11,6 +11,7 @@ import ChatSDKMessage from "./core/messaging/ChatSDKMessage";
|
|
11
11
|
import ChatTranscriptBody from "./core/ChatTranscriptBody";
|
12
12
|
import EmailLiveChatTranscriptOptionaParams from "./core/EmailLiveChatTranscriptOptionalParams";
|
13
13
|
import EndChatOptionalParams from "./core/EndChatOptionalParams";
|
14
|
+
import FetchChatTokenResponse from "@microsoft/ocsdk/lib/Model/FetchChatTokenResponse";
|
14
15
|
import FileMetadata from "@microsoft/omnichannel-amsclient/lib/FileMetadata";
|
15
16
|
import FramedClient from "@microsoft/omnichannel-amsclient/lib/FramedClient";
|
16
17
|
import FramedlessClient from "@microsoft/omnichannel-amsclient/lib/FramedlessClient";
|
@@ -30,7 +31,6 @@ import OmnichannelMessage from "./core/messaging/OmnichannelMessage";
|
|
30
31
|
import OnNewMessageOptionalParams from "./core/messaging/OnNewMessageOptionalParams";
|
31
32
|
import PostChatContext from "./core/PostChatContext";
|
32
33
|
import StartChatOptionalParams from "./core/StartChatOptionalParams";
|
33
|
-
import FetchChatTokenResponse from "@microsoft/ocsdk/lib/Model/FetchChatTokenResponse";
|
34
34
|
declare class OmnichannelChatSDK {
|
35
35
|
private debug;
|
36
36
|
runtimeId: string;
|
@@ -73,11 +73,13 @@ declare class OmnichannelChatSDK {
|
|
73
73
|
private AMSClientLoadCurrentState;
|
74
74
|
private isMaskingDisabled;
|
75
75
|
private maskingCharacter;
|
76
|
+
private isAMSClientAllowed;
|
76
77
|
constructor(omnichannelConfig: OmnichannelConfig, chatSDKConfig?: ChatSDKConfig);
|
77
78
|
setDebug(flag: boolean): void;
|
78
79
|
private retryLoadAMSClient;
|
79
80
|
private getAMSClient;
|
80
81
|
private loadInitComponents;
|
82
|
+
private evaluateAMSAvailability;
|
81
83
|
private loadAmsClient;
|
82
84
|
private parallelInitialization;
|
83
85
|
private sequentialInitialization;
|