> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotbot.ch/llms.txt
> Use this file to discover all available pages before exploring further.
# Route AI questions to your team via Teams
> Configure Microsoft Teams notifications so dotbot can route needs-input tasks to stakeholders and resume automatically once an answer arrives.
When dotbot cannot proceed with a task without human input, for example a missing requirement or an ambiguous design decision, it marks that task as `needs-input` and routes the question to the appropriate stakeholder. Rather than blocking the entire queue, dotbot sends the question out-of-band via Microsoft Teams, email, or Jira, waits for a reply, and then resumes the task automatically once an answer arrives. This keeps pipelines moving without requiring the team to monitor the dashboard in real time.
This page covers the client side: the `mothership` settings block and how dotbot routes a question to Teams. The server that delivers questions and collects answers is documented separately in [Question delivery service](/guides/question-delivery-service).
## Why human-in-the-loop matters
AI models can resolve most questions by reading the codebase, product documents, and task context. But some decisions require human judgment — a stakeholder who knows the business constraint, the architect who owns the design, or the product owner who decides between competing priorities. Without a structured way to ask those questions, the AI either guesses (introducing risk) or halts the pipeline entirely.
The `needs-input` mechanism gives the AI a safe escape hatch: pause the task, ask the right person, and continue when the answer arrives — without blocking any other tasks that do not depend on this one.
## How the flow works
The AI determines it cannot proceed without more information and calls the `task_set_status` MCP tool to move the task to `needs-input`. dotbot records the question on the task as a `pending_question` and pauses it, removing it from the active execution queue.
dotbot's notification client reads the `mothership` settings block and sends the question to the configured channel (`teams`, `email`, or `jira`) along with the available choices.
The stakeholder replies directly in Teams via an Adaptive Card, by email, or via a Jira comment. The question delivery service stores the answer in Azure Blob Storage.
dotbot polls the server on the configured `poll_interval_seconds` interval. When an answer arrives, it attaches the answer to the paused task and promotes it back to the active queue.
## Configuring Microsoft Teams integration
Add the `mothership` block to your `settings.default.json` and set `channel` to `teams`:
```json settings.default.json theme={null}
{
"mothership": {
"enabled": false,
"server_url": "",
"api_key": "",
"channel": "teams",
"recipients": [],
"project_name": "",
"project_description": "",
"poll_interval_seconds": 30,
"sync_tasks": true,
"sync_questions": true
}
}
```
| Field | Type | Description |
| ----------------------- | ------- | --------------------------------------------------------------------------- |
| `enabled` | boolean | Set to `true` to activate the mothership integration |
| `server_url` | string | Base URL of the deployed Teams bot App Service |
| `api_key` | string | API key used to authenticate requests to the bot server |
| `channel` | string | Delivery channel: `teams`, `email`, or `jira` |
| `recipients` | array | List of Teams user object IDs, email addresses, or Jira account IDs |
| `project_name` | string | Displayed in the question card so stakeholders know which project is asking |
| `project_description` | string | Additional context shown in the notification |
| `poll_interval_seconds` | integer | How often dotbot checks for answers (default: `30`) |
| `sync_tasks` | boolean | Whether to sync task state to the mothership server |
| `sync_questions` | boolean | Whether to push questions and retrieve answers via the server |
## Setting up the server\_url and api\_key
To use Teams (or any other notification channel), you need a deployed mothership server. Once your server is running, set its URL and API key in `settings.default.json`:
```json settings.default.json theme={null}
{
"mothership": {
"enabled": true,
"server_url": "https://your-dotbot-server.example.com",
"api_key": "your-api-key-here",
"channel": "teams"
}
}
```
Store the `api_key` in your local `.bot/.control/settings.json` rather than in the version-controlled `settings.default.json` to avoid accidentally committing credentials to your repository.
## What stakeholders see
When a question is routed to Teams, the recipient receives an Adaptive Card that includes the project name, the question text, and a set of choices to select from. Clicking a choice submits the answer directly — no separate login or dashboard access is required.
The architecture is:
```
[dotbot runtime] ──POST──▶ [App Service /api/notify]
│
Sends Adaptive Card
│
[Teams user] ◀──Card────────────────┘
│ clicks choice
▼
[Teams] ──▶ [Bot Service] ──▶ [App Service /api/messages]
│
Stores answer JSON
Sends confirmation card
```
## Question types
The question delivery service supports five question types. A `needs-input` task picks the type that fits the decision it needs:
| Type | What the stakeholder does |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `singleChoice` | Picks one option from a list. |
| `multiChoice` | Picks one or more options from a list. |
| `approval` | Approves or rejects a proposal. This type also carries attached documents for review, absorbing what was previously a separate document review type. |
| `freeText` | Writes a free-form answer. |
| `priorityRanking` | Orders a set of items by priority. |
When a stakeholder responds, the service stores the answer in Azure Blob Storage. dotbot reads it during the next poll cycle and attaches it to the paused task before resuming. For the answer record format and the server side of this flow, see [Question delivery service](/guides/question-delivery-service).
## Other routing options
Set `channel` to `email` and populate `recipients` with email addresses. dotbot sends a formatted message with answer choices and resumes when a reply is received.
Set `channel` to `jira` and populate `recipients` with Jira account IDs. dotbot creates a comment on the relevant Jira issue and resumes when a reply comment is detected.
Set `poll_interval_seconds` to `60` or higher in long-running pipelines to reduce noise in the server logs. For time-sensitive interactive workflows, `15`–`30` seconds gives a responsive feel without excessive polling.