Skip to main content

# Microsoft Teams

Microsoft Teams integration lets users create CoderFlow tasks from Teams by mentioning the CoderFlow bot in a channel or group chat, or by sending the bot a personal chat message. Task results are posted back to the Teams conversation where the task started.

Teams configuration is global. It applies to all environments and all users on the server.

## What Teams Can Do​

When Teams is configured:

- Channel mentions - Mention the CoderFlow bot in a Teams channel or thread with task instructions.
- Personal chats - Send the bot a direct Teams message to create a task.
- Thread follow-ups - Replies in a mapped Teams conversation thread can follow up on the existing CoderFlow task after it finishes.
- Account linking - Users link their Teams identity to their CoderFlow account once, after which Teams-created tasks run under their CoderFlow permissions.
- Completion replies - Completed, failed, and interrupted task status is posted back to Teams.

## Prerequisites​

- A Microsoft tenant where you can create or upload a Teams app.
- A Microsoft Bot or app registration with a client secret.
- A public HTTPS URL that Microsoft Teams can reach for the bot messaging endpoint.
- The same public HTTPS base URL for CoderFlow task links and account-link callbacks.
- CoderFlow administrator access.

The Teams bot messaging endpoint is:

    https://<your-coderflow-server>/api/teams/messages

## Configure CoderFlow​

1. Go to Settings -> Microsoft Teams Integration.
2. Enter the Microsoft App ID from the Azure Bot or app registration.
3. Enter the Client Secret value.
4. Choose the app type:
   - `MultiTenant` for a normal multi-tenant bot app.
   - `SingleTenant` for a tenant-restricted app registration.
5. If using `SingleTenant`, enter the tenant ID.
6. Set Task Link Base URL to the public HTTPS base URL for this CoderFlow server. This is required when Teams is enabled so account-link callbacks and task links work from Teams.
7. Optionally choose a Default Environment.
8. Save settings.

Use Validate Configuration to confirm the saved values can initialize the Bot Framework adapter. The full end-to-end test is to message the bot from Teams.

## Create the Teams App​

The settings panel generates a Teams manifest preview. Copy it into a Teams app package with the required icon files:

- `color.png`
- `outline.png`

Upload the app in Teams or through the Teams admin center.

The generated manifest enables bot scopes for personal chats, team/channel use, and group chats.

## Account Linking​

Before a user can create CoderFlow tasks from Teams, their Teams identity must be linked to their CoderFlow user.

1. In Teams, send `link` to the CoderFlow bot.
2. Open the returned link while signed in to CoderFlow.
3. The page confirms that the Teams account is linked.

If an unlinked user tries to create a task, the bot asks them to link first. No task is created.

Users can unlink Teams identities from their CoderFlow profile.

## Choosing an Environment​

When a Teams message creates a new task, CoderFlow resolves the environment in this order:

1. Explicit message prefix - `env:<environment-name>` in the Teams message.
2. Channel mapping - A configured Teams channel/conversation mapping.
3. Single permitted environment - If the user can create tasks in only one environment.
4. Default environment - The default selected in Settings.

If multiple environments remain and no default is set, the bot asks the user to specify `env:<name>`.

## Channel Mappings​

Channel mappings let admins pre-assign a Teams channel or conversation to a CoderFlow environment. Messages in that Teams channel use the mapped environment unless the user explicitly includes `env:<name>`.

Mappings accept:

- Team ID, optional
- Channel or conversation ID
- Environment

## Security Notes​

- Teams inbound requests are handled through the Microsoft Bot Framework adapter, which verifies Bot Framework authentication.
- CoderFlow stores the Teams client secret in `teams.json` inside the server data directory with owner read/write permissions.
- Teams-created tasks still use the linked CoderFlow user's permissions.
- The bot stores conversation references in task metadata so completion messages can be posted after the task finishes or after a server restart.

## Troubleshooting​

### The Bot Does Not Respond​

- Confirm the Azure Bot messaging endpoint is exactly `https://<server>/api/teams/messages`.
- Confirm the endpoint is reachable from the public internet over HTTPS.
- Confirm the App ID and client secret in CoderFlow match the bot registration.
- Check server logs for Teams turn errors.

### "Link Your Microsoft Teams User..."​

The Teams user is not linked to a CoderFlow user. Send `link` to the bot and open the returned URL while signed in to CoderFlow.

If the bot cannot generate a link, confirm Task Link Base URL is set in Settings -> Microsoft Teams Integration.

### Multiple Environments Are Available​

Add `env:<environment-name>` to the message, configure a Teams channel mapping, or set a default environment in Settings.