Microsoft Teams Bot

Bring Vaquill into Microsoft Teams via the Bot Framework. The bot replies in personal chats, channels (with @mention), and threads with Adaptive Cards that include cited statute sections and source links. Source code at github.com/Vaquill-AI/integrations/ms-teams-bot.

Features

Statute search via the Vaquill API (US Code, CFR, all 50 state codes)
Multi-turn conversation with client-side chat history
Adaptive Cards with source citations (code, title, section, source link)
Per-user, per-channel, and per-tenant rate limits (Redis or in-memory)
Tenant and channel allowlists, user blocklists
Slash commands: /help, /clear, /status
Thread support with @mention in channels

Prerequisites

Requirement	Notes
Azure account	Azure Bot resource uses the free F0 tier
Microsoft Teams admin or app sideloading permission	Required to upload the custom app package
Vaquill API key from app.vaquill.ai/settings	Starts with `vq_key_`. See Authentication.
Python 3.10+ (or Docker)	3.12 recommended
ngrok (local dev only)	Tunnels your localhost to a public HTTPS URL
Redis (optional)	For distributed rate limiting

You need three credentials before you can run the bot: TEAMS_APP_ID, TEAMS_APP_PASSWORD, and VAQUILL_API_KEY.

Platform setup

Create an Azure App Registration

In the Azure Portal, search for Microsoft Entra ID > App registrations > + New registration. Use:

Name: vaquill-teams-bot
Supported account types: Single tenant (recommended) or Multi-tenant
Redirect URI: leave blank

Click Register. Copy the Application (client) ID - this is your TEAMS_APP_ID.

Create a client secret

In the registration, go to Certificates & secrets > Client secrets > + New client secret. Description: Teams Bot Secret, Expires: 24 months. Click Add and immediately copy the Value column - this is your TEAMS_APP_PASSWORD.

Copy the Value, not the Secret ID. The Value is shown only once.

Create the Azure Bot resource

In the Azure Portal, Create a resource > Azure Bot. Fill in:

Bot handle: vaquill-teams-bot
Pricing tier: F0 (Free)
Microsoft App ID: paste the ID from Step 1

Click Review + Create > Create.

Enable the Teams channel

Open your Azure Bot resource, go to Channels, click the Microsoft Teams icon, and click Apply.

Generate your Vaquill API key

Quickstart

Clone and install

git clone https://github.com/Vaquill-AI/integrations.git
cd integrations/ms-teams-bot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configure environment

cp .env.example .env

Set the minimum required values:

TEAMS_APP_ID=12345678-1234-1234-1234-123456789abc
TEAMS_APP_PASSWORD=abc123~XYZ456.789def-GHI012_JKL345
TEAMS_APP_TYPE=MultiTenant
VAQUILL_API_KEY=vq_key_your_key_here
VAQUILL_COUNTRY_CODE=US

Run the bot

python3 app.py

Expected:

INFO - Vaquill client initialized
INFO - Rate limiter initialized
INFO - Bot initialization complete
 * Running on http://0.0.0.0:3978

Health check: curl http://localhost:3978/health.

Expose with ngrok (local dev only)

ngrok http 3978

Copy the HTTPS URL, append /api/messages, and paste into Azure Portal > your Bot > Configuration > Messaging endpoint. Click Apply.

Free ngrok URLs change on restart. You will need to update the messaging endpoint each time.

Install in Teams

Create a deployment/ folder with manifest.json (set botId to TEAMS_APP_ID), color.png (192x192), and outline.png (32x32). Zip them:

cd deployment
zip -r vaquill-bot.zip manifest.json color.png outline.png

In Teams: Apps > Manage your apps > Upload an app > Upload a custom app. Select the ZIP.Test by DMing the bot or mentioning it in a channel:

@Vaquill Bot What is qualified immunity under 42 USC 1983?

Configuration

Top env vars. See the repo .env.example for the full set.

Variable	Required	Default	Description
`TEAMS_APP_ID`	Yes	-	Application (client) ID from Azure App Registration
`TEAMS_APP_PASSWORD`	Yes	-	Client secret Value from the registration
`TEAMS_APP_TYPE`	No	`MultiTenant`	`SingleTenant` or `MultiTenant`
`VAQUILL_API_KEY`	Yes	-	Vaquill API key (`vq_key_...`)
`VAQUILL_MODE`	No	`standard`	`standard` or `deep`
`VAQUILL_COUNTRY_CODE`	No	-	Jurisdiction filter, e.g. `US`
`ALLOWED_TENANTS`	No	-	Comma-separated tenant IDs (production safety)
`RATE_LIMIT_PER_USER`	No	`20`	Per-user limit per minute
`RATE_LIMIT_PER_CHANNEL`	No	`100`	Per-channel limit per hour
`RATE_LIMIT_PER_TENANT`	No	`500`	Per-org limit per hour
`REDIS_URL`	No	-	Optional Redis URL
`PORT`	No	`3978`	HTTP server port

Commands

Command	Description
`/help`	Show available commands
`/clear`	Clear conversation history for the current chat
`/status`	Show rate-limit usage and bot status
`@Vaquill Bot <question>`	Ask in a channel (mention required)
Personal chat	Send any message - no mention needed

Deployment

Docker

docker build -t vaquill-teams-bot .
docker run -d --name teams-bot -p 3978:3978 --env-file .env vaquill-teams-bot
docker logs -f teams-bot

Azure Web App (native)

az webapp up \
  --name vaquill-teams-bot \
  --resource-group vaquill-rg \
  --runtime "PYTHON:3.12" \
  --sku B1

Set environment variables under Web App > Configuration > Application settings, then point Azure Bot Messaging endpoint at https://vaquill-teams-bot.azurewebsites.net/api/messages.

Other cloud hosts

Railway

Fork the repo, connect on railway.app, add env vars, deploy, copy the URL, update the Azure messaging endpoint.

Render

New Web Service, connect GitHub, set env vars, deploy. Use the .onrender.com URL as the messaging endpoint.

Always end the messaging endpoint with /api/messages and use HTTPS. HTTP endpoints will be rejected by the Bot Framework.

Troubleshooting

Symptom	Fix
Bot not responding in Teams	Confirm messaging endpoint ends with `/api/messages`. Confirm the app is installed in Teams. Try personal chat first to isolate channel-permission issues.
Authentication errors	Verify `TEAMS_APP_ID` matches Azure Portal > Bot > Configuration. Regenerate the client secret if expired. Restart the bot after credential changes.
Vaquill API 401	`VAQUILL_API_KEY` is invalid - generate a new one.
Vaquill API 402	Insufficient credits - top up at app.vaquill.ai/settings.
Rate-limit hits	Raise `RATE_LIMIT_PER_USER` / `RATE_LIMIT_PER_CHANNEL`, or set `REDIS_URL` for shared state.

Test the Vaquill API directly to isolate bot issues:

curl -X POST https://api.vaquill.ai/api/v1/statutes/search \
  -H "Authorization: Bearer vq_key_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "civil action for deprivation of rights", "country_code": "US"}'

Slack

Slack workspace equivalent.

Discord

Same engine, no Azure required.

Chatbots overview

Compare all six platforms.

Authentication

How Vaquill API keys work.

Overview

MCP Servers

Chatbots

Widgets

Browser

Automation

Features

Prerequisites

Platform setup

Quickstart

Configuration

Commands

Deployment

Docker

Azure Web App (native)

Other cloud hosts

Railway

Render

Troubleshooting

Slack

Discord

Chatbots overview

Authentication

​Features

​Prerequisites

​Platform setup

​Quickstart

​Configuration

​Commands

​Deployment

​Docker

​Azure Web App (native)

​Other cloud hosts

Railway

Render

​Troubleshooting

​Related

Slack

Discord

Chatbots overview

Authentication

Features

Prerequisites

Platform setup

Quickstart

Configuration

Commands

Deployment

Docker

Azure Web App (native)

Other cloud hosts

Troubleshooting

Related