Skip to content
threada Docs

Microsoft Teams setup and support

Threada for Microsoft Teams is the Teams app path for creating governed Threada WorkItems from Teams conversations and messages. The first reviewable app is intentionally narrow: it uses a Teams bot command and message-extension action to capture Teams context into Threada. It does not read broad chat history, access files or calendars, send proactive messages, or execute third-party actions directly from Teams. Separately, Threada can send governed outbound notifications to a configured Teams incoming webhook or Teams Workflows webhook from inside Threada runtime automation.

This guide supports private Microsoft reviewer testing once a review package is available and public Teams users after Microsoft approves and lists the app. Until the Teams Store app is approved, private app packages and signed relay-style intake remain custom tenant integration work and should not be treated as a public Teams Store listing.

Start Threada-side runtime setup from https://studio.threada.ai/integrations/teams/install when a reviewer or tenant admin needs to bind the Microsoft Teams runtime integration record to a pack. This setup handoff does not replace Teams Store or AppSource installation and approval.

Requirements

Before installing or testing the Teams app, make sure you have:

  • An active Threada tenant.
  • Studio or Admin access for the Threada workspace that should receive Teams WorkItems.
  • Permission to install Teams apps in the target Microsoft 365 tenant, or a Teams admin approval path.
  • For private reviewer testing, the exact Teams app package and setup notes provided through the approved Microsoft review channel.
  • A configured Teams tenant, team, group chat, or personal scope mapping in Threada for the reviewed app package.
  • A Bot Framework registration whose messaging endpoint is the Threada runtime endpoint for the mapped tenant and channel: https://api.threada.ai/api/v1/runtime/webhooks/teams/{tenant_id}/{channel_id}.

Do not use production customer Teams tenants, customer messages, raw exports, or screenshots containing private tenant data for marketplace review evidence.

Install the Teams app

After Microsoft approves the public app, install Threada from the Microsoft Teams Store or AppSource. During private review, use only the package and instructions provided in Partner Center or the approved reviewer notes.

  1. In Teams, open Apps.
  2. Search for Threada, or upload the private package if you are performing approved reviewer testing.
  3. Add the app to the intended personal, team, or group chat scope.
  4. If Teams says admin approval is required, complete the Teams admin approval flow before testing.
  5. Confirm the app is available in the expected Teams scope.

If a private package fails to upload or validate, stop and fix the Teams app package, Bot Framework registration, manifest, or Developer Portal validation issues before continuing.

Connect Teams to Threada

The Teams app must be mapped to a Threada tenant and receiving workspace before Teams users can create WorkItems.

  1. Sign in to Threada Studio with an admin or builder account.
  2. Start from https://studio.threada.ai/integrations/teams/install, or open the workspace or pack that should receive Teams-created WorkItems.
  3. Open the integration or channel setup area for Microsoft Teams.
  4. Bind the installed Teams app, tenant, and Teams scope to the Threada workspace or pack.
  5. Select the receiving queue or routing policy.
  6. Save the mapping and run the connection test if one is available.

If the reviewed build does not yet expose a self-service Studio mapping UI, follow the reviewer setup notes for the exact tenant, Teams scope, Threada workspace, and queue prepared for review. Do not infer tenant mappings from Teams display names alone.

For admin-managed setup, store the Teams channel secret in Secret Manager as JSON. The runtime owns the Microsoft Bot Framework issuer and JWKS URL; the secret only supplies tenant-specific expectations:

{
  "microsoft_app_id": "00000000-0000-0000-0000-000000000000",
  "teams_tenant_id": "00000000-0000-0000-0000-000000000000",
  "allowed_service_url_prefixes": ["https://smba.trafficmanager.net/"]
}

teams_tenant_id, allowed_service_urls, and allowed_service_url_prefixes are optional tightening fields. Do not store bot client secrets in repo files, screenshots, logs, or reviewer notes.

Create a WorkItem from Teams

The v1 app exposes two WorkItem intake paths:

  • Bot command: use the create command to create a WorkItem from a request typed in Teams.
  • Message extension action: choose Create Threada WorkItem from Teams message, compose, or command-box context.

For reviewer testing, use a short request such as:

Need vendor security review for ExampleCo before Friday.

After a successful request, Teams should show a clear success response and a safe Threada Work link when available. Open the WorkItem in Threada and confirm the source is Teams, the original request is preserved, routing is correct, and the audit timeline records the intake event.

For the current runtime app path, Bot Framework bearer tokens are validated server-side before WorkItem creation. The Activity serviceUrl must match the token claim, and the Activity channelId must be msteams.

Send a Teams notification from Threada

The microsoft_teams_post_message action sends a governed notification from a Threada WorkItem or automation to a Microsoft Teams incoming webhook or Teams Workflows webhook URL. This is an outbound Threada runtime action; it is not a Teams user command, proactive bot message, Graph chat write, or direct third-party action executed from Teams.

To configure it:

  1. Create a Teams incoming webhook or a Teams Workflows webhook for the channel or chat that should receive notifications.

  2. Store the webhook URL as the Microsoft Teams integration endpoint_url in Threada. The runtime accepts Teams webhook hosts such as *.webhook.office.com and Teams Workflows hosts such as *.logic.azure.com.

  3. If the webhook flow requires additional authentication, store the optional integration secret in Secret Manager as JSON:

    {
  "headers": {
    "X-Workflow-Key": "<shared-secret>"
  },
  "token": "<optional-bearer-token>"
}

  4. Use an action payload with title, text, optional summary, and optional facts values. The runtime sends a Teams card payload, enforces HTTPS and Teams webhook host validation, and rejects payloads larger than 28 KB before making the provider request. Because Teams webhooks do not return a stable message id, the runtime appends an Action reference card fact and persists the same microsoft_teams:<action-id> value as the action external reference.

Example action payload:

{
  "type": "microsoft_teams_post_message",
  "title": "Refund request",
  "text": "Customer needs help with order #1001.",
  "summary": "Refund request",
  "facts": {
    "Requester": "nick@example.com",
    "Queue": "support"
  }
}

Setup-required responses

If Teams is installed but not connected to a Threada tenant or workspace, the app should show a setup-required response instead of silently dropping the request.

Common setup issues:

  • The Teams app was installed in a tenant or scope that is not mapped in Threada.
  • The mapped Threada workspace or pack was disabled.
  • The receiving queue or routing policy is missing.
  • The app package uses placeholder Microsoft app or bot IDs.
  • Bot Framework metadata does not match the app manifest.
  • The production endpoint is unavailable or not reachable over HTTPS.

For review builds, include the Teams tenant, scope, command time, and sanitized error text in support requests. Do not send bot secrets, access tokens, cookies, raw Teams exports, or private message content.

Disconnect or uninstall

To stop Teams-created WorkItems:

  1. In Threada Studio, disable or remove the Teams mapping for the workspace, pack, team, group chat, or personal scope.
  2. In Teams, remove the Threada app from the relevant scope if no longer needed.
  3. Run a test command and confirm Teams returns setup-required feedback rather than creating a new WorkItem.

Disconnecting the app stops future intake. Existing WorkItems, messages, evidence, approvals, and audit events remain available in Threada according to the tenant retention policy.

Data handling

For v1, Threada receives only the data needed to create and audit a WorkItem from the Teams command or message-extension action, including Microsoft tenant and conversation identifiers, user context supplied by Teams, the selected or entered request text, and request metadata needed for routing and support.

Threada uses this data to create and audit WorkItems in the configured tenant. Threada does not use Teams payloads to train large language models. The v1 app does not request broad Graph permissions, read Teams files, read calendars, read chat history, or export Teams tenant data.

For privacy or deletion requests, contact privacy@threada.ai. For support requests, contact support@threada.ai. To report a security issue, contact security@threada.ai.

Support requests for the Teams app receive a response within 2 business days.