Gateways
Microsoft Teams Gateway
Connect Org in a Box to Microsoft Teams via the Bot Framework.
Prerequisites
- Azure subscription with permission to create Bot Service resources
- Microsoft 365 tenant with Teams
1. Register a Bot in Azure
az bot create \
--resource-group <rg> \
--name Org in a BoxBot \
--kind registration \
--sku F0 \
--endpoint https://your-domain.com/api/messagesOr use the Azure Portal: Bot Services → Create → Azure Bot.
2. Configure Teams Channel
In the Bot resource → Channels → Microsoft Teams → Enable.
3. Get App Credentials
In the Bot resource → Configuration:
- Copy Microsoft App ID
- Create a new client secret → copy it
4. Configure Environment
MICROSOFT_APP_ID=<app-id>
MICROSOFT_APP_PASSWORD=<client-secret>
MICROSOFT_APP_TYPE=MultiTenant
MICROSOFT_APP_TENANT_ID=<tenant-id> # only for SingleTenant bots
TEAMS_PORT=39785. Expose the Webhook
The Teams gateway listens on port 3978. In production, point the bot's messaging endpoint at https://your-domain.com/api/messages (use a reverse proxy or Azure Container Apps ingress).
For local development, use a tunnel:
ngrok http 3978
# Update bot endpoint URL in Azure Portal6. Start the Gateway
docker compose --profile teams up -dUsage
- Mention the bot in a channel:
@Org in a BoxBot what's on my calendar today? - Direct Message: find the bot in Teams search, send a DM
When Azure AD SSO is enabled, users are automatically resolved from the aadObjectId in every Teams activity — no linking step required.
Troubleshooting
| Symptom | Fix |
|---|---|
| 401 Unauthorized | Verify MICROSOFT_APP_ID and MICROSOFT_APP_PASSWORD |
| Bot not appearing in Teams | Re-publish the Teams channel in Azure Portal |
| Messages not reaching bot | Check ngrok/tunnel is running and endpoint URL is updated |