Skip to main content

Microsoft Teams Integration

Talk to the ChatWalaʻau agent directly from Microsoft Teams -- a 1:1 personal chat, a group chat, or a channel post -- using the Teams bot chat UI and Adaptive Cards. It is the first external chat-channel integration: the same agent you use in the web app answers in Teams, with no separate chat logic.

The feature is opt-in and off by default. Turn it on with TEAMS_ENABLED=true plus the bot credentials.

What you get​

  • Personal, group, and channel chat. In a group or channel, address the bot with an @mention; the bot's own mention is stripped before the agent reads your message.
  • Typing indicator + proactive replies. The agent can take a while (reasoning, tools); Teams shows a typing indicator while it works and then posts the answer. Long answers are split to stay within Teams' message size limit.
  • Tool approval as an Adaptive Card. When the agent wants to run an approval-gated tool, you get a card with Allow Once / Allow Session / Deny and a round counter. Teams never auto-approves. Allow Session grants that tool for the rest of the thread and resolves any other pending cards of the same tool.
  • Access control. Optionally restrict who can use the bot to specific Microsoft Entra ID users (by Object ID). The default is everyone in the bot's reach.
  • Images. Generated images are delivered into the Teams conversation.

How it works​

Microsoft Teams Cloud delivers your message to ChatWalaʻau's bot endpoint over HTTPS:

Microsoft Teams Cloud
  |
  |  POST https://<your-host>/api/teams/messages
  v
ChatWalaʻau (Bot Framework JWT verified) --> agent turn --> reply

Inbound requests are authenticated by Microsoft Bot Framework JWT (not the product API key). ChatWalaʻau runs the agent turn in the background and replies proactively, so a slow answer never times out Teams. Each Teams conversation maps to its own chat thread.

Enabling it​

Set the master switch and the bot credentials (from your Entra app / Azure Bot registration):

TEAMS_ENABLED=true
TEAMS_APP_ID=<client-id>
TEAMS_APP_PASSWORD=<client-secret>
TEAMS_TENANT_ID=<tenant-id>

Optional settings:

# Comma-separated Entra ID Object IDs allowed to use the bot. Blank = everyone.
TEAMS_ALLOWED_USERS=
# Inbound path (registered as the bot messaging endpoint, with your host).
TEAMS_MESSAGING_ENDPOINT_PATH=/api/teams/messages
# Max characters per outbound message chunk (Teams size-limit guard).
TEAMS_MAX_REPLY_CHARS=25000

The Teams SDK (microsoft-teams-apps) ships as a standard dependency, so no extra install step is needed. When TEAMS_ENABLED is off, the Teams endpoint is not mounted and the SDK is never imported -- the runtime is unchanged.

Local development needs a tunnel​

Microsoft Teams Cloud cannot reach localhost, so for local development you expose your running ChatWalaʻau through a public HTTPS tunnel. The default is Microsoft Dev Tunnels; ngrok and cloudflared also work. The bot's messaging endpoint becomes https://<tunnel-host>/api/teams/messages.

Setup guides​

Two step-by-step operator guides live in the repository:

  • Tunnel setup (assets/docs/guides/teams-tunnel-setup.md) -- expose localhost:8000 with Microsoft Dev Tunnels (default), ngrok, or cloudflared.
  • Bot registration (assets/docs/guides/teams-bot-registration.md) -- register the bot with the Microsoft Teams CLI (or the Entra / Azure portal), obtain the credentials, set the messaging endpoint, and sideload the app into Teams.

Notes and limits​

  • A group or channel is a shared thread: anyone allowed can talk to the bot there, and the access check runs per sender on every message.
  • Personalized memory is not applied per-user in a shared thread (this is intentional for privacy in group/channel conversations).
  • The integration is off on demo deployments (DEMO_MODE leaves TEAMS_ENABLED off).