Class Proactive<TState>

constructor

• new Proactive<
      TState extends TurnState<DefaultConversationState, DefaultUserState>,
  >(
      app: AgentApplication<TState>,
      options: ProactiveOptions,
  ): Proactive<TState>

  Type Parameters

  • TState extends TurnState<DefaultConversationState, DefaultUserState>

  Parameters

  • app: AgentApplication<TState>
  • options: ProactiveOptions

  Returns Proactive<TState>

Static ReadonlyContinueConversationValueType

continueConversation

• continueConversation(
      adapter: BaseAdapter,
      conversationId: string,
      handler: RouteHandler<TState>,
      autoSignInHandlers?: string[],
      continuationActivity?: Partial<Activity>,
  ): Promise<void>

  Continues a stored conversation by executing the given handler within the context of that conversation, looking it up by ID.

  See the Conversation overload for full details.

  Parameters

  • adapter: BaseAdapter

    The channel adapter used to continue the conversation.

  • conversationId: string

    The ID of a conversation previously stored via storeConversation.

  • handler: RouteHandler<TState>

    The route handler to execute within the continued conversation context.

  • OptionalautoSignInHandlers: string[]

    Optional list of OAuth connection names whose tokens should be acquired before invoking the handler.

  • OptionalcontinuationActivity: Partial<Activity>

    Optional activity fields merged into the continuation activity, making them available on ctx.activity inside the handler (e.g. value, valueType).

  Returns Promise<void>

  Throws

  Error if no conversation reference is found for the specified ID.

  Example

  // Scheduled job: send a daily digest to all stored conversations
  for (const convId of storedIds) {
    await app.proactive.continueConversation(adapter, convId, async (ctx, state) => {
      await ctx.sendActivity('Here is your daily digest...')
    })
  }
  Copy

• continueConversation(
      adapter: BaseAdapter,
      conversation: Conversation,
      handler: RouteHandler<TState>,
      autoSignInHandlers?: string[],
      continuationActivity?: Partial<Activity>,
  ): Promise<void>

  Continues an existing conversation by executing the given handler within the context of the provided Conversation reference. The handler receives a TurnContext and a freshly loaded TurnState scoped to the original conversation, enabling the agent to respond as if replying to an incoming activity.

  Parameters

  • adapter: BaseAdapter

    The channel adapter used to continue the conversation.

  • conversation: Conversation

    A Conversation instance created via its constructor or ConversationBuilder.

  • handler: RouteHandler<TState>

    The route handler to execute within the continued conversation context.

  • OptionalautoSignInHandlers: string[]

    Optional list of OAuth connection names whose tokens should be acquired before invoking the handler.

  • OptionalcontinuationActivity: Partial<Activity>

    Optional activity fields merged into the continuation activity, making them available on ctx.activity inside the handler (e.g. value, valueType).

  Returns Promise<void>

  Remarks

  Exceptions thrown inside the handler are captured and re-thrown after the adapter callback completes, since the adapter would otherwise silently swallow them.

  If autoSignInHandlers are supplied and the application has user authorization configured, tokens are acquired before the handler is called. If not all tokens are available and proactiveOptions.failOnUnsignedInConnections is not false, an error is thrown.

  Example

  // Continue a conversation with a custom value payload
  const conv = await app.proactive.getConversationOrThrow(convId)
  await app.proactive.continueConversation(
    adapter,
    conv,
    async (ctx, state) => {
      const payload = ctx.activity.value as { alertType: string }
      await ctx.sendActivity(`Alert triggered: ${payload.alertType}`)
    },
    undefined,
    { value: { alertType: 'threshold-exceeded' }, valueType: Proactive.ContinueConversationValueType }
  )
  Copy

createConversation

• createConversation(
      adapter: BaseAdapter,
      createOptions: CreateConversationOptions,
      handler?: RouteHandler<TState>,
  ): Promise<Conversation>

  Creates a new conversation using the specified channel adapter and conversation options.

  Parameters

  • adapter: BaseAdapter

    The channel adapter used to create the conversation. Must implement createConversationAsync() (i.e. a CloudAdapter instance).

  • createOptions: CreateConversationOptions

    Details required to create the conversation, including identity, channel, service URL, OAuth scope, and ConversationParameters. Build with CreateConversationOptionsBuilder.

  • Optionalhandler: RouteHandler<TState>

    Optional route handler executed immediately after the conversation is created.

  Returns Promise<Conversation>

  The newly created Conversation.

  Remarks

  This wraps CloudAdapter.createConversationAsync(), which requires real network connectivity and authentication. The provided adapter must implement createConversationAsync(); a TypeError is thrown if it does not.

  If createOptions.storeConversation is true, the resulting Conversation is automatically stored via storeConversation so it can be retrieved by ID later.

  If a handler is provided it is executed within the newly created conversation, giving the agent a chance to send an initial message or load state.

  Throws

  TypeError if the adapter does not implement createConversationAsync().

  Example

  // Initiate a new 1:1 conversation with a Teams user and send a welcome message
  const opts = CreateConversationOptionsBuilder
    .create(process.env.APP_ID!, 'msteams')
    .withUser('user-aad-object-id')
    .withTenantId('tenant-id')
    .storeConversation(true)
    .build()
  
  const conv = await app.proactive.createConversation(adapter, opts, async (ctx, state) => {
    await ctx.sendActivity('Hi! I have an update for you.')
  })
  console.log('New conversation ID:', conv.reference.conversation.id)
  Copy

deleteConversation

• deleteConversation(conversationId: string): Promise<void>

  Deletes the stored conversation reference for the given conversation ID.

  Parameters

  • conversationId: string

    The unique identifier of the conversation whose reference should be deleted.

  Returns Promise<void>

  Remarks

  If no record exists for the given ID, no action is taken.

  Example

  // Clean up after a conversation has ended
  app.onActivity('endOfConversation', async (ctx, state) => {
    await app.proactive.deleteConversation(ctx.activity.conversation.id)
  })
  Copy

getConversation

• getConversation(conversationId: string): Promise<Conversation | undefined>

  Retrieves the stored Conversation associated with the given conversation ID.

  Parameters

  • conversationId: string

    The unique identifier of the conversation to retrieve.

  Returns Promise<Conversation | undefined>

  The stored Conversation, or undefined if no record exists for that ID.

  Example

  const conv = await app.proactive.getConversation(convId)
  if (conv) {
    await app.proactive.sendActivity(adapter, conv, { text: 'Hello!' })
  }
  Copy

getConversationOrThrow

• getConversationOrThrow(conversationId: string): Promise<Conversation>

  Retrieves the stored Conversation for the given ID, throwing if no record is found.

  Parameters

  • conversationId: string

    The unique identifier of the conversation to retrieve.

  Returns Promise<Conversation>

  The stored Conversation.

  Throws

  Error if no conversation reference is found for the specified ID.

  Example

  // Use when absence of the conversation should be treated as an error
  const conv = await app.proactive.getConversationOrThrow(convId)
  await app.proactive.sendActivity(adapter, conv, { text: 'Alert: your report is ready.' })
  Copy

sendActivity

• sendActivity(
      adapter: BaseAdapter,
      conversationId: string,
      activity: Partial<Activity>,
  ): Promise<ResourceResponse>

  Sends an activity to a stored conversation, looking it up by ID.

  Parameters

  • adapter: BaseAdapter

    The channel adapter used to send the activity.

  • conversationId: string

    The ID of a conversation previously stored via storeConversation.

  • activity: Partial<Activity>

    The activity to send. If type is not set it defaults to 'message'.

  Returns Promise<ResourceResponse>

  A ResourceResponse with the ID of the sent activity.

  Throws

  Error if no conversation reference is found for the specified ID.

  Example

  // Send a notification using a previously stored conversation ID
  await app.proactive.sendActivity(adapter, storedConvId, { text: 'Your order has shipped!' })
  Copy

• sendActivity(
      adapter: BaseAdapter,
      conversation: Conversation,
      activity: Partial<Activity>,
  ): Promise<ResourceResponse>

  Sends an activity to an existing conversation using the provided Conversation reference.

  Parameters

  • adapter: BaseAdapter

    The channel adapter used to send the activity.

  • conversation: Conversation

    A Conversation instance created via its constructor or ConversationBuilder.

  • activity: Partial<Activity>

    The activity to send. If type is not set it defaults to 'message'.

  Returns Promise<ResourceResponse>

  A ResourceResponse with the ID of the sent activity.

  Example

  // Build a Conversation from a stored reference and send a message
  const conv = await app.proactive.getConversationOrThrow(convId)
  const response = await app.proactive.sendActivity(adapter, conv, { text: 'Hello from the agent!' })
  console.log('Sent activity ID:', response.id)
  Copy

storeConversation

• storeConversation(context: TurnContext): Promise<string>

  Stores the current conversation reference from a live TurnContext in proactive storage.

  Parameters

  • context: TurnContext

    The context object for the current turn, containing activity and conversation information.

  Returns Promise<string>

  The conversation ID that can be used to retrieve the reference in future operations.

  Example

  // Inside an onMessage handler — save the conversation so we can message later
  app.onActivity('message', async (ctx, state) => {
    const convId = await app.proactive.storeConversation(ctx)
    await ctx.sendActivity(`Conversation stored. ID: ${convId}`)
  })
  Copy

• storeConversation(conversation: Conversation): Promise<string>

  Stores an explicit Conversation object in proactive storage.

  Parameters

  • conversation: Conversation

    The conversation reference record to store.

  Returns Promise<string>

  The conversation ID that can be used to retrieve the reference in future operations.

  Throws

  If the conversation fails validation (missing conversation.id, serviceUrl, or claims.aud).

  Example

  // Build a Conversation manually and store it
  const conv = ConversationBuilder
    .create('my-app-id', 'msteams')
    .withUser('user-aad-id')
    .withConversationId('19:existing-thread-id@thread.tacv2')
    .build()
  const convId = await app.proactive.storeConversation(conv)
  Copy