Skip to main content

Teams Bot

Ask ZenSearch questions directly from Microsoft Teams. The bot responds with Adaptive Cards containing cited answers, source references, and follow-up suggestions.

info

The Teams bot is separate from the Microsoft 365 integration. The integration provides agent tools for reading/writing to M365 services. The bot lets you query ZenSearch from within Teams.

Using the Bot​

Mention in a Channel​

Mention the bot in any channel or group chat:

@ZenSearch how do I set up data connectors?

The bot replies with:

  • A cited answer as an Adaptive Card
  • Source references (up to 5) shown as facts
  • Follow-up suggestion buttons

Direct Chat​

Open a 1:1 chat with the bot — no @ mention needed:

What authentication methods are supported?

Conversations​

The bot maintains conversation context across messages in the same Teams conversation.

  • Conversation scope: Each Teams conversation maps to a ZenSearch conversation
  • Session duration: 24 hours of inactivity starts a new conversation
  • Cross-platform: Conversations can be continued in the web app

Follow-up Suggestions​

After each answer, the bot shows suggested follow-up questions as buttons. Clicking one sends a new query in the same conversation.

Agent Approvals​

When an agent action in a Teams conversation requires policy approval, the bot posts an Adaptive Card in that conversation with Approve and Deny buttons.

  • Only team Admins and Owners can approve or deny
  • The card updates to show who took action and the decision
  • Approved actions resume automatically; denied actions stop the agent

Delegated delegate_to_human approvals are routed through the delegated approval resolver and are visible from Governance. Slack DM and email delivery can notify resolved approvers when those channels are configured; Teams does not currently send proactive delegated approval DMs.

Setup (Admin)​

Prerequisites​

  • An Azure AD tenant with admin permissions
  • A ZenSearch team with data sources configured

1. Register a Bot in Azure​

  1. Go to the Azure Portal > Bot Services > Create
  2. Create a new Azure Bot resource
  3. Under Configuration, set the messaging endpoint to: 
    https://your-zensearch-domain/api/v1/surfaces/teams/activities
  4. Note the Microsoft App ID and generate a Client Secret
  5. Under Channels, add Microsoft Teams
  6. In the Teams admin center, approve the bot for your organization

2. Configure ZenSearch​

Set these environment variables on the core-api service:

VariableDescription
TEAMS_APP_IDBot Framework Application ID from Azure
TEAMS_APP_PASSWORDBot Framework Application Password (client secret)
TEAMS_BOT_ENABLEDSet to true to enable

ZenSearch maps Teams users to ZenSearch accounts by their verified identity — never an admin-asserted binding. The manual identity-links API that let an admin map an arbitrary user to an external account was removed for security: it carried no proof the admin controlled that account, which allowed impersonation.

note

Automatic verified-identity linking for Teams — matching a user's verified Azure AD identity to their ZenSearch account on first interaction — is in development and not yet available. (Slack already links this way via its verified email.)

caution

Users without a linked identity will see: "Your identity is not linked to ZenSearch. Ask your admin to link your account."

4. Install in Teams​

  1. Create a Teams app package (manifest.json) with your bot's App ID
  2. Upload to your organization's Teams app catalog
  3. Users can then add the bot to channels or start direct chats

Troubleshooting​

Bot Not Responding​

  • Verify TEAMS_BOT_ENABLED=true is set
  • Check that the messaging endpoint URL is reachable from Azure
  • Verify the App ID and password match the Azure Bot registration
  • Check core-api logs for JWT validation errors

Identity Not Linked​

  • Ensure the Teams user's Azure AD email matches their ZenSearch account email
  • Or create an explicit identity link via the API using the user's AAD Object ID

"Still processing your previous message..."​

  • The bot processes one message per conversation at a time
  • Wait for the current response to complete before sending another

Adaptive Card Not Rendering​

  • Ensure the Teams client is up to date
  • Cards use Adaptive Card schema v1.5 — older clients may not render all elements