Skip to main content
Moved to App Settings in v0.129.0

The tuning values on this page are configured in the in-app App Settings screen (sidebar footer, sliders icon) and stored in app_settings.jsonc -- not in .env. A value left in .env is ignored and named once in the startup log; run chatwalaau settings migrate --write to carry an existing configuration across. Feature enable-gates and secrets stay in .env. See Configuration -> Application settings.

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.
  • No approval cards. As of v0.160.0 tools run as soon as the agent calls them, in Teams as everywhere else. Anyone who can use the bot can therefore cause the agent's enabled tools to run -- restrict the bot with Access control below, and turn off tools you do not want reachable (for example CODING_ENABLED=false). An approval card posted before the upgrade does nothing when clicked.
  • 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.
  • Files the assistant creates. A file link Teams cannot open is replaced by its name and workspace path, for example report.pdf (workspace file: output/report.pdf). The file itself is not sent to Teams; open the same chat in the web app to download it (see File Explorer).

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).