on how to set up pre-conversation surveys\n\n```ts\n import * as AdaptiveCards, { Action } from \"adaptivecards\";\n\n ...\n\n const preChatSurvey = await chatSDK.getPreChatSurvey();\n\n ...\n\n // Web implementation\n const renderPreChatSurvey = () => {\n const adaptiveCard = new AdaptiveCards.AdaptiveCard();\n adaptiveCard.parse(preChatSurvey); // Parses Adaptive Card JSON data\n adaptiveCard.onExecuteAction = async (action: Action) => { // Adaptive Card event handler\n const preChatResponse = (action as any).data;\n const optionalParams: any = {};\n if (preChatResponse) {\n optionalParams.preChatResponse = preChatResponse;\n }\n await chatSDK.startChat(optionalParams);\n }\n\n const renderedCard = adaptiveCard.render(); // Renders as HTML element\n return { // Returns React element\n n && n.firstChild && n.removeChild(n.firstChild); // Removes duplicates fix\n renderedCard && n && n.appendChild(renderedCard);\n }} />\n }\n\n```\n\n### Post-Chat Survey\n\n> See on how to set up post-conversation surveys\n\n__NOTE : It should be called ONLY when the chat contains a post-survey as part of their configuration, otherwise it will throw an error.__\n\n> β `chatSDK.getPostChatSurveyContext()` needs to be called before `chatSDK.endChat()` is called.\n\n```ts\n// 1. Start chat\nawait chatSDK.startChat();\n\n// 2. Save post chat survey context before ending chat\ntry {\n const context = await chatSDK.getPostChatSurveyContext();\n if (context.participantJoined) { // participantJoined will be true if an agent has joined the conversation, or a bot has joined the conversation and the bot survey flag has been turned on the admin side.\n // formsProLocale is the default language you have set on the CustomerVoice portal. You can override this url parameter with any locale that CustomerVoice supports.\n // If \"&lang=\" is not set on the url, the locale will be English.\n const link = context.participantType === \"Bot\" ? context.botSurveyInviteLink : context.surveyInviteLink;\n const locale = context.participantType === \"Bot\" ? context.botFormsProLocale : context.formsProLocale;\n const linkToSend = link + \"&lang=\" + locale;\n // This link is accessible and will redirect to the survey page. Use it as you see fit.\n }\n} catch (ex) {\n // If the post chat should not be shown for any reason (e.g. post chat is not enabled), promise will be rejected.\n}\n\n// 3. End chat\nawait chatSDK.endChat();\n\n// 4. Display Post Chat\n```\n\n### Reconnect to existing Chat\n\n```ts\nawait chatSDK.startChat(); // Starts NEW chat\n\nconst liveChatContext = await chatSDK.getCurrentLiveChatContext(); // Gets chat context\n\ncache.saveChatContext(liveChatContext); // Custom logic to save chat context to cache\n\n...\n\n// Page/component reloads, ALL previous states are GONE\n\n...\n\nconst liveChatContext = cache.loadChatContext() // Custom logic to load chat context from cache\n\nconst optionalParams = {};\noptionalParams.liveChatContext = liveChatContext;\n\nawait chatSDK.startChat(optionalParams); // Reconnects to EXISTING chat\n\n...\n\nconst messages = await chatSDK.getMessages(); // Gets all messages from EXISTING chat\nmessages.reverse().forEach((message: any) => renderMessage(message)); // Logic to render all messages to UI\n```\n\n### Authenticated Chat\n\n> See on how to set up an authenticated chat\n\n```ts\nconst chatSDKConfig = {\n getAuthToken: async () => {\n const response = await fetch(\"http://contosohelp.com/token\");\n if (response.ok) {\n return await response.text();\n }\n else {\n return null\n }\n }\n}\n\nconst chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, chatSDKConfig);\nawait chatSDK.initialize();\n\n// from this point, this acts like a regular chat widget\n```\n\n### Persistent Chat\n\n> See on how to set up persistent chat\n\n```ts\nconst chatSDKConfig = {\n persistentChat: {\n disable: false,\n tokenUpdateTime: 21600000\n },\n getAuthToken: async () => {\n const response = await fetch(\"http://contosohelp.com/token\");\n if (response.ok) {\n return await response.text();\n }\n else {\n return null\n }\n }\n}\n\nconst chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, chatSDKConfig);\nawait chatSDK.initialize();\n\n// from this point, this acts like a persistent chat\n```\n\n### Persistent Chat History\n\n> See on how to set up persistent chat\n\nWhen persistent chat is enabled, you can retrieve the chat history from previous conversations using `getPersistentChatHistory()`. This method returns paginated results, allowing you to load history incrementally (e.g., as the user scrolls up).\n\n> :warning: **Prerequisites:**\n> - Persistent chat must be **enabled** in the admin portal (conversation mode set to Persistent Chat) and in the SDK config (`persistentChat.disable: false`)\n> - The user must be **authenticated** (`getAuthToken` must be configured)\n> - `chatSDK.initialize()` and `chatSDK.startChat()` must be called before fetching history\n> - Chat history is available for up to **12 months**\n\n#### Page Size\n\nThe `pageSize` parameter controls how many messages are returned per call.\n\n| | Value |\n| --- | --- |\n| **Default** | `50` (used when `pageSize` is omitted) |\n| **Minimum** | `1` |\n| **Maximum** | `100` |\n\nIf `pageSize` is not provided, the backend defaults to **50**. Values outside the 1β100 range will be rejected with an error.\n\n#### How Pagination Works\n\n| Call | `pageToken` param | What happens |\n| --- | --- | --- |\n| **First call** | Omit or `undefined` | Fetches the most recent page of messages. The response includes `nextPageToken` if older messages exist. |\n| **Subsequent calls** | Pass the `nextPageToken` from the previous response | Fetches the next (older) page. Again returns `nextPageToken` if more messages remain. |\n| **Last page** | Pass the `nextPageToken` from the previous response | Returns the remaining messages. `nextPageToken` is `null`, indicating there are no more messages in the history. |\n\nIn short: keep passing the `nextPageToken` from each response into the next call until the backend returns `nextPageToken: null` β that signals the entire history has been retrieved.\n\n#### Basic Usage\n\n```ts\nconst chatSDKConfig = {\n persistentChat: {\n disable: false,\n tokenUpdateTime: 21600000\n },\n getAuthToken: async () => {\n const response = await fetch(\"http://contosohelp.com/token\");\n if (response.ok) {\n return await response.text();\n }\n else {\n return null\n }\n }\n}\n\nconst chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, chatSDKConfig);\nawait chatSDK.initialize();\n\nawait chatSDK.startChat();\n\n// Fetch the first page of chat history\nconst history = await chatSDK.getPersistentChatHistory({\n pageSize: 25\n});\n\nif (history) {\n // Render messages\n history.chatMessages.forEach((message) => {\n console.log(`[${message.createdDateTime}] ${message.content}`);\n });\n\n // Check if more history is available\n if (history.nextPageToken) {\n console.log(\"More history available\");\n }\n}\n```\n\n#### Pagination β Loading More History on Scroll Up\n\nAfter the first call returns a `nextPageToken`, you can fetch older pages on demand β for example, each time the customer scrolls up in the chat window. The loop below shows fetching all remaining history, but in practice you would call `getPersistentChatHistory` once per scroll-up action, passing the `nextPageToken` from the previous response.\n\n```ts\n// After the first call (Basic Usage above), save the nextPageToken\nlet pageToken: string | undefined = history?.nextPageToken ?? undefined;\n\n// Example: fetch the next page when the customer scrolls up\nconst loadMoreHistory = async () => {\n if (!pageToken) {\n console.log(\"No more history to load\");\n return;\n }\n\n const response = await chatSDK.getPersistentChatHistory({\n pageSize: 25,\n pageToken\n });\n\n if (response && response.chatMessages.length > 0) {\n // Render the older messages in the chat UI\n response.chatMessages.forEach((message) => {\n console.log(`[${message.createdDateTime}] ${message.content}`);\n });\n\n // Update the token for the next scroll-up action\n pageToken = response.nextPageToken ?? undefined;\n }\n};\n\n// Bind to your scroll-up event (e.g., user reaches the top of the chat container)\nchatContainer.addEventListener('scroll', () => {\n if (chatContainer.scrollTop === 0) {\n loadMoreHistory();\n }\n});\n```\n\nAlternatively, to fetch all history at once in a loop:\n\n```ts\nlet token: string | undefined = history?.nextPageToken ?? undefined;\nlet allMessages = [...(history?.chatMessages ?? [])];\n\nwhile (token) {\n const response = await chatSDK.getPersistentChatHistory({\n pageSize: 25,\n pageToken: token\n });\n\n if (response && response.chatMessages.length > 0) {\n allMessages = [...allMessages, ...response.chatMessages];\n token = response.nextPageToken ?? undefined;\n } else {\n break;\n }\n}\n\nconsole.log(`Total messages retrieved: ${allMessages.length}`);\n```\n\n#### Response Shape\n\nThe response type is exported from the SDK and can be imported for TypeScript usage:\n\n```ts\nimport { GetPersistentChatHistoryResponse } from '@microsoft/omnichannel-chat-sdk';\n```\n\n```ts\ntype GetPersistentChatHistoryResponse = {\n chatMessages: PersistentChatHistoryMessage[];\n nextPageToken: string | null; // null when no more pages\n}\n\ntype PersistentChatHistoryMessage = {\n content: string; // Message text\n contentType: number; // Content type identifier\n createdDateTime: string; // ISO 8601 timestamp\n from: {\n application: { // Sender application info\n displayName: string; // e.g., agent name or bot name\n id: string;\n } | null;\n };\n id: string; // Unique message identifier\n attachments: unknown[]; // File attachments if any\n additionalData: {\n deliveryMode: string; // Delivery channel\n ConversationId: string; // Conversation the message belongs to\n tags: string; // Message tags\n };\n}\n```\n\n#### Error Handling\n\n```ts\ntry {\n const history = await chatSDK.getPersistentChatHistory({ pageSize: 25 });\n // Process messages...\n} catch (error) {\n if (error.message === 'ChatSDKNotInitialized') {\n // SDK not initialized β call chatSDK.initialize() first\n }\n if (error.message === 'PersistentChatNotEnabled') {\n // Persistent chat is not enabled for this widget\n }\n if (error.message === 'AuthenticatedUserTokenNotFound') {\n // User is not authenticated β configure getAuthToken\n }\n if (error.message === 'PersistentChatConversationRetrievalFailure') {\n // Server error fetching history β retry or handle gracefully\n }\n}\n```\n\n### Chat Reconnect with Authenticated User\n\n> See on how to set up chat reconnect\n\n```ts\nconst chatSDKConfig = {\n chatReconnect: {\n disable: false,\n },\n getAuthToken: async () => {\n const response = await fetch(\"http://contosohelp.com/token\");\n if (response.ok) {\n return await response.text();\n }\n else {\n return null\n }\n }\n}\n\nconst chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, chatSDKConfig);\nawait chatSDK.initialize();\n\n...\n\nconst chatReconnectContext = await chatSDK.getChatReconnectContext();\n\nif (chatReconnectContext.reconnectId) {\n // Add UX with options to reconnect to previous existing chat or start new chat\n}\n\n// Reconnect chat option\nconst optionalParams = {};\noptionalParams.reconnectId = chatReconnectContext.reconnectId;\nchatSDK.startChat(optionalParams);\n\n// Start new chat option\nchatSDK.startChat();\n```\n\n### Chat Reconnect with Unauthenticated User\n\n> See on how to set up chat reconnect\n\n```ts\nconst chatSDKConfig = {\n chatReconnect: {\n disable: false,\n },\n}\n\nconst chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, chatSDKConfig);\nawait chatSDK.initialize();\n\n....\n\nconst optionalParams: any = {};\n\n// Retrieve reconnect id from the URL\nconst urlParams = new URLSearchParams(window.location.search);\nconst reconnectId = urlParams.get('oc.reconnectid');\n\nconst params = {\n reconnectId\n};\n\n// Validate reconnect id\nconst chatReconnectContext = await chatSDK.getChatReconnectContext(params);\n\n// If the reconnect id is invalid or expired, redirect URL if there is any URL set in the configuration\nif (chatReconnectContext.redirectURL) {\n window.location.replace(chatReconnectContext.redirectURL);\n}\n\n// Valid reconnect id, reconnect to previous chat\nif (chatReconnectContext.reconnectId) {\n await chatSDK.startChat({\n reconnectId: chatReconnectContext.reconnectId\n });\n} else { // Reconnect id from URL is not valid, start new chat session\n await chatSDK.startChat();\n}\n```\n\n### Operating Hours\n\n> See on how to set up operating hours\n\n```ts\nconst chatConfig = await chatSDK.getLiveChatConfig();\nconst {LiveWSAndLiveChatEngJoin: liveWSAndLiveChatEngJoin} = liveChatConfig;\nconst {OutOfOperatingHours: outOfOperatingHours} = liveWSAndLiveChatEngJoin;\n\nif (outOfOperatingHours === \"True\") {\n // Handles UX on Out of Operating Hours\n} else {\n await chatSDK.startChat();\n // Renders Custom Chat Widget\n}\n```\n\n### Best Practices for Chat Session Management: Handling Disconnections and Network Instability\n\n> When users switch away from a browser tab or move an browser app to the background, it's important to check if the chat session is still active before allowing message sending when user resumes. This applies to both mobile and desktop environments, as sessions can expire or disconnect when not actively used\n\n```ts\n// 1. Register a listener for visbilitychange event\nwindow.addEventListener(\"visibilitychange\", async () => {\n// 2. verify if the browser is in the foreground by checking the document.hidden property\n if (!document.hidden) {\n//3. Check conversation state by making a call to getConversationDetails\n const optionalParams = {\n liveChatContext: {}, // EXISTING chat context data\n };\n const conversationDetails = await chatSDK.getConversationDetails(optionalParams);\n if (conversationDetails?.state === \"WrapUp\" || conversationDetails?.state === \"Closed\") {\n//4. Show disconnect notification to customer and disable the input box so that user cannot send a message \n }\n \n }\n});\n\n\n\nwindow.addEventListener('online', async () => {\n // Re-establish chat connection\n const optionalParams = {\n liveChatContext: {}, // EXISTING chat context data\n };\n const conversationDetails = await chatSDK.getConversationDetails(optionalParams);\n if (conversationDetails?.state === \"WrapUp\" || conversationDetails?.state === \"Closed\") {\n \n }\n});\n\nwindow.addEventListener('offline', () => {\n // Inform user of connectivity issues\n});\n\n\n```\n\n### Using [BotFramework-WebChat](https://github.com/microsoft/BotFramework-WebChat)\n>\n> :warning: Currently supported on web only\n\nMinimum Requirement Checklist\n\n1. [ ] Initialize ChatSDK\n1. [ ] Start new conversation\n1. [ ] Create Chat Adapter\n1. [ ] Create WebChat store with default middlewares\n 1. [ ] Send Default Channel Message Tags using Store Middleware (See [here](/docs//DEVELOPMENT_GUIDE.md#send-default-channel-message-tags-using-store-middleware)) β Required\n1. [ ] Render WebChat\n\n```ts\nimport OmnichannelChatSDK from '@microsoft/omnichannel-chat-sdk';\nimport ReactWebChat, {createStore} from 'botframework-webchat';\n\n// 1. ChatSDK Initialization\nconst chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig);\nawait chatSDK.initialize();\n\n// 2. Start new conversation\nawait chatSDK.startChat();\n\n// 3. Create chat adapter\nconst chatAdapter = await chatSDK.createChatAdapter();\n\n// 4. Create WebChat store with middlewares\nconst store = createStore(\n {}, // initial state\n sendDefaultMessagingTagsMiddleware // β Required\n);\n\n// 5. Render WebChat\n\n```\n\n### Escalation to Voice & Video\n>\n> :warning: Currently supported on web only\n\n> See on how to set up calling options\n\n```ts\nimport OmnichannelChatSDK from '@microsoft/omnichannel-chat-sdk';\n\n...\n\nconst chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, chatSDKConfig);\nawait chatSDK.initialize();\n\nlet VoiceVideoCallingSDK;\ntry {\n VoiceVideoCallingSDK = await chatSDK.getVoiceVideoCalling();\n console.log(\"VoiceVideoCalling loaded\");\n} catch (e) {\n console.log(`Failed to load VoiceVideoCalling: ${e}`);\n\n if (e.message === 'UnsupportedPlatform') {\n // Voice Video Calling feature is not supported on this platform\n }\n\n if (e.message === 'FeatureDisabled') {\n // Voice Video Calling feature is disabled on admin side\n }\n}\n\nawait chatSDK.startChat();\n\nconst chatToken: any = await chatSDK.getChatToken();\n\n// Initialize only if VoiceVideoCallingSDK is defined\nif (VoiceVideoCallingSDK) {\n try {\n await VoiceVideoCallingSDK.initialize({\n chatToken,\n selfVideoHTMLElementId: 'selfVideo', // HTML element id where video stream of the agent will be rendered\n remoteVideoHTMLElementId: 'remoteVideo', // HTML element id where video stream of the customer will be rendered\n OCClient: chatSDK.OCClient\n });\n } catch (e) {\n console.error(\"Failed to initialize VoiceVideoCalling!\");\n }\n\n // Triggered when there's an incoming call\n VoiceVideoCallingSDK.onCallAdded(() => {\n ...\n });\n\n // Triggered when local video stream is available (e.g.: Local video added succesfully in selfVideoHTMLElement)\n VoiceVideoCallingSDK.onLocalVideoStreamAdded(() => {\n ...\n });\n\n // Triggered when local video stream is unavailable (e.g.: Customer turning off local video)\n VoiceVideoCallingSDK.onLocalVideoStreamRemoved(() => {\n ...\n });\n\n // Triggered when remote video stream is available (e.g.: Remote video added succesfully in remoteVideoHTMLElement)\n VoiceVideoCallingSDK.onRemoteVideoStreamAdded(() => {\n ...\n });\n\n // Triggered when remote video stream is unavailable (e.g.: Agent turning off remote video)\n VoiceVideoCallingSDK.onRemoteVideoStreamRemoved(() => {\n ...\n });\n\n // Triggered when current call has ended or disconnected regardless the party\n VoiceVideoCalling.onCallDisconnected(() => {\n ...\n });\n\n // Check if microphone is muted\n const isMicrophoneMuted = VoiceVideoCallingSDK.isMicrophoneMuted();\n\n // Check if remote video is available\n const isRemoteVideoEnabled = VoiceVideoCallingSDK.isRemoteVideoEnabled();\n\n // Check if local video is available\n const isLocalVideoEnabled = VoiceVideoCallingSDK.isLocalVideoEnabled();\n\n // Accepts incoming call\n const acceptCallConfig = {\n withVideo: true // Accept call with/without video stream\n };\n await VoiceVideoCallingSDK.acceptCall(acceptCallConfig);\n\n // Rejects incoming call\n await VoiceVideoCallingSDK.rejectCall();\n\n // Ends/Stops current call\n await VoiceVideoCallingSDK.stopCall();\n\n // Mute/Unmute current call\n await VoiceVideoCallingSDK.toggleMute()\n\n // Display/Hide local video of current call\n await VoiceVideoCallingSDK.toggleLocalVideo()\n\n // Clean up VoiceVideoCallingSDK (e.g.: Usually called when customer ends chat session)\n VoiceVideoCallingSDK.close();\n}\n```\n\n## Feature Comparisons\n\n### Web\n\n| | Custom Control | WebChat Control |\n| --- | --- | --- |\n| **Features** | | |\n| Chat Widget UI | Not provided | Basic chat client provided |\n| Data Masking | Embedded | Requires `Data Masking Middleware` implementation |\n| Send Typing indicator | Embedded | Requires `sendTypingIndicator` flag set to `true` |\n| PreChat Survey | Requires Adaptive Cards renderer | Requires Adaptive Cards renderer|\n| Display Attachments | Requires implementation | Basic interface provided & Customizable |\n| Incoming messages handling | IC3 protocol message data | DirectLine activity data |\n\n### React Native\n\n| | Custom Control | Gifted Chat Control | WebChat Control |\n| --- | --- | --- | --- |\n| **Features** | | | Currently not supported |\n| Chat Widget UI | Not provided | Basic chat client provided | X |\n| Data Masking | Embedded | Embedded | X |\n| Send Typing indicator | Embedded | Requires Implementation | X |\n| PreChat Survey | Requires Adaptive Cards renderer | Requires Adaptive Cards renderer | X |\n| Display Attachments | Requires implementation| Embedded | X |\n| Incoming messages handling |IC3 protocol message data | IC3 protocol message data | X |\n\n## Telemetry\n\nOmnichannel Chat SDK collects telemetry by default to improve the featureβs capabilities, reliability, and performance over time by helping Microsoft understand usage patterns, plan new features, and troubleshoot and fix problem areas.\n\nSome of the data being collected are the following:\n\n| Field | Sample |\n| --- | --- |\n| Organization Id | `e00e67ee-a60e-4b49-b28c-9d279bf42547` |\n| Organization Url | `org60082947.crm.oc.crmlivetie.com` |\n| Widget Id | `1893e4ae-2859-4ac4-9cf5-97cffbb9c01b` |\n| Browser Name | `Edge` |\n| Os Name | `Windows` |\n| Anonymized IP Address (last octet redacted) | `19.207.000.000` |\n\nIf your organization is concerned about the data collected by the Chat SDK, you have the option to turn off automatic data collection by adding a flag in the `ChatSDKConfig`.\n\n```ts\nconst omnichannelConfig = {\n orgUrl: \"\",\n orgId: \"\",\n widgetId: \"\"\n};\n\nconst chatSDKConfig = {\n telemetry: {\n disable: true // Disable telemetry\n }\n};\n\nconst chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, chatSDKConfig);\nawait chatSDK.initialize();\n```\n\n## Releasing\n\nSee [docs/RELEASING.md](docs/RELEASING.md) for development builds, official npm and GitHub releases, release notes, and hotfixes.\n\n## Contributing\n\nThis project welcomes contributions and suggestions. Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit .\n\nWhen you submit a pull request, a CLA bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n","readmeFilename":"README.md"}