repository·main·Indexed 23 days ago
https://github.com/microsoft/botframework-webchatA highly customizable web-based client for the Bot Framework v4 SDK. This documentation covers integration via iframes, package bundles (Full, ES5, and Minimal), architecture layers (base, core, component, directlinespeech, embed), and localization workflows. It also includes details on the cldr-data-downloader tool and Vibe-Grep for repository housekeeping.
Web Chat supports speech-to-text (STT) and text-to-speech (TTS) functionality through Azure Cognitive Services.
Note: Direct Line Speech is the preferred method for providing speech functionality in Web Chat. This guide specifically covers integration using Azure Cognitive Services directly.
Bot Framework Web Chat is a highly-customizable web-based client designed for the Bot Framework v4 SDK. It provides a user interface for interacting with conversational AI bots. It is part of the larger Microsoft Bot Framework ecosystem.
Security Note: Web Chat supports Content Security Policy (CSP). Developers are encouraged to enable CSP to protect conversations and improve security.
Vibe-Grep (vg) is an internal tool designed for repository housekeeping. It uses AST-based (Abstract Syntax Tree) code search and analysis to perform custom operations and audits across the repository.
You can access the tool via the vg command line interface.
vg helpsamples directory contains hosted examples of Web Chat in action. These samples are designed to demonstrate various features of the library by connecting to MockBot, a specialized bot used for testing Web Chat capabilities. You can find the source code for these samples in the main repository under the samples folder, and the source code for the MockBot used in these examples is available in a separate repository.Direct Line Speech is a protocol designed for Voice Assistant scenarios, such as smart displays, automotive dashboards, or navigation systems that require low latency in Single-Page Applications (SPA) or Progressive Web Apps (PWA).
Key characteristics:
For specific requirements regarding Cognitive Services Speech Services, refer to the SPEECH.md documentation in the repository.
Polymiddleware is Web Chat's unified middleware approach. It allows for deep, cascaded UI customization by enabling you to add, remove, replace, or decorate UI elements. Middleware is passed via a single polymiddleware prop to the ReactWebChat component and operates in a cascading sequence where upstream middleware can influence downstream rendering.
To use it, create an array of middleware functions (often wrapped in specific creators like createActivityPolymiddleware) and pass them to the polymiddleware prop. Use useMemo to ensure the middleware array is stable across re-renders.
function MyChatUI() {
const polymiddleware = useMemo(
() => [
createActivityPolymiddleware(
next => request =>
request.activity.type === 'event'
? // Handle rendering of event activity though <EventActivity activity={request.activity}>
reactComponent(EventActivity, { activity: request.activity })
: // Continue rendering.
next(request)
),
createActivityPolymiddleware(...),
createActivityPolymiddleware(...),
// Handle rendering of error box.
createErrorBoxPolymiddleware(...)
],
[]
);
return (
<ReactWebChat
polymiddleware={polymiddleware}
// ... other props ...
/>
);
}Vibe-Grep is built on top of ast-grep and organizes its extensible analysis capabilities into three hierarchical layers:
commands/ folder.rules/ folder.To ensure reliability during packet loss or when a client joins a conversation after a livestream has already started, interim activities are designed to contain overlapping content.
Instead of sending incremental fragments, each interim activity provides enough content to allow the client to catch up to the current state of the livestream. This approach also allows the bot to backtrack or erase parts of a response if necessary.
To automatically clear conversation data and start a new session after a period of inactivity, you can implement a custom store middleware. This pattern involves monitoring specific Web Chat actions to reset an idle timer.
createStore to listen for DIRECT_LINE/CONNECT_FULFILLED (when the connection is established) or WEB_CHAT/SUBMIT_SEND_BOX (when the user sends a message).resetAt) to a new timestamp (Date.now() + IDLE_TIMEOUT).setSession(false) to clear the current session and then re-initialize the session with a new Direct Line token and a new store instance to start a fresh conversation.Note: This approach is a proof of concept and should be implemented with production security considerations in mind.
setSession({
directLine: createDirectLine({ token }),
key,
store: createStore({}, () => next => action => {
if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED' || action.type === 'WEB_CHAT/SUBMIT_SEND_BOX') {
// Reset the timer when the connection established, or the user sends an activity
setResetAt(Date.now() + IDLE_TIMEOUT);
}
return next(action);
})
});Web Chat uses a dynamic discovery mechanism to sync configuration between the adapter and the UI:
capabilitieschanged event, Web Chat re-fetches all capabilities.useCapabilities hook with a selector targeting the changed capability will re-render.While Activity ID is a unique service-assigned ID, not every activity is guaranteed to have one. Web Chat uses Activity Keys as an alternative opaque string reference.
Key characteristics:
Use the following hooks to navigate between these identifiers:
useGetActivitiesByKeyuseGetActivityByKeyuseGetKeyByActivityuseGetKeyByActivityIdTo provide custom, accessible narration for message activities (especially when dealing with complex Markdown, HTML, or file attachments), use the webchat:fallback-text field within the channelData object of the activity.
Web Chat follows this priority logic:
channelData['webchat:fallback-text'] is present and not empty: Web Chat uses this string for narration. This is the recommended way to ensure consistent results for complex content.textFormat is markdown, Web Chat attempts to strip Markdown syntax from the text field using a best-effort algorithm before narrating.text field as-is.In both cases, it then appends narration for every attachment rendered through the attachmentForScreenReader middleware.