Deployment guide

Prerequisites

To begin, you will need:

• A name for your Teams app. For example, "Contoso Stickers"
• Sticker images, which must be:
  • PNG, JPEG, or GIF format
  • Less than 1MB in total size
  • No more than 1000px in width or height. For best results, we recommend a maximum size of 300x300.
• An Azure subscription where you can create the following kinds of resources:
  • Azure Function
  • App service
  • App service plan
  • Bot channels registration
  • Storage account
  • Application Insights
• A copy of the Stickers app GitHub repo (https://github.com/officedev/microsoft-teams-stickers-app)

Step 1: Register Azure AD applications

Register two Azure AD applications in your tenant’s directory: one for the messaging extension, and another for the configuration app.

1. Log in to the Azure Portal for your subscription, and go to the “App registrations” blade at https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps.

2. Click on "New registration", and create an Azure AD application.

   1. Name: The name of your Teams app. For example, "Contoso Stickers".
   2. Supported account types: Select "Account in this organizational directory only"
   3. Leave the "Redirect URI" field blank.

   

3. Click on the "Register" button.

4. When the app is registered, you'll be taken to the app's "Overview" page. Copy the following IDs; we will need them later.

   • Application (client) ID
   • Directory (tenant) ID

   

5. Go back to “App registrations”, then repeat steps 2-4 to create another Azure AD application for the configuration app. We advise appending “Configuration” to the name of this app; for example, “Contoso Stickers Configuration”.

At this point you have 3 unique GUIDs:

• Two application (client) IDs: one for the messaging extension, and another for the configuration app
• Tenant ID, which is the same for the two apps that you registered

Step 2: Deploy to your Azure subscription

1. Click on the "Deploy to Azure" button below.

   

2. When prompted, log in to your Azure subscription.

3. Azure will create a "Custom deployment" based on the ARM template and ask you to fill in the template parameters.

   

4. Select a subscription and resource group.

   • We recommend creating a new resource group.
   • The resource group location MUST be in a datacenter that supports Application Insights. For an up-to-date list, refer to https://azure.microsoft.com/en-us/global-infrastructure/services/?products=monitor, under "Application Insights".

5. Enter a "Base Resource Name", which the template uses to generate names for the other resources.

   • The app service names [Base Resource Name] and [Base Resource Name]-config must be available. For example, if you select contosostickers as the base name, the names contosostickers and contosostickers-config must be free; otherwise, the deployment will fail with a Conflict error.
   • Remember the base resource name that you selected. We will need it later.

6. Fill in the various IDs in the template:

   1. Messaging Extension App Id: The application (client) ID of the messaging extension app
   2. Config App Client Id: The application (client) ID of the configuration app
   3. Tenant Id: The tenant ID

   Make sure that the GUIDs are copied as-is, with no extra spaces. The template checks that the IDs are exactly 36 characters.

7. Fill in the "Config Admin UPN List", which is a semicolon-delimited list of users who will be allowed to access the configuration app.

   • For example, to allow Megan Bowen (meganb@contoso.com) and Adele Vance (adelev@contoso.com) to access the configuration app, set this parameter to meganb@contoso.com;adelev@contoso.com.
   • You can change this list later by going to the configuration app service's "Configuration" blade.

8. Agree to the Azure terms and conditions by clicking on the check box “I agree to the terms and conditions stated above” located at the bottom of the page.

9. Click on “Purchase” to start the deployment.

10. Wait for the deployment to finish. You can check the progress of the deployment from the "Notifications" pane of the Azure Portal.

Step 3: Finish setting up the configuration app

1. Note the location of the configuration app that you deployed, which is https://[BaseResourceName]-config.azurewebsites.net. For example, if you chose “contosostickers” as the base name, the configuration app will be at https://contosostickers-config.azurewebsites.net.

2. Go back to the “App registrations” page at https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps. Select the configuration app that you created in Step 1.5.

3. Under “Manage”, click on “Authentication” to bring up authentication settings.

4. Add a new entry to “Redirect URIs”:

   1. Type: Web
   2. Redirect URI: Location (URL) of your configuration app. This is the URL from Step 3.1.

   

5. Under "Implicit grant", check "ID tokens".

   

6. Click “Save” to commit your changes.

Step 4: Add your custom stickers

Upload your custom stickers. To get you started, we have a set of sample stickers in the deployment\stickers folder.

1. Go to the configuration app, which is at https://[BaseResourceName]-config.azurewebsites.net. For example, if you chose “contosostickers” as the base name, the configuration app will be at https://contosostickers-config.azurewebsites.net.

2. When prompted, log in as one of the users that you specified in “Config Admin UPN List”.

3. For each sticker:

   1. Click on "Add new".
   2. Click on “Choose file” and select the image.
   3. Update the name and keywords. Keywords should be separated by commas.
   4. Click on “Create” to save the image.

4. When you’re done adding stickers, click on “Update messaging extension” so that your changes are reflected in the messaging extension.

   

Step 5: Create the Teams app package

1. Open the manifest\manifest.json file in a text editor.

2. Change the “botId” to your messaging extension’s application ID. This is the same GUID that you entered in the template under “Messaging Extension App Id”.

3. Change the fields in the manifest to values appropriate for your organization.

   • developer.name (What's this?)
   • developer.websiteUrl
   • developer.privacyUrl
   • developer.termsOfUseUrl
   • name.short (What's this?)
   • description.short (What's this?)
   • description.full

4. Create a ZIP package with manifest.json, color.png, and outline.png. The two image files are the icons for your app in Teams. You can customize your app even more by replacing them with other images, as long as they meet the app icon guidelines.

   • Make sure that the 3 files are the top level of the ZIP package, with no nested folders.

Step 6: Run the app in Microsoft Teams

1. If your tenant has sideloading apps enabled, you can install your app personally or to a team by following the instructions below.

   • Upload package to a team or personally using the Store: https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/apps/apps-upload#upload-your-package-into-a-team-or-conversation-using-the-store
   • Upload package to a team using the Apps tab: https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/apps/apps-upload#upload-your-package-into-a-team-using-the-apps-tab

2. You can also upload it to your tenant's app catalog, so that it can be available for everyone in your tenant to install: https://docs.microsoft.com/en-us/microsoftteams/tenant-apps-catalog-teams

Troubleshooting

Please see our Troubleshooting page.