[Feature Request]: Enhance Proactive Message - retrieve and manage ConversationReference

[swatDong]

Scenario

Per https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=csharp#retrieve-and-store-the-conversation-reference, to proactively messaging a person/group/team, I need to get the ConversationReference first.

However, it's not so clear that how to treat the conversation reference for different activity types, or how to get correct value for 1:1 chat / group / team channel. For example:

• On team deleted, I need to remove/forget the conversation reference
• Get the team's conversation reference instead of the channel post one

Would it worth to add some utilities/helpers to simplify the whole flow?

Solution

Based on current SDK, here's one solution to use a beforeTurnHandler to manage conversation references on all incoming activities.

import { TurnState } from "@microsoft/teams-ai";
import { TurnContext, Activity, ConversationReference } from "botbuilder";

export const conversationReferences: Record<string, any> = {};

export async function beforeTurnHandler(context: TurnContext, state: TurnState): Promise<boolean> {
  const activityType = context.activity.type;
  const conversationReference = getConversationReference(context.activity);
  let operation = "";
  
  // determine operation per activity types and details
  if (activityType === "installationUpdate") {
    const action = context.activity.action?.toLowerCase();
    if (action === "add") {
      operation = "add";
    } else {
      operation = "remove";
    }
  } else if (activityType === "conversationUpdate") {
    const eventType = context.activity.channelData?.eventType as string;
    if (eventType === "teamDeleted") {
      operation = "remove";
    } else if (eventType === "teamRestored") {
      operation = "add";
    }
  } else if (activityType === "message") {
    operation = "check";
  }
  
  // update conversationReferences
  if (operation === "add") {
    conversationReferences[getKey(conversationReference)] = conversationReference;
  } else if (operation === "remove") {
    delete conversationReferences[getKey(conversationReference)];
  } else if (operation === "check") {
    if (conversationReferences[getKey(conversationReference)] === undefined) {
      conversationReferences[getKey(conversationReference)] = conversationReference;
    }
  }

  return true;
}

// get conversation reference for a 1:1 chat, or group chat, or team
function getConversationReference(activity: Activity): Partial<ConversationReference> {
  const reference = TurnContext.getConversationReference(activity);
  const conversationType = reference?.conversation?.conversationType;
  if (conversationType === "channel") {
    const teamId = activity?.channelData?.team?.id;
    const channelId = activity.channelData?.channel?.id;
    // `teamId === channelId` means General channel. Ignore non-General channel.
    if (
      teamId !== undefined &&
      (channelId === undefined || teamId === channelId)
    ) {
      const teamReference = JSON.parse(JSON.stringify(reference));
      teamReference.conversation.id = teamId;
      return teamReference;
    }
  }
  return reference;
}

// get a key of conversation reference
function getKey(reference: Partial<ConversationReference>): string {
  return `_${reference.conversation?.tenantId}_${reference.conversation?.id}`;
}

Wondering if some of the above code parts could be added to SDK to simplify user's code.

Additional Context

No response

[Benjiiim]

I like the idea of having some utilities/helpers to ease the proactive messages story.

[Benjiiim]

It seems that @yiqing-zhao and @MuyangAmigo are working on something related according to #1949