Create a message extension

5 minutes

In this unit, you learn how to create a message extension. You also learn how to run and debug your message extension in Microsoft Teams using Teams Toolkit.

To create a message extension, you need the following components:

Azure Bot resource to register your web service as a bot with the Bot Framework
Web service to handle user interactions with the message extension
App manifest to define the message extension capabilities in Microsoft Teams

Configure Azure Bot resource

The Azure Bot resource is used to register your web service as a bot with the Bot Framework. A Microsoft Entra app registration is required to create an Azure Bot resource. The app registration provides a secure way to authenticate and authorize your bot. The web service uses the Microsoft Entra app registration credentials to authenticate with the bot service.

The following code snippet shows how to create an Azure Bot resource using Bicep:

resource botService 'Microsoft.BotService/botServices@2021-03-01' = {
  kind: 'azurebot'
  location: 'global'
  name: 'botService'
  properties: {
    displayName: 'Bot Service'
    endpoint: 'https://webservice.contoso.com/api/messages'
    msaAppId: '00000000-0000-0000-0000-000000000000'
  }
  sku: {
    name: botServiceSku
  }
}

The endpoint property specifies the messaging endpoint exposed on the web service that the bot service uses to send requests when a user interacts with the message extension. The msaAppId property specifies the Microsoft Entra app registration ID used to authenticate the bot service with the web service.

Channels are used to connect the bot service with messaging platforms such as Microsoft Teams, Slack, Facebook Messenger, and more.

The following code snippet shows how to configure the Microsoft Teams and Microsoft 365 (Outlook and Microsoft 365 Copilot) channels on the Azure Bot resource:

resource botServiceMsTeamsChannel 'Microsoft.BotService/botServices/channels@2021-03-01' = {
  parent: botService
  location: 'global'
  name: 'MsTeamsChannel'
  properties: {
    channelName: 'MsTeamsChannel'
  }
}

resource botServiceM365ExtensionsChannel 'Microsoft.BotService/botServices/channels@2022-06-15-preview' = {
  parent: botService
  location: 'global'
  name: 'M365Extensions'
  properties: {
    channelName: 'M365Extensions'
  }
}

Configure web service

The web service is a web app that contains the message extension code. The web service is responsible for handling user interactions with the message extension and uses the Bot Framework SDK to communicate with the bot service.

To handle user interactions, you implement:

A messaging endpoint
A Bot Adapter
A Bot Activity Handler

The messaging endpoint is used to receive requests from the bot service. The messaging endpoint is exposed on the web service and passes the requests to the Bot Adapter for processing.

The following code snippet shows how to configure the messaging endpoint:

// Create HTTP server.
const server = restify.createServer();
server.use(restify.plugins.bodyParser());
server.listen(process.env.port || process.env.PORT || 3978, () => {
  console.log(`\nBot Started, ${server.name} listening to ${server.url}`);
});

// Listen for incoming requests.
server.post("/api/messages", async (req, res) => {
  await adapter.process(req, res, async (context) => {
    await searchApp.run(context);
  });
});

The Bot Adapter is used to connect the bot service with the web service. The Bot Adapter is responsible for processing incoming requests from the bot service and invoking the bot activity handler. The web service authenticates with the bot service using the Microsoft Entra app registration credentials used to register the Azure Bot resource with the Bot Framework.

The following code snippet shows how to configure the Bot Adapter in the web service:

const credentialsFactory = new ConfigurationServiceClientCredentialFactory(config);

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(
  {},
  credentialsFactory
);

const adapter = new CloudAdapter(botFrameworkAuthentication);

To process the user search query and return search results, implement a Bot Activity Handler that inherits from the TeamsActivityHandler class provided by the Bot Framework SDK and override the handleTeamsMessagingExtensionQuery method.

The following code snippet shows how to configure the Bot Activity Handler in the web service:

export class SearchApp extends TeamsActivityHandler {

  public async handleTeamsMessagingExtensionQuery(
    context: TurnContext,
    query: MessagingExtensionQuery
  ): Promise<MessagingExtensionResponse> {

    const text = query.parameters[0]?.value as string ?? "";
    var template = new ACData.Template(card);

    return {
      composeExtension: {
        type: 'result',
        attachmentLayout: AttachmentLayoutTypes.List,
        attachments: [
          {
            contentType: 'application/vnd.microsoft.card.adaptive',
            content: template.expand({ $root: { text } }),
            preview: CardFactory.thumbnailCard(text)
          },
        ],
      },
    };
  }
}

Configure search command

The app manifest is a JSON file that defines the app's metadata and configuration. It defines the functionalities the app provides, such as message extensions. The app manifest is included within the app package. The app package is a ZIP file that you upload to Microsoft Teams to install the app.

The following code snippet shows how a search command is defined in the app manifest:

"composeExtensions": [
  {
    "botId": "4cc3ac43-d581-403d-8bbf-ff9c0fbf3fb2",
    "commands": [
      {
        "id": "Search",
        "context": [
          "compose",
          "commandBox"
        ],
        "description": "Find products by name or by target audience",
        "title": "Products",
        "type": "query",
        "parameters": [
          {
            "name": "ProductName",
            "title": "Product name",
            "description": "The name of the product as a keyword",
            "inputType": "text"
          }
        ]
      }
    ]
  }
]

A command can contain one or more parameters. A parameter is a field that is displayed in the user interface. In this example, the command has a single parameter named ProductName. The parameter is a text field that the user fills in with the name of the product they're searching for.

Teams Toolkit for Visual Studio Code

Teams Toolkit for Visual Studio Code is an extension that provides tools to create, debug, and deploy Microsoft Teams apps. Teams Toolkit integrates with Visual Studio Code to streamline the development process and provide a seamless experience for building Microsoft Teams apps.

Teams Toolkit scaffolds a Node.js project that contains the necessary files and dependencies to build a Microsoft Teams app.

Teams Toolkit integrates with the Dev tunnels CLI to enable communication between the bot service and the locally running web service. Dev tunnels expose the web service beyond your machine to allow the bot service to reach it.

Feedback

Was this page helpful?