Microsoft Teams Integration

OttoBot answers questions about accounts, products and market signals in Microsoft Teams, using HG Insights data. HG Insights creates and runs the bot for your organization. You install it in your Teams tenant and approve the permissions it needs.

You don't create anything in Azure, and you don't handle any secrets.

Before you start

Confirm with HG Insights that your organization is activated for OttoBot in Teams. HG Insights sets up your bot and connects it to your organization first. If you skip this check, the app installs normally but never answers.

You need three roles. One person may hold all of them:

Role	What they do in this guide
HG Insights organization admin (owner or admin of your organization in HG Insights)	Downloads the Teams package
Teams administrator (tenant admin)	Uploads the app to your Teams tenant, and adds OttoBot to each team so they can accept its channel-message permission
Microsoft Entra administrator who can grant tenant-wide admin consent. If the consent screen lists Read all users' basic profiles, this must be a Global Administrator or Privileged Role Administrator; a Cloud Application Administrator or Application Administrator can accept only when it isn't listed	Grants admin consent so OttoBot can reply

Questions at any step: customersupport@hginsights.com.

1. Download the package

1. Sign in to HG Insights and open your organization's Integrations page.
2. On the Microsoft Teams card, select Download Teams package.

You get a file named ottobot-teams.zip. Upload it exactly as downloaded. Do not unzip it and re-zip it: Teams rejects a re-packed archive (see If something goes wrong).

If the card says HG Insights activates Teams for your organization, activation isn't finished yet. Contact HG Insights. If the button is greyed out next to Managed by an admin, ask an owner or admin of your organization to download it.

The package contains the app definition and two icons. It identifies your organization's bot. It contains no passwords, keys or secrets.

2. Upload and install

Choose one of these paths.

Option A: publish to your organization's app catalog (recommended)

This makes OttoBot available to everyone in your tenant under Apps → Built for your org.

1. In the Teams admin center, go to Teams apps → Manage apps.
2. Select Upload new app, then Upload, and choose ottobot-teams.zip.
3. Check that OttoBot now appears in the list, with Published version filled in. Make sure your app permission policies allow it for the users who need it.
4. In Teams, go to Apps → Built for your org → OttoBot → Add to a team, and pick the team and channel.

OttoBot isn't in "Built for your org" yet?

That's normal right after the upload. Microsoft says an app uploaded in the admin center becomes available to users after a few hours. In our testing, the Teams desktop app also showed the new app later than Teams on the web.

• Open Teams on the web (teams.microsoft.com) and look under Apps → Built for your org, or type OttoBot in the Apps search box. In our testing it appeared there first.
• In the desktop app, sign out and back in (and install any update Teams offers), or wait.
• Don't work around the wait by uploading the same ZIP with Option B: the catalog already holds this app, and Teams rejects a second upload of it.

The app is named just OttoBot. If your tenant also has older, hand-made OttoBot apps from HG Insights (for example "OttoBot (Staging)"), they are separate apps.

Option B: upload a custom app (sideload)

1. In the Teams client, go to Apps → Manage your apps → Upload an app → Upload a custom app.
2. Choose ottobot-teams.zip.
3. Select Add to a team and pick the team and channel. (Add installs it for personal use only.)

This option requires custom-app upload to be allowed for you. Three settings decide that:

• Org-wide app settings → Let users interact with custom apps in preview: on.
• Teams apps → Setup policies → Upload custom apps: on in the policy assigned to you.
• In the team itself, Manage team → Settings → Member permissions → Allow members to upload custom apps: on, unless you're a team owner.

The permission prompt at install

When OttoBot is added to a team, Teams asks for approval of the permission for the app to read that team's channel messages. Have a tenant administrator accept this prompt. Your tenant's consent settings decide who is allowed to; a tenant administrator always can. If the prompt isn't accepted, OttoBot misses thread replies (see If something goes wrong). The simplest way is for your Teams administrator to add OttoBot to each team.

This is the only time Teams asks for it. You can't grant it later from the admin center, where Manage apps → OttoBot → Permissions only shows what was granted. See Permissions you're approving for what it allows.

3. Grant admin consent

OttoBot's identity was registered by HG Insights. Before it can reply in your tenant, an Entra administrator must consent to it once for the whole tenant. Without this step OttoBot receives your messages but can never answer.

1. Get two values:

   • your Directory (Tenant) ID: Microsoft Entra admin center → Overview → Tenant ID;
   • OttoBot's App ID: HG Insights sends it to you with your activation confirmation. If you don't have it, unzip a copy of the package and read botId in manifest.json. Keep uploading the original ZIP.

2. As an Entra administrator, open this address in a browser, with your two values filled in:

   https://login.microsoftonline.com/<Directory (Tenant) ID>/adminconsent?client_id=<OttoBot App ID>

3. Review the permissions and select Accept.

Microsoft shows OttoBot as "unverified". That is expected: HG Insights has not completed Microsoft's publisher verification. HG Insights created this app registration specifically for your organization; no other customer uses it. (It lives in HG Insights' Microsoft Entra tenant and is set up so your tenant can consent to it.)

Directory read permission (User.ReadBasic.All), recommended. If the consent screen lists Read all users' basic profiles, approving it lets OttoBot recognize who is asking. The consent screen is accepted as a whole, so when this permission is listed, the person who selects Accept must be a Global Administrator or Privileged Role Administrator. If it isn't listed, OttoBot still works. Ask HG Insights if you want it added. See the next section for what you lose without it.

Permissions you're approving

Permission	Granted where	What it lets OttoBot do	If you don't grant it
Admin consent for the OttoBot app (creates OttoBot's service principal in your tenant)	Admin-consent link, step 3	Sign in as itself so it can send replies in your tenant	OttoBot receives messages but never replies
ChannelMessage.Read.Group (resource-specific consent, per team)	Permission prompt when OttoBot is added to a team; a tenant administrator must accept it	Receive messages in the channels of teams where it is installed, so it can follow a thread after you @mention it. OttoBot ignores messages that aren't addressed to it	@mentions still work, but plain replies in a thread are never seen
Bot scopes team, personal, groupChat	Part of the app package	Be added to a team, to a 1:1 chat, or to a group chat. See Verify it works for which of these it answers in	—
App permissions identity, messageTeamMembers	Part of the app package	Know who sent a message, and reply to team members	—
User.ReadBasic.All (Microsoft Graph, application) — recommended, not required	Admin-consent screen, if listed	Read a user's basic profile, including email, across your directory, to recognize who is asking	OttoBot still answers. It loses email-based personalization and can't link a Teams user to their HG Insights account. Nothing else changes

OttoBot does not ask for file access, and it can't post into teams where it isn't installed.

4. Verify it works

In a channel of a team where OttoBot is installed, @mention OttoBot with a question, for example:

@OttoBot What CRM does Acme Corporation use?

OttoBot replies in the same thread with an answer drawn from HG Insights data. You can keep asking in that thread.

• Channels are where OttoBot works. Use an @mention in a channel to test.
• 1:1 chats are off by default. If you message OttoBot directly, it replies: "DMs aren't enabled for your organization. Please @-mention me in a channel instead."
• Group chats are not served. OttoBot gives the same reply there.

If there's no reply, see the first row of the next section.

If something goes wrong

What you see	Cause	What to do
OttoBot is installed, you @mention it in a channel, and nothing comes back	Admin consent was never granted, so OttoBot can't sign in to reply	Grant admin consent (step 3), then @mention it again. No reinstall is needed
Still silent after admin consent	Your organization isn't activated yet, or HG Insights hasn't linked your tenant to your organization. OttoBot drops messages it can't match to an organization without replying	Contact HG Insights with your Directory (Tenant) ID and the app name as shown in Teams
@mentions work, but plain replies in the thread are ignored	The channel-message permission wasn't granted when OttoBot was added to the team	Have a tenant administrator remove OttoBot from the team, add it again, and accept the permission prompt
Teams says "Manifest parsing error message unavailable" when you upload	The ZIP was changed: unzipped and re-zipped, renamed inside, or wrapped in a folder	Download the package again and upload it untouched
You uploaded OttoBot in the Teams admin center, but it isn't under Apps → Built for your org in Teams	An admin-center upload can take a few hours to reach users, and the Teams desktop app can show it later than Teams on the web	Check Teams on the web or search OttoBot in Apps; sign out and back in on desktop, or wait. Don't upload the same ZIP again
Upload a custom app is missing	Custom-app upload is turned off for you	Use Option A (the admin center), or ask a Teams administrator to turn on Org-wide app settings → Let users interact with custom apps in preview and Setup policies → Upload custom apps
OttoBot replies "DMs aren't enabled for your organization. Please @-mention me in a channel instead."	You messaged it in a 1:1 chat (off by default) or a group chat (not served)	@mention OttoBot in a channel of a team where it is installed
Download Teams package shows an error, or is greyed out	You aren't an owner or admin of your organization in HG Insights, or Teams isn't activated yet	Ask an owner or admin to download it, or contact HG Insights to finish activation
Two OttoBot apps appear after uploading	Your organization installed an earlier package that HG Insights sent you directly. The downloaded package is a separate app	Contact HG Insights before removing either one

Disconnecting

To stop using OttoBot in Teams:

1. Remove the app from your teams, and if you published it, delete it in the Teams admin center under Teams apps → Manage apps.
2. Optionally, delete OttoBot under Microsoft Entra admin center → Enterprise applications to withdraw the admin consent.
3. Ask HG Insights to disconnect Teams for your organization.

Next Steps

• Slack Integration: use OttoBot in Slack as well
• Supported MCP Clients: connect HG Insights to other AI tools
• MCP Tool Documentation: the full tool catalog