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 requires approval, the bot posts an Adaptive Card 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

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 needs to map Teams users to ZenSearch accounts. Two methods:

Automatic (email match): If a Teams user's Azure AD email matches a ZenSearch user's email, they're linked automatically on first message.

Manual linking: Use the identity links API to explicitly map users:

curl -X POST https://your-domain/api/v1/identity-links \
  -H "Authorization: Bearer <token>" \
  -d '{
    "platform": "teams",
    "external_user_id": "<azure-ad-object-id>",
    "external_team_id": "<tenant-id>",
    "user_id": "<zensearch-user-uuid>",
    "team_id": "<zensearch-team-uuid>"
  }'
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