Create a personal tab

Article
02/28/2023
14 minutes to read

Personal tabs, along with personally-scoped bots, are part of personal apps and are scoped to a single user. They can be pinned to the left pane for easy access. You can also reorder your personal tabs.

Ensure that you have all the prerequisites to build your personal tab.

Note

This topic reflects version 2.0.x of the Microsoft Teams JavaScript client library (TeamsJS). If you are using an earlier version, refer to the TeamsJS library overview for guidance on the differences between the latest TeamsJS and earlier versions.

Create a personal tab with Node.js

At the command prompt, install the Yeoman and gulp-cli packages by entering the following command after installing the Node.js:
```
npm install yo gulp-cli --global
```
At the command prompt, install Microsoft Teams app generator by entering the following command:
```
npm install generator-teams --global
```

Following are the steps to create a personal tab:

Generate your application with a personal tab
Add a content page to the personal tab
Create your app package
Build and run your application
Establish a secure tunnel to your personal tab
Upload your application to Teams

Generate your application with a personal tab

At the command prompt, create a new directory for your personal tab.
Enter the following command in your new directory to start the Microsoft Teams app generator:
```
yo teams
```
Provide your values to a series of questions prompted by Microsoft Teams app generator to update your manifest.json file.
Series of questions to update your manifest.json file
- What is your solution name?
  
  The solution name is your project name. You can accept the suggested name by selecting Enter.
- Where do you want to place the files?
  
  You're currently in your project directory. Select Enter.
- Title of your Microsoft Teams app project?
  
  The title is your app package name and is used in the app manifest and description. Enter a title or select Enter to accept the default name.
- Your (company) name? (max 32 characters)
  
  Your company name will be used in the app manifest. Enter a company name or select Enter to accept the default name.
- Which manifest version would you like to use?
  
  Select the default schema.
- Quick scaffolding? (Y/n)
  
  The default is yes; enter n to enter your Microsoft Partner ID.
- Enter your Microsoft Partner Id, if you have one? (Leave blank to skip)
  
  This field isn't required and must be used only if you're already part of the Microsoft Partner Network.
- What do you want to add to your project?
  
  Select ( * ) A Tab.
- The URL where you will host this solution?
  
  By default, the generator suggests an Azure website URL. You're only testing your app locally, so a valid URL isn't necessary.
- Would you like show a loading indicator when your app/tab loads?
  
  Choose not to include a loading indicator when your app or tab loads. The default is no, enter n.
- Would you like personal apps to be rendered without a tab header-bar?
  
  Choose not to include personal apps to be rendered without a tab header-bar. Default is no, enter n.
- Would you like to include Test framework and initial tests? (y/N)
  
  Choose not to include a test framework for this project. The default is no, enter n.
- Would you like to include ESLint support? (y/N)
  
  Choose not to include ESLint support. The default is no, enter n.
- Would you like to use Azure Applications Insights for telemetry? (y/N)
  
  Choose not to include Azure Application Insights. The default is no; enter n.
- Default Tab Name (max 16 characters)?
  
  Name your tab. This tab name is used throughout your project as a file or URL path component.
- What kind of Tab would you like to create?
  
  Use the arrow keys to select Personal (static).
- Do you require Microsoft Azure Active Directory (Azure AD) Single-Sign-On support for the tab?
  
  Choose not to include Azure AD Single-Sign-On support for the tab. The default is yes, enter n.
Note

In a tab, the tab home page appears only when the user selects the back button (or moves out of the tab) and comes back to the home page. The tab doesn't maintain or retain the previous state by design.

Add a content page to the personal tab

Create a content page and update the existing files of the personal tab application:

Create a new personal.html file in your Visual Studio Code with the following markup:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>
            <!-- Todo: add your a title here -->
        </title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <!-- inject:css -->
        <!-- endinject -->
    </head>
        <body>
            <h1>Personal Tab</h1>
            <p><img src="/assets/icon.png"></p>
            <p>This is your personal tab!</p>
        </body>
</html>

Save personal.html in your application's public folder in the following location:
```
./src/public/<yourDefaultTabNameTab>/personal.html
```
Open manifest.json from the following location in your Visual Studio Code:
```
 ./src/manifest/manifest.json
```
Add the following to the empty staticTabs array (staticTabs":[]) and add the following JSON object:
```
{
    "entityId": "personalTab",
    "name": "Personal Tab ",
    "contentUrl": "https://{{PUBLIC_HOSTNAME}}/<yourDefaultTabNameTab>/personal.html",
    "websiteUrl": "https://{{PUBLIC_HOSTNAME}}",
    "scopes": ["personal"]
}
```
Important

The path component yourDefaultTabNameTab is the value that you entered in the generator for Default Tab Name plus the word Tab.

For example: DefaultTabName is MyTab then /MyTabTab/
Update the contentURL path component yourDefaultTabNameTab with your actual tab name.
Save the updated manifest.json file.
Open Tab.ts in your Visual Studio Code from the following path to provide your content page in an iFrame:
```
./src/server/<yourDefaultTabNameTab>/<yourDefaultTabNameTab>.ts
```

Add the following to the list of iFrame decorators:

 @PreventIframe("/<yourDefaultTabName Tab>/personal.html")

Save the updated file. Your tab code is complete.

Create your app package

You must have an app package to build and run your application in Teams. The app package is created through a gulp task that validates the manifest.json file and generates the zip folder in the ./package directory. At the command prompt, use the command gulp manifest.

Build and run your application

Build your application

Enter the following command at the command prompt to transpile your solution into the ./dist folder:

gulp build

Run your application

At the command prompt, enter the following command to start a local web server:
```
gulp serve
```
Enter http://localhost:3007/<yourDefaultAppNameTab>/ in your browser to view your application's home page.
Browse http://localhost:3007/<yourDefaultAppNameTab>/personal.html, to view your personal tab.

Establish a secure tunnel to your tab

At the command prompt exit the localhost and enter the following command to establish a secure tunnel to your tab:

gulp ngrok-serve

After your tab is uploaded to Microsoft Teams through ngrok and successfully saved, you can view it in Teams until your tunnel session ends.

Upload your application to Teams

Go to Teams and select Apps .
Select Manage your apps > Upload an app > Upload a custom app.
Go to your project directory, browse to the ./package folder, select the zip folder, and choose Open.
Select Add in the dialog. Your tab is uploaded to Teams.
In the left pane of Teams, select ellipses ●●● and then choose your uploaded app to view your personal tab.

Now you've successfully created and added your personal tab in Teams.

As you have your personal tab in Teams, you can also reorder your personal tab.

Create a personal tab with ASP.NET Core

At the command prompt, create a new directory for your tab project.
Clone the sample repository into your new directory using the following command or you can download the source code and extract the files:
```
git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git
```

Following are the steps to create a personal tab:

Generate your application with a personal tab
Update and run your application
Establish a secure tunnel to your tab
Update your app package with Developer Portal
Preview your app in Teams

Generate your application with a personal tab

Open Visual Studio and select Open a project or solution.
Go to Microsoft-Teams-Samples > samples > tab-personal > razor-csharp folder and open PersonalTab.sln.
In Visual Studio, select F5 or choose Start Debugging from your application's Debug menu to verify if the application has loaded properly. In a browser, go to the following URLs:
- <http://localhost:3978/>
- <http://localhost:3978/personalTab>
- <http://localhost:3978/privacy>
- <http://localhost:3978/tou>

Review the source code

Startup.cs

This project was created from an ASP.NET Core 3.1 web application empty template with the Advanced - Configure for HTTPS check box selected at setup. The MVC services are registered by the dependency injection framework's ConfigureServices() method. Additionally, the empty template doesn't enable serving static content by default, so the static files middleware is added to the Configure() method using the following code:

public void ConfigureServices(IServiceCollection services)
  {
      services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
  }
public void Configure(IApplicationBuilder app)
  {
    app.UseStaticFiles();
    app.UseMvc();
  }

wwwroot folder

In ASP.NET Core, the web root folder is where the application looks for static files.

Index.cshtml

ASP.NET Core treats files called Index as the default or home page for the site. When your browser URL points to the root of the site, Index.cshtml is displayed as the home page for your application.

AppManifest folder

This folder contains the following required app package files:

A full color icon measuring 192 x 192 pixels.
A transparent outline icon measuring 32 x 32 pixels.
A manifest.json file that specifies the attributes of your app.

These files must be zipped in an app package for use in uploading your tab to Teams. Teams loads the contentUrl specified in your manifest, embeds it in an <iframe>, and renders it in your tab.

.csproj

In Visual Studio Solution Explorer, right-click on the project and select Edit Project File. At the end of the file, you can see the following code that creates and updates your zip folder when the application builds:

<PropertyGroup>
    <PostBuildEvent>powershell.exe Compress-Archive -Path \"$(ProjectDir)AppManifest\*\" -DestinationPath \"$(TargetDir)tab.zip\" -Force</PostBuildEvent>
  </PropertyGroup>

  <ItemGroup>
    <EmbeddedResource Include="AppManifest\icon-outline.png">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
    <EmbeddedResource Include="AppManifest\icon-color.png">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
    <EmbeddedResource Include="AppManifest\manifest.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
  </ItemGroup>

Update and run your application

Open Visual Studio Solution Explorer and go to Pages > Shared folder and open _Layout.cshtml and add the following to the <head> tags section:

<script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.4.1.min.js"></script>
<script src="https://res.cdn.office.net/teams-js/2.0.0/js/MicrosoftTeams.min.js" integrity="sha384-QtTBFeFlfRDZBfwHJHYQp7MdLJ2C3sfAEB1Qpy+YblvjavBye+q87TELpTnvlXw4" crossorigin="anonymous"></script>

In Visual Studio Solution Explorer, open PersonalTab.cshtml from Pages folder and add microsoftTeams.app.initialize() in the <script> tags.
Select Save.
In Visual Studio, select F5 or choose Start Debugging from your application's Debug menu.

Establish a secure tunnel to your tab

At the command prompt in the root of your project directory, run the following command to establish a secure tunnel to your tab:

ngrok http 3978 --host-header=localhost

Update your app package with Developer Portal

Go to Developer portal.
Open Apps and select Import app.
The app package file name is tab.zip and it's available at /bin/Debug/netcoreapp3.1/tab.zip path.
Select tab.zip and open it in the Developer Portal.
A default App ID is created and populated in Basic information section.
Add the Short and Long description for your app in Descriptions.
In Developer Information, add the required details and in Website (must be a valid HTTPS URL) give your ngrok HTTPS URL.
In App URLs, update the Privacy policy to https://<yourngrokurl>/privacy and Terms of use to https://<yourngrokurl>/tou and select Save.
In App features, select Personal app > Create your first personal app tab and enter the name and update the Content URL with https://<yourngrokurl>/personalTab. Leave the Website URL field blank and select Context as personalTab from the dropdown list and select Confirm.
Select Save.
In the Domains section, domains from your tabs must contain your ngrok URL without the HTTPS prefix <yourngrokurl>.ngrok.io.

Preview your app in Teams

Select Preview in Teams from the Developer Portal toolbar, Developer Portal informs you that your app is sideloaded successfully. The Add page appears for your app in Teams.
Select Add to load the tab in Teams. Your tab is now available in Teams.

Now you've successfully created and added your personal tab in Teams.

As you have your personal tab in Teams, you can also reorder your personal tab.

Create a personal tab with ASP.NET Core MVC

At the command prompt, create a new directory for your tab project.
Clone the sample repository into your new directory using the following command or you can download the source code and extract the files:
```
git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git
```

Following are the steps to create a personal tab:

Generate your application with a personal tab
Update and run application
Establish a secure tunnel to your tab
Update your app package with Developer Portal
Preview your app in Teams

Generate your application with a personal tab

Open Visual Studio and select Open a project or solution.
Go to Microsoft-Teams-Samples > samples > tab-personal > mvc-csharp folder and open PersonalTabMVC.sln in Visual Studio.
In Visual Studio, select F5 or choose Start Debugging from your application's Debug menu to verify if the application has loaded properly. In a browser, go to the following URLs:
- <http://localhost:3978>
- <http://localhost:3978/personalTab>
- <http://localhost:3978/privacy>
- <http://localhost:3978/tou>

Review the source code

Startup.cs

public void ConfigureServices(IServiceCollection services)
  {
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
  }
public void Configure(IApplicationBuilder app)
  {
    app.UseStaticFiles();
    app.UseMvc();
  }

wwwroot folder

In ASP.NET Core, the web root folder is where the application looks for static files.

AppManifest folder

This folder contains the following required app package files:

A full color icon measuring 192 x 192 pixels.
A transparent outline icon measuring 32 x 32 pixels.
A manifest.json file that specifies the attributes of your app.

These files must be zipped in an app package for use in uploading your tab to Teams. Teams loads the contentUrl specified in your manifest, embeds it in an iFrame, and renders it in your tab.

.csproj

In the Visual Studio Solution Explorer, right-click on the project and select Edit Project File. At the end of the file, you see the following code that creates and updates your zip folder when the application builds:

<PropertyGroup>
    <PostBuildEvent>powershell.exe Compress-Archive -Path \"$(ProjectDir)AppManifest\*\" -DestinationPath \"$(TargetDir)tab.zip\" -Force</PostBuildEvent>
  </PropertyGroup>

  <ItemGroup>
    <EmbeddedResource Include="AppManifest\icon-outline.png">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
    <EmbeddedResource Include="AppManifest\icon-color.png">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
    <EmbeddedResource Include="AppManifest\manifest.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
  </ItemGroup>

Models

PersonalTab.cs presents a message object and methods that are called from PersonalTabController when a user selects a button in the PersonalTab View.

Views

These views are the different views in ASP.NET Core MVC:

Home: ASP.NET Core treats files called Index as the default or home page for the site. When your browser URL points to the root of the site, Index.cshtml is displayed as the home page for your application.
Shared: The partial view markup _Layout.cshtml contains the application's overall page structure and shared visual elements. It also references the Teams Library.

Controllers

The controllers use the ViewBag property to transfer values dynamically to the Views.

Update and run your application

Open Visual Studio Solution Explorer and go to Views > Shared folder and open _Layout.cshtml, and add the following to the <head> tags section:

<script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.4.1.min.js"></script>
<script src="https://res.cdn.office.net/teams-js/2.0.0/js/MicrosoftTeams.min.js" integrity="sha384-QtTBFeFlfRDZBfwHJHYQp7MdLJ2C3sfAEB1Qpy+YblvjavBye+q87TELpTnvlXw4" crossorigin="anonymous"></script>

In Visual Studio Solution Explorer, open PersonalTab.cshtml from Views > PersonalTab folder and add microsoftTeams.app.initialize() inside the <script> tags.
Select Save.
In Visual Studio, select F5 or choose Start Debugging from your application's Debug menu.

Establish a secure tunnel to your tab

At the command prompt in the root of your project directory, run the following command to establish a secure tunnel to your tab:

ngrok http 3978 --host-header=localhost

Update your app package with Developer Portal

Go to Developer portal.
Open Apps and select Import app.
The name of your app package is tab.zip. It's available in the following path:
```
/bin/Debug/netcoreapp3.1/tab.zip
```
Select tab.zip and open it in the Developer Portal.
A default App ID is created and populated in Basic information section.
Add the Short and Long description for your app in Descriptions.
In Developer information, add the required details and in Website (must be a valid HTTPS URL) give your ngrok HTTPS URL.
In App URLs, update the Privacy policy to https://<yourngrokurl>/privacy and Terms of use to https://<yourngrokurl>/tou and select Save.
In App features, select Personal app > Create your first personal app tab and enter the name and update the Content URL with https://<yourngrokurl>/personalTab. Leave the Website URL field blank and select Context as personalTab from the dropdown list and select Confirm.
Select Save.
In the Domains section, Domains from your tabs must contain your ngrok URL without the HTTPS prefix <yourngrokurl>.ngrok.io.

Preview your app in Teams

Select Preview in Teams from the Developer Portal toolbar, Developer Portal informs you that your app is sideloaded successfully. The Add page appears for your app in Teams.
Select Add to load the tab on Teams. Your tab is now available in Teams.

Now you've successfully created and added your personal tab in Teams.

As you have your personal tab in Teams, you can also reorder your personal tab.

Reorder static personal tabs

Starting with manifest version 1.7, developers can rearrange all tabs in their personal app. You can move the bot chat tab, which always defaults to the first position, anywhere in the personal app tab header. Two reserved tab entityId keywords are declared, conversations and about.

If you create a bot with a personal scope, it appears in the first tab position in a personal app by default. If you want to move it to another position, you must add a static tab object to your manifest with the reserved keyword, conversations. The conversation tab appears on web or desktop depending on where you add the conversation tab in the staticTabs array.


{
   "staticTabs":[
      {
         
      },
      {
         "entityId":"conversations",
         "scopes":[
            "personal"
         ]
      }
   ]
}

Code sample

Sample name	Description	.NET	Node.js	Manifest
Tab personal	Sample app which showcases creating a custom channel/group tab with ASP.Net Core and MVC.	View	NA	View

Next step

Create a channel or group tab

Create a personal tab

Create a personal tab with Node.js

Generate your application with a personal tab

Add a content page to the personal tab

Create your app package

Build and run your application

Build your application

Run your application

Establish a secure tunnel to your tab

Upload your application to Teams

Create a personal tab with ASP.NET Core

Generate your application with a personal tab

Startup.cs

wwwroot folder

Index.cshtml

AppManifest folder

.csproj

Update and run your application

Establish a secure tunnel to your tab

Update your app package with Developer Portal

Preview your app in Teams

Create a personal tab with ASP.NET Core MVC

Generate your application with a personal tab

Startup.cs

wwwroot folder

AppManifest folder

.csproj

Models

Views

Controllers

Update and run your application

Establish a secure tunnel to your tab

Update your app package with Developer Portal

Preview your app in Teams

Reorder static personal tabs

Code sample

Next step

See also

Feedback

Additional resources

Additional resources