Microsoft Teams

If your company runs on Microsoft Teams, your assistant should too. Docana connects through an Azure Bot: you register the bot in the Azure Portal, hand Docana the credentials, and Teams messages reach your assistant while the answers go back to the conversation. Setup takes about 20 minutes and you do it once.

You'll switch between two screens, the Azure Portal and Docana, so keep both open in separate tabs. Find the channel in your application: open Channels, then Teams.

Prerequisites

• An active Azure subscription with permission to create resources
• Administrator rights on your organization's Microsoft Teams
• Admin or editor access to the Docana application that will answer in Teams

The Azure Bot resource runs on the F0 (Free) tier, which covers Teams use. Teams itself needs Microsoft 365 licenses, which most companies already have.

Step 1: Create the bot in Azure

In the Azure Portal, create a new Azure Bot resource:

• Bot handle: a name of your choice, like docana_assistant
• Subscription and Resource group: your organization's, or create a new group
• Pricing tier: click Change plan and pick F0 (Free)
• Type of App: Single Tenant
• Creation type: keep Create new Microsoft App ID

Click Review + create, then Create. It takes a minute or two.

Type of App must be Single Tenant

Single Tenant is what Microsoft offers today, and it's what keeps the bot usable only inside your organization. The managed-identity option only works for bots hosted on Azure.

Step 2: Collect the three credentials

Open the new resource and go to Configuration in the side menu. Copy two values from there:

• Microsoft App ID: the bot's identifier
• App Tenant ID: your organization's directory identifier

The Azure Bot Configuration page, showing Bot Type set to Single Tenant, the Microsoft App ID with the Manage Password link beside it, and the App Tenant ID

Still on Configuration, click Manage Password next to the Microsoft App ID. That takes you to Certificates & secrets. Click New client secret, give it a description like docana, choose an expiry, and confirm with Add.

The Certificates & secrets page listing client secrets, with the Value column holding the secret and the Secret ID column beside it

Copy the password right away

The secret shows once, in the Value column. Leave the page and it's hidden forever, and you'll have to generate a new one. Copy Value, not Secret ID, which is a different value.

Step 3: Fill in the channel in Docana

Open your application, go to Channels, then Teams, and enter the three values:

• Tenant ID: the App Tenant ID from step 2
• App ID: the Microsoft App ID from step 2
• App Password: the secret from step 2

Turn on Enabled and click Save. On the same screen, Agent Routing decides who answers: leave it on Automatic for the application assistant, or pick Route to Specific Agent to send Teams conversations to one agent.

Enter the Teams tenant ID, app ID, and app password, then copy the Webhook URL. Credentials are blank in this local example.

Then find the Webhook URL field on the same screen and copy the address. It looks like this:

https://platform.docana.com/api/channels/teams/your_application_id_here/

That's where Teams will send incoming messages.

Step 4: Point Azure at Docana and turn Teams on

Back in the Azure Portal, on the bot's Configuration page, paste the copied address into Messaging endpoint and click Apply.

Then open Channels in the bot's side menu and click Microsoft Teams. Accept Microsoft's terms and confirm with Apply. This is the step that lets the bot send and receive Teams messages. Skip it and the configuration looks complete while the bot stays unreachable.

The Open in Teams link on that same channels page opens a direct chat with the bot, which is the fastest way to test it.

The Azure Bot Channels page with Microsoft Teams connected and healthy, and the Open in Teams link in the Actions column

Give the whole team access

The Azure link works for you, but it doesn't put the assistant in anyone else's Teams. For that, your IT team publishes a Teams app that points at the bot's App ID, through the Teams Admin Center or the Developer Portal.

The Azure Portal doesn't hand you that app. It registers the bot and gives you the Open in Teams test link, and nothing more. The package is a separate artifact you either build yourself or generate in the Developer Portal.

A Teams app package is a ZIP with three files: manifest.json, a 192x192 color icon, and a 32x32 transparent outline icon. Start from ours:

Download the Docana Teams app package (3 KB)

Unzip it, open manifest.json, and replace both id and botId with your bot's Microsoft App ID. Change packageName to your own reverse-domain name while you're there. The rest works as shipped:

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
  "manifestVersion": "1.16",
  "version": "1.0.0",
  "id": "your_bot_app_id_here",
  "packageName": "com.yourcompany.docana",
  "developer": {
    "name": "Docana",
    "websiteUrl": "https://docana.com",
    "privacyUrl": "https://docana.com/privacy",
    "termsOfUseUrl": "https://docana.com/terms"
  },
  "name": {
    "short": "Docana",
    "full": "Docana Assistant"
  },
  "description": {
    "short": "The Docana assistant in Microsoft Teams",
    "full": "Chat with the Docana assistant from Teams. It answers from your application's knowledge."
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "accentColor": "#0B5FFF",
  "bots": [
    {
      "botId": "your_bot_app_id_here",
      "scopes": ["personal", "team", "groupChat"],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": ["platform.docana.com"]
}

The scopes list is what makes the bot usable in direct chats (personal), in channels (team), and in group chats (groupChat).

Zip the three files back up with them at the root of the archive, not inside a wrapping folder, then upload the ZIP in the Teams Admin Center under Teams apps, then Manage apps. The upload lives behind the Actions menu, as Upload new app.

The Manage apps page in the Teams Admin Center with the Actions menu open on Upload new app

Swap in your own color.png and outline.png if you'd rather the app carry your company's branding than Docana's. Ask your Docana contact if you'd like us to walk through this with you.

How conversations work

• Direct chat: message the bot like you'd message a colleague. It answers from your application's knowledge
• In channels: once the app is added to a channel, mention the bot with @ and its name to bring it into the conversation
• History: conversations are recorded in Docana and feed the usage reports and the insights about what your team asks most

If something doesn't work

Credential changes take a few minutes to take effect, so give it a moment before digging in.

Situation	Likely cause and fix
The bot doesn't answer at all	Check that the Microsoft Teams channel is enabled on the bot's Channels page in Azure, and that the Messaging endpoint is correct
An authentication error	The App ID or App Password don't match. Generate a new secret in Azure and re-enter it in Docana. Copy the Value field, not the Secret ID
The channel shows as not configured	All three fields (Tenant ID, App ID, App Password) have to be filled in and saved. One blank field blocks the connection
Only some people can use it	The channel may be limited to users with access to the application. Turn on Public in the channel settings, or grant those people access in Docana
Lost the App Password	It can't be recovered. Generate a new one in Certificates & secrets and update it in Docana

Still stuck? Talk to your Docana contact or write to [email protected].

Next steps

• Slack: The same assistant for Slack-first teams
• Web Widget: Put it on your website too
• Conversation Insights: See what your team asks most