CopilotStudioWebChat class

Package:
@microsoft/agents-copilotstudio-client

A utility class that provides WebChat integration capabilities for Copilot Studio services.

Example

Basic WebChat Integration

import { CopilotStudioClient } from '@microsoft/agents-copilotstudio-client';
import { CopilotStudioWebChat } from '@microsoft/agents-copilotstudio-client';

// Initialize the Copilot Studio client
const client = new CopilotStudioClient({
  botId: 'your-bot-id',
  tenantId: 'your-tenant-id'
});

// Create a WebChat-compatible connection
const directLine = CopilotStudioWebChat.createConnection(client, {
  showTyping: true
});

// Integrate with WebChat
window.WebChat.renderWebChat({
  directLine: directLine,
  // ... other WebChat options
}, document.getElementById('webchat'));

Example

Advanced Usage with Connection Monitoring

const connection = CopilotStudioWebChat.createConnection(client);

// Monitor connection status
connection.connectionStatus$.subscribe(status => {
  switch (status) {
    case 0: console.log('Disconnected'); break;
    case 1: console.log('Connecting...'); break;
    case 2: console.log('Connected and ready'); break;
  }
});

// Listen for incoming activities
connection.activity$.subscribe(activity => {
  console.log('Received activity:', activity);
});

Remarks

This class acts as a bridge between Microsoft Bot Framework WebChat and Copilot Studio, enabling seamless communication through a DirectLine-compatible interface.

Key Features:

  • DirectLine protocol compatibility for easy WebChat integration
  • Real-time bidirectional messaging with Copilot Studio agents
  • Automatic conversation management and message sequencing
  • Optional typing indicators for enhanced user experience
  • Observable-based architecture for reactive programming patterns

Usage Scenarios:

  • Embedding Copilot Studio agents in web applications
  • Creating custom chat interfaces with WebChat components
  • Building conversational AI experiences with Microsoft's bot ecosystem

Methods

createConnection(CopilotStudioClient, CopilotStudioWebChatSettings)

Creates a DirectLine-compatible connection for integrating Copilot Studio with WebChat.

Example

const connection = CopilotStudioWebChat.createConnection(client, {
  showTyping: true
});

// Use with WebChat
window.WebChat.renderWebChat({
  directLine: connection
}, document.getElementById('webchat'));

Method Details

createConnection(CopilotStudioClient, CopilotStudioWebChatSettings)

Creates a DirectLine-compatible connection for integrating Copilot Studio with WebChat.

Example

const connection = CopilotStudioWebChat.createConnection(client, {
  showTyping: true
});

// Use with WebChat
window.WebChat.renderWebChat({
  directLine: connection
}, document.getElementById('webchat'));

static function createConnection(client: CopilotStudioClient, settings?: CopilotStudioWebChatSettings): CopilotStudioWebChatConnection

Parameters

client
CopilotStudioClient

A configured CopilotStudioClient instance that handles the underlying communication with the Copilot Studio service. This client should be properly authenticated and configured with the target bot details.

settings
CopilotStudioWebChatSettings

Optional configuration settings that control the behavior of the WebChat connection. These settings allow customization of features like typing indicators and other user experience enhancements.

Returns

CopilotStudioWebChatConnection

A new CopilotStudioWebChatConnection instance that can be passed directly to WebChat's renderWebChat function as the directLine parameter. The connection is immediately ready for use and will automatically manage the conversation lifecycle.

Remarks

This method establishes a real-time communication channel between WebChat and the Copilot Studio service. The returned connection object implements the DirectLine protocol, making it fully compatible with Microsoft Bot Framework WebChat components.

Connection Lifecycle:

  1. Initialization: Creates observables for connection status and activity streaming
  2. Conversation Start: Automatically initiates conversation when first activity is posted
  3. Message Flow: Handles bidirectional message exchange with proper sequencing
  4. Cleanup: Provides graceful connection termination

Message Processing:

  • User messages are validated and sent to Copilot Studio
  • Agent responses are received and formatted for WebChat
  • All activities include timestamps and sequence IDs for proper ordering
  • Optional typing indicators provide visual feedback during processing