00.MIGRATION.md

Guidance on using this wrapper framework over the BotBuilder SDK

Previously, users developing bots for Teams and Microsoft 365 apps had to use the BotBuilder SDK directly. This SDK is designed to help you build bots that can interact with Teams and Microsoft 365 apps.

While one of the exciting features of this SDK is the AI support that customers will be able to migrate to, your team's first goals might be simply update your current bot without AI.

These directions will apply both to non-AI and AI bot migration. Please feel free to provide feedback!

Convert to the Teams AI SDK

Features from Teams apps that might already exist in your bot are:

1. Messaging capabilities
2. Message Extension (ME) capabilities
3. Adaptive Cards capabilities

The first samples [C# | JS] available assist in migrating these features.

Note: Teams samples are currently available. These samples will be updated to use this SDK in the future.

1. Messaging capabilities

Sample 01.a - echoBot

Replace BotActivityHandler and ApplicationTurnState with this Application and DefaultTurnState in your bot. Note that here, DefaultTurnState is constructed to include ConversationState.

  // Assumption is that the bot/app is already named `app`. Another common possibility is 'bot'
+ import { Application, DefaultTurnState } from @microsoft/teams-ai";

  interface ConversationState {
    count: number;
  }
```diff
- const bot = BotActivityHandler();
  // DefaultTurnState: Conversation State, UserState, TurnState (or TempState). Can be set to one or all three
+ type ApplicationTurnState = DefaultTurnState<ConversationState>;

+ const app =
+  new Application() <
+  ApplicationTurnState >
+  {
+    storage
+  };

The rest of the code, including server.post and await app.run(context) stays the same.

That's it!

Run your bot (with ngrok) and sideload your manifest to test.

---

2. Message Extensions

The original ME sample will eventually be updated to the AI usage: AI messageExtensions

In the previous Teams SDK format, developers needed to set up the Message Extensions query handler like so:

(The rest of the handler continues)

Now, the app class has messageExtensions features to make creating the handler(s) simpler:

• context is TurnContext and state is DefaultTurnState passed in from the bot. The third parameter, in this case query, is the data passed from ME interaction.

// Imported from last example
import { MessagingExtensionAttachment } from "botbuilder";
import { Application } from @microsoft/teams-ai";

// ME query Listener
app.messageExtensions.query("searchCmd", async (context, state, query) => {
  const searchQuery = query.parameters.queryText;
  // Other handling
  // e.g. Create search / action cards

  // Return results
  return {
    attachmentLayout: "",
    attachments: results,
    type: "result"
  };
});

Similarly, selectItem listener would be set up as:

app.messageExtensions.selectItem(async (context, state, item) => {
  // Other handling
  // e.g. Create search / action cards
  // item is the card/item the user selected
  return {
    //...
  }

}

---

Adaptive Cards capabilities

Similar to app.messageExtensions above, app.AdaptiveCards is the handler for producing Adaptive Cards.

// Listener for messages from the user that trigger an adaptive card
app.message(/searchQuery/i, async (context, state) => {
  const attachment = createAdaptiveCard();
  await context.sendActivity({ attachments: [attachment] });
});

// Listener for action.submit on cards from the user

interface SubmitData {
  choiceSelect: string;
}

// Listen for submit actions from the user
app.adaptiveCards.actionSubmit("ChoiceSubmit", async (context, state, data: SubmitData) => {
  await context.sendActivity(`Submitted option is: ${data.choiceSelect}`);
});

Conclusion

Using the code examples above, developers can quickly migrate from using 'botbuilder' SDK to a simpler 'teams-ai' setup.

Please feel free to send us feedback.

Next, the exciting step is to add AI to your bot! Continue on to 01.AI-SETUP