ConversationBuilder class

Package:
@microsoft/agents-hosting

Fluent builder for the Conversation class.

Example

// Build from scratch
const conv = ConversationBuilder
  .create('my-client-id', 'msteams')
  .withUser('user-aad-id')
  .withConversationId('19:channel@thread.skype')
  .build()

// Build from a live TurnContext
const conv = ConversationBuilder.fromContext(turnContext).build()

Methods

build()

Builds the Conversation, auto-filling serviceUrl from channel defaults if needed.
create(string, string, string, string)

Creates a new builder for the given agent and channel.
fromContext(TurnContext)

Creates a builder pre-populated from a live TurnContext. Captures both the conversation reference and the JWT identity claims.
withActivityId(string)

Sets reference.activityId.
withConversation(ConversationAccount)

Sets reference.conversation from a full ConversationAccount.
withConversationId(string)

Sets reference.conversation.id.
withReference(Partial<ConversationReference>)

Merges a partial ConversationReference into the current one. Useful for overlaying externally-provided reference data without losing fields set by earlier builder calls.
withUser(string, string)

Sets reference.user.

Method Details

build()

Builds the Conversation, auto-filling serviceUrl from channel defaults if needed.

function build(): Conversation

Returns

Conversation

create(string, string, string, string)

Creates a new builder for the given agent and channel.

static function create(agentClientId: string, channelId: string, serviceUrl?: string, requestorId?: string): ConversationBuilder

Parameters

agentClientId

string

channelId

string

serviceUrl

string

requestorId

string

Optional: the client ID of the app making the request. Becomes the appid claim, used in multi-tenant Azure Bot scenarios.

Returns

ConversationBuilder

fromContext(TurnContext)

Creates a builder pre-populated from a live TurnContext. Captures both the conversation reference and the JWT identity claims.

static function fromContext(context: TurnContext): ConversationBuilder

Parameters

context
TurnContext

Returns

ConversationBuilder

withActivityId(string)

Sets reference.activityId.

function withActivityId(activityId: string): ConversationBuilder

Parameters

activityId

string

Returns

ConversationBuilder

withConversation(ConversationAccount)

Sets reference.conversation from a full ConversationAccount.

function withConversation(account: ConversationAccount): ConversationBuilder

Parameters

account
ConversationAccount

Returns

ConversationBuilder

withConversationId(string)

Sets reference.conversation.id.

function withConversationId(id: string): ConversationBuilder

Parameters

id

string

Returns

ConversationBuilder

withReference(Partial<ConversationReference>)

Merges a partial ConversationReference into the current one. Useful for overlaying externally-provided reference data without losing fields set by earlier builder calls.

function withReference(ref: Partial<ConversationReference>): ConversationBuilder

Parameters

ref

Partial<ConversationReference>

Returns

ConversationBuilder

withUser(string, string)

Sets reference.user.

function withUser(userId: string, userName?: string): ConversationBuilder

Parameters

userId

string

userName

string

Returns

ConversationBuilder