CopilotStudioWebChatConnection interface

Package:
@microsoft/agents-copilotstudio-client

Represents a connection interface for integrating Copilot Studio with WebChat.

Remarks

This interface provides the necessary methods and observables to facilitate bidirectional communication between a WebChat client and the Copilot Studio service.

The connection follows the DirectLine protocol pattern, making it compatible with Microsoft Bot Framework WebChat components.

Properties

activity$

An observable stream that emits incoming activities from the Copilot Studio service. Each activity represents a message, card, or other interactive element sent by the agent.

All emitted activities include:

  • A timestamp indicating when the activity was received
  • A 'webchat:sequence-id' in their channelData for proper message ordering
  • Standard Bot Framework Activity properties (type, text, attachments, etc.)
connectionStatus$

An observable that emits the current connection status as numeric values. This allows WebChat clients to monitor and react to connection state changes.

Connection status values:

  • 0: Disconnected - No active connection to the service
  • 1: Connecting - Attempting to establish connection
  • 2: Connected - Successfully connected and ready for communication
conversationId

The active conversation ID. Set from CopilotStudioWebChatSettings.conversationId when resuming, or captured from the first response activity for new conversations. Returns undefined until a conversation has been established.

Methods

end()

Gracefully terminates the connection to the Copilot Studio service. This method ensures proper cleanup by completing all active observables and releasing associated resources.

After calling this method:

  • The connectionStatus$ observable will be completed
  • The activity$ observable will stop emitting new activities
  • No further activities can be posted through this connection
postActivity(Activity)

Posts a user activity to the Copilot Studio service and returns an observable that emits the activity ID once the message is successfully sent.

The method validates that the activity contains meaningful content and handles the complete message flow including optional typing indicators.

Property Details

activity$

An observable stream that emits incoming activities from the Copilot Studio service. Each activity represents a message, card, or other interactive element sent by the agent.

All emitted activities include:

  • A timestamp indicating when the activity was received
  • A 'webchat:sequence-id' in their channelData for proper message ordering
  • Standard Bot Framework Activity properties (type, text, attachments, etc.)
activity$: Observable<Partial<Activity>>

Property Value

Observable<Partial<Activity>>

connectionStatus$

An observable that emits the current connection status as numeric values. This allows WebChat clients to monitor and react to connection state changes.

Connection status values:

  • 0: Disconnected - No active connection to the service
  • 1: Connecting - Attempting to establish connection
  • 2: Connected - Successfully connected and ready for communication
connectionStatus$: BehaviorSubject<number>

Property Value

BehaviorSubject<number>

conversationId

The active conversation ID. Set from CopilotStudioWebChatSettings.conversationId when resuming, or captured from the first response activity for new conversations. Returns undefined until a conversation has been established.

conversationId: undefined | string

Property Value

undefined | string

Method Details

end()

Gracefully terminates the connection to the Copilot Studio service. This method ensures proper cleanup by completing all active observables and releasing associated resources.

After calling this method:

  • The connectionStatus$ observable will be completed
  • The activity$ observable will stop emitting new activities
  • No further activities can be posted through this connection
function end()

postActivity(Activity)

Posts a user activity to the Copilot Studio service and returns an observable that emits the activity ID once the message is successfully sent.

The method validates that the activity contains meaningful content and handles the complete message flow including optional typing indicators.

function postActivity(activity: Activity): Observable<string>

Parameters

activity
Activity

The user activity to send.

Returns

Observable<string>

An observable that emits the unique activity ID upon successful posting.