NIVA
All integrations

Microsoft Teams Integration

How to Connect Microsoft Teams to NIVA · Integration Guide

25–35 minutesMedium7 steps

Connect NIVA to Microsoft Teams via Azure Bot Service. Your AI bot will respond to direct messages and channel mentions in Teams. NIVA uses the Bot Framework REST API with full JWT token validation for security. <strong>Each client needs their own Azure Bot registration</strong>, credentials cannot be shared across bots.

Before you begin

  • ✓
    NIVA botmaster account with a bot already created and configured
  • ✓
    Microsoft Azure account, free tier is sufficient for bot registration (no paid plan required)
  • ✓
    Microsoft Teams access, Microsoft 365 subscription OR Teams Free. For org-wide deployment (bot searchable by all employees) a Microsoft 365 Business/Enterprise plan with Teams Admin Center access is required
  • ✓
    Public HTTPS webhook URL, Azure cannot reach localhost. Use your production domain or a tunnel like ngrok (ngrok http 8000) for development
  • ✓
    Stable internet connection during setup, Azure validates the messaging endpoint in real time

Step-by-step setup

  1. 1

    Create an Azure Bot Registration

    • Go to portal.azure.com and sign in
    • Search for Azure Bot in the top search bar and click Create
    • Enter a Bot handle (e.g. my-company-bot), select your subscription and resource group
    • Under Microsoft App ID choose Create new Microsoft App ID
    • Set Type of App to Multi Tenant (required for Teams)
    • Click Review + Create → Create and wait ~1 minute for deployment
    The bot handle is just an Azure resource name, the display name shown to Teams users is set later in the Teams app manifest.
  2. 2

    Get your App ID and create a Client Secret

    • Open your new bot resource → click Configuration in the left menu
    • Copy the Microsoft App ID (a UUID like d33ab0dc-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
    • Click Manage Password link next to the App ID, this opens App Registrations
    • Go to Certificates & secrets → Client secrets → New client secret
    • Add a description (e.g. NIVA bot), set expiry to 24 months, click Add
    • Immediately copy the Value column of the new secret, it disappears after you navigate away
    Critical: copy the secret Value (looks like _xK9Q~abc...), not the Secret ID (which is a GUID). Pasting the Secret ID causes a 400 error when fetching tokens.
  3. 3

    Configure in NIVA Botmaster

    • Open your NIVA botmaster → Omnichannel → Configure on the Microsoft Teams card
    • Paste the Microsoft App ID into the App ID field
    • Paste the Client Secret Value into the Client Secret field
    • Leave Tenant ID as botframework.com for multi-tenant bots (default)
    • Click Save & Activate
    • Copy the generated Webhook URL shown after saving
    The App ID you paste here must exactly match what Azure uses in its JWT tokens. If you get 401 errors, verify the App ID by checking Azure → App Registrations → your app → Overview → Application (client) ID.
  4. 4

    Set the Messaging Endpoint in Azure

    • Back in Azure → your bot resource → Configuration
    • Paste your NIVA Webhook URL into Messaging endpoint (must start with https://)
    • Click Apply
    • Azure will immediately send a test POST to your endpoint, your server must be running and reachable
    For local development: run ngrok http 8000, use the https://xxxx.ngrok-free.app URL as the endpoint. Restart ngrok = new URL = update Azure endpoint again.
  5. 5

    Enable the Microsoft Teams Channel

    • In your bot resource → Channels (left menu)
    • Click the Microsoft Teams tile under "Available Channels"
    • Accept the terms of service → click Agree → Apply
    • Wait a few seconds · the status should change to Running
  6. 6

    Test in Azure Web Chat first

    • In your bot resource → Test in Web Chat (left menu)
    • Type a message, if your server is running you should get a reply
    • This confirms JWT auth and reply pipeline work before moving to Teams
    • If you see no reply, check server logs for [MSTeams] errors before proceeding
    Always verify in Azure Web Chat before testing in the Teams app. It isolates auth problems from Teams deployment problems.
  7. 7

    Add the Bot to Microsoft Teams

    • For personal testing (sideload): In Teams → Apps → Manage your apps → Upload an app → upload the bot's .zip app manifest
    • For org-wide deployment: Teams Admin Center → Teams apps → Manage apps → Upload → publish to your org catalog
    • After upload, search for your bot name in Teams → click Open → type a message
    • Note: bots do not appear in Teams search until they are published to the org catalog or sideloaded
    Teams Free users can sideload apps. Microsoft 365 is required to publish to the org catalog so all employees can discover the bot via search.

Troubleshooting

401 Unauthorized in webhook logs
Almost always an App ID mismatch. The App ID in NIVA must match exactly what Azure sends in the JWT aud claim. Verify: Azure Portal → App Registrations → your app → Overview → Application (client) ID. Update NIVA config if different.
400 Bad Request when fetching access token
Client Secret is wrong. You likely saved the Secret ID (a GUID) instead of the secret Value. Go to App Registrations → Certificates & secrets → create a new secret → copy the Value column.
Webhook returns 200 but no reply appears in Teams / Web Chat
Check server logs for [MSTeams] send_message HTTP 4xx. Common cause: Activity.From field missing or service_url not captured correctly. Ensure NIVA is up to date.
Bot not appearing in Teams search
Bots must be published to the org app catalog or sideloaded before they appear in search. Simply registering in Azure is not enough. Use Teams Admin Center to publish, or sideload a manifest .zip for testing.
Azure Web Chat works but Teams gives no response
Confirm Microsoft Teams channel is enabled in Azure → Channels → Teams → status Running. Also confirm the Messaging Endpoint URL in Azure Configuration is the current public URL (ngrok URLs change each restart).
ngrok URL not accepted by Azure (CSRF / SSL error)
Ensure your Django settings include CSRF_TRUSTED_ORIGINS = ['https://*.ngrok-free.app']. Azure must reach your server via HTTPS, HTTP-only URLs are rejected.
Teams says "This app encountered a problem"
Server returned an error response. Check Django logs. Ensure bot slug in Webhook URL matches your bot exactly.