B2C Customer-Agent Messaging Teams App

Overview

This is a sample application to show how we can build a custom Teams App that can interface with an Azure Communication Services instance, enabling the two systems to work together while keeping their backend environments and identity configurations separate.

This sample includes three standalone applications: CustomerApp, BusinessApp, and Server. Together, they provide a comprehensive customer support experience. The overall view of the system is shown below:

1. An Azure Communication Services instance that enables the chat experience.
2. CustomerApp: A web application used by customers to interact with agents. Users of this CustomerApp will be assigned Azure Communication Services identities.
3. BusinessApp: A web application hosted within a custom Teams application and deployed to Teams through an iframe inside the Teams client. Agents utilize this app within their Teams client.
   • This app leverages Teams’ Single Sign-On (SSO) to retrieve the Teams user ID.
   • The Azure Communication Services instance is not directly connected to the Teams environment. Identity mapping is required to connect the BusinessApp users who have a Teams user ID, to the CustomerApp users' Azure Communication Services identities.
   • For this sample app, an Azure Communication Services identity needs to be manually created for each BusinessApp user, and the identity mapping stored in environment variables (steps are shown below in the AgentUsers section).
   • Once the linkage is set, the BusinessApp will use the Teams user ID to retrieve the Azure Communication Services ID, and use that ID to retrieve threads and communicate with CustomerApp users.
4. Azure Cloud: Where the CustomerApp and the BusinessApp are hosted.
5. Server app: A web API that provides the necessary server-side functionality for the BusinessApp and the CustomerApp.
6. Database: An Azure Cosmos database to store metadata related to chat threads, such as their status.

Key Features

• Seamless Chat Start: Customers can easily initiate a conversation by entering their name and question, instantly connecting with a random available agent.
• Integrated Agent Interface: Agents manage and respond to customer messages directly within the Microsoft Teams environment.
• Effortless Conversation Management: Agents can handle multiple customer conversations simultaneously and resolve them when complete. Resolved chats are moved to a separate tab, and customers are notified that the conversation has ended.
• Chat Continuity: Customers can resume conversations at any time simply by sending a new message, reactivating the chat.
• Easy Exit for Customers: Customers can exit the chat anytime, which revokes their access and informs the agent of their departure. Agents are instantly notified with a toast message showing which customer has exited, keeping them informed in real-time.

Prerequisites

• Visual Studio Code (Stable Build).
• Node.js, supported versions: 20 | 22.
• Create an Azure account with an active subscription. For details, see Create an account for free.
• Create an Azure Communication Services resource. For details, see Create an Azure Communication Resource. You'll need to record your resource connection string for this sample app.
• Create an Azure Cosmos DB for NoSQL account. For details, see Create an Azure Cosmos DB account. You'll need to record the URI and PRIMARY KEY for this sample app.
• A Microsoft 365 account for development.
• Set up your dev environment for extending Teams apps across Microsoft 365. Please note that after you enrolled your developer tenant in Office 365 Target Release, it may take couple days for the enrollment to take effect.
• Teams Toolkit Visual Studio Code Extension version 5.0.0 and higher or Teams Toolkit CLI.

Code structure

• BusinessApp - A custom Teams app for agents to provide customer support

  • /index.tsx - Entry point of this app
  • /src - The source code for the frontend of the Teams custom application
  • /.vscode - VSCode files for debugging
  • /appPackage - Teams application manifest
  • /env - Environment files
  • /infra - files for provisioning Azure resources The following are Teams Toolkit specific project files. You can visit a complete guide on Github to understand how Teams Toolkit works
  • /teamsapp.yml - This is the main Teams Toolkit project file. The project file defines two primary things: Properties and configuration Stage
  • /teamsapp.local.yml - This overrides teamsapp.yml with actions that enable local execution and debugging
  • /aad.manifest.json - This file defines the configuration of Microsoft Entra app. This template will only provision single tenant Microsoft Entra app

• CustomerApp - A web app where customers can start an Azure Communication Services chat without a Microsoft Teams account

  • /index.tsx - Entry point of this app

• Server - A server app that supports the BusinessApp and the CustomerApp

  • /app.ts - Entry point of this app
  • /appsettings.json.sample - The sample file for all the environment variables needed to run the Server app

Before running the sample for the first time

1. Open an instance of PowerShell, Windows Terminal, Command Prompt, or equivalent, and navigate to the directory that you'd like to clone the sample to and clone the repo.

   git clone https://github.com/Azure-Samples/communication-services-messaging-teams-app.git

2. Copy Server/appsettings.json.sample and remove the .sample extension.

3. Fill in the following variables in the newly created Server/appsettings.json file:

   1. ResourceConnectionString: Use the Connection String from the Azure portal. For more information on connection strings, see Create an Azure Communication Resources.
   2. EndpointUrl: Use the Endpoint from the Azure portal. For more information on endpoint strings, see Create an Azure Communication Resources.
   3. AdminUserId: Create a new Azure Communication Services user as a server user to add new users to the chat thread. You can get this value by clicking on Identities & User Access Tokens in Azure portal. Generate a user with Chat scope. Then use the Identity value for this variable. For more information on identity strings, see Create and manage access tokens.
   4. CosmosDBEndpoint: Use the URI value from the Azure portal's Cosmos DB account. For more information on Azure Cosmos DB account, see Create an Azure Cosmos DB account.
   5. CosmosDBKey: Use the PRIMARY KEY value from the Azure portal's Cosmos DB account. For more information on Azure Cosmos DB account, see Create an Azure Cosmos DB account.
   6. AgentUsers: An array of agent users that can use the BusinessApp. Each agent user object should contain the following values:
      1. teamsUserId:
         1. Login to the Azure portal tenant that you want to build the BusinessApp with (The same Microsoft 365 account should be used for the Start the BusinessApp) step below.
         2. Use the Object ID from the Azure portal. For more information on user's object Id, see Find the user object ID.
      2. acsUserId: Each agent should be linked to an Azure Communication Services user. The BusinessApp will use this credential to retrieve chat threads data and to communicate with customers in the Azure Communication Services environment. You can get this value by clicking on Identities & User Access Tokens in Azure portal. Generate a user with Chat scope. Then use the Identity value for this variable. For more information on identity strings, see Create and manage access tokens.
      3. displayName: Assign a display name for this agent.

Local run

1. Start the CustomerApp

   cd CustomerApp && npm install && npm start

   This will open a client server on port 3000 that serves the website files.
   

2. Start the Server app

   cd Server && npm install && npm run start:dev

   This will start an api server on port 8080 that performs functionality like minting tokens for chat participants and storing the chat thread.
   

3. Start the BusinessApp

   1. Open a new VS Code instance with BusinessApp as the top level folder.
   2. Select the Teams Toolkit icon on the left in the VS Code toolbar.
   3. In the Account section, sign in with your Microsoft 365 account if you haven't already.
   4. Press F5 to start debugging which launches your app in Teams using a web browser. Select Debug in Teams (Edge) or Debug in Teams (Chrome).
   5. When Teams launches in the browser, select the Add button in the dialog to install the BusinessApp to Teams.

   This will open a browser window with the BusinessApp running inside Teams web client.

Deploy

1. Preparation for deployment:
   1. Prepare the App manifest and App icons. For details, see Teams app package.
   2. Edit app Basic information, App features, Permissions etc. through Developer Portal. For details, see To update Manifest file and app package.
2. Deploy the BusinessApp: BusinessApp is a Teams App. You can deploy the BusinessApp following this instruction and publish it either using Teams Toolkit or using Developer Portal.
3. Deploy the CustomerApp: CustomerApp is a React app. You can host it with a hosting provider such as Azure Static Web Apps. For details, see Deploy your web app to Azure Static Web Apps .
4. Deploy the Server app: Server app is a Node.js app. You can host it with a hosting provider such as Azure App Service. For details, see Deploy a Node.js web app in Azure.

Add additional features:

• File sharing: To enable the file sharing feature, please follow this quickstart as an example.

Additional Reading

• Embed chat in a Microsoft Teams custom app
• Azure Communication Services - UI Library - To learn more about what the @azure/communication-react package offers.
• Azure Communication Chat SDK - To learn more about the chat web sdk
• Add or manage the environment
• Create multi-capability app
• Use an existing Microsoft Entra application
• Customize the Teams app manifest
• Host your app in Azure by provision cloud resources and deploy the code to cloud
• Collaborate on app development
• Set up the CI/CD pipeline
• Enable the app for multi-tenant
• Preview the app on mobile clients

Telemetry

The B2C Customer-Agent Messaging Teams App collects usage data and sends it to Microsoft to help improve our products and services. Read our Privacy Statement and Data Collection Notice to learn more. Learn more in our FAQ.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.