Microsoft Teams

Overview

The Microsoft Teams provider integrates your digital worker with Teams channels and chats. It supports:

Channel messages
Personal chats
Group chats
Adaptive Cards
Interactive components
File attachments

Prerequisites

Microsoft 365 tenant
A public Microsoft Entra application client id that supports device-code OAuth
Permission to grant or consent to the Graph scopes used by setup
Permission to create channels in the selected Team when you want setup to create a missing desired channel

Setup

Teams setup has two supported configuration shapes:

Mode	Use this when	Main fields
Graph channel mode	You want Graph-based channel sends and subscriptions. This is the default setup mode.	`tenant_id`, `client_id`, `team_id`, `team_name`, `channel_id`, `channel_name`, `desired_channel_name`
Bot Framework mode	You have an Azure Bot and Teams app manifest for inbound Bot Framework messages.	`ms_bot_app_id`, `ms_bot_app_password`, `bot_display_name`, `messaging_endpoint`

Configure the setup hint

You can run setup with only the default public client id, or provide your own client_id. Add desired_channel_name when you want setup to find or create a specific standard channel:
answers.json
```
{
  "setup_answers": {
    "messaging-teams": {
      "client_id": "6c115a7a-f656-49c4-975a-5e831efae833",
      "desired_channel_name": "hr onboarding"
    }
  }
}
```

Start Teams setup

gtc setup --answers answers.json ./my-bundle

Complete device-code OAuth

Setup starts a Microsoft device-code flow. Copy the code, open the verification URL, sign in with the Microsoft 365 account that can access the target Team, and approve the requested Graph scopes.

Return to the terminal and continue when setup asks you to verify Microsoft Teams setup. Greentic then polls Microsoft Graph, stores the delegated tokens as secrets, and runs post-login discovery.
Select or verify the Team and channel

Setup calls Microsoft Graph to list joined teams and channels for the signed-in user. Choose the Team and channel when prompted, or let desired_channel_name guide the create-if-missing flow.

Setup persists both the identifiers and labels:
- team_id and team_name
- channel_id and channel_name
The IDs are what runtime sends and subscription setup use. The display names are for operators and setup UIs.
Check the channel in Teams

Open Microsoft Teams and go to the selected Team and channel. If setup created desired_channel_name, confirm the channel exists and that the signed-in account has access to it.

If the selected Team does not already have that channel, setup can create a standard channel and then stores the resulting channel_id and channel_name. The ID remains authoritative for runtime sends and subscriptions.
Start or restart the runtime
Terminal window
```
gtc start ./my-bundle
```
The Teams pack declares desired subscription metadata, including the Graph resource template, component config fields, notification URL template, and lifecycle notification URL template. Hosts should use this metadata instead of hard-coding Teams resource paths.
Test the target channel

Send a message in the selected Teams channel or trigger a flow that sends to Teams. If messages do not appear, re-run setup and check that the persisted team_id and channel_id still match the channel you opened in Teams.

Configuration Options

Option	Required	Description
`client_id`	Yes for Graph setup	Public Microsoft application client id used for device-code OAuth
`tenant_id`	Generated	Tenant id discovered from Microsoft Graph
`team_id`	Generated or selected	Teams team id used for channel sends and subscriptions
`team_name`	Generated or selected	Display name for the selected Team
`channel_id`	Generated or selected	Channel id used for sends and subscriptions
`channel_name`	Generated or selected	Display name for the selected channel
`desired_channel_name`	No	Default/search hint, and channel creation name when creation is supported
`chat_id`	No	Chat id for chat subscriptions where applicable
`ms_bot_app_id`	Bot Framework mode	Microsoft Bot Framework app id
`ms_bot_app_password`	Bot Framework mode	Bot Framework app password
`bot_display_name`	Bot Framework mode	Display name used in Teams app manifest workflows
`messaging_endpoint`	Bot Framework mode	Public Bot Framework messaging endpoint

Network Access

Teams Graph mode uses Microsoft Graph subscriptions for incoming channel or chat messages. Expose the Greentic runtime through HTTPS on port 443; local development can use a tunnel that forwards the public URL to the local runtime port.

Direction	Protocol and port	Purpose
Incoming	HTTPS `443` from Microsoft Graph to Greentic	Change notifications and lifecycle notifications for Teams message subscriptions
Incoming, Bot Framework mode	HTTPS `443` from Microsoft Bot Framework to Greentic	Bot Framework activity callbacks to the configured messaging endpoint
Outgoing	HTTPS `443` from Greentic to `login.microsoftonline.com`	Device-code OAuth and token refresh
Outgoing	HTTPS `443` from Greentic to `graph.microsoft.com`	Team/channel discovery, optional channel creation, message sends, and subscription reconciliation
Outgoing, Bot Framework mode	HTTPS `443` from Greentic to Bot Framework service URLs	Replies and proactive sends through the Bot Framework service URL from incoming activities

The Graph subscription notificationUrl and lifecycleNotificationUrl must both be publicly reachable over HTTPS. The provider pack declares the URL templates; hosts should not hard-code Teams paths.

Features

Text Messages

- id: reply
  type: reply
  config:
    message: "Hello! How can I help you today?"

Markdown Formatting

Teams supports a subset of Markdown:

- id: formatted
  type: reply
  config:
    message: |
      **Bold** *Italic*
      - Bullet 1
      - Bullet 2
      [Link](https://example.com)

Adaptive Cards

Teams has native Adaptive Card support through Bot Framework attachments. Use the version supported by your target Teams client and action model; Adaptive Cards 1.4 features such as Universal Actions are specific to supported bot scenarios.

- id: send_card
  type: adaptive-card
  config:
    card:
      type: AdaptiveCard
      version: "1.4"
      body:
        - type: TextBlock
          text: "Welcome!"
          size: Large
          weight: Bolder
        - type: TextBlock
          text: "How can I assist you today?"
        - type: ActionSet
          actions:
            - type: Action.Submit
              title: "Get Help"
              data:
                action: "help"
            - type: Action.Submit
              title: "Create Ticket"
              data:
                action: "ticket"

Hero Cards

- id: hero_card
  type: reply
  config:
    hero_card:
      title: "Support Bot"
      subtitle: "Your AI Assistant"
      text: "I can help with technical issues, billing questions, and more."
      images:
        - url: "https://example.com/bot-image.png"
      buttons:
        - type: messageBack
          title: "Get Started"
          text: "get started"
          displayText: "Getting started..."

Suggestions (Quick Replies)

- id: suggestions
  type: reply
  config:
    message: "What would you like to do?"
    suggested_actions:
      - title: "Check Status"
        value: "status"
      - title: "Create Ticket"
        value: "ticket"
      - title: "Contact Human"
        value: "human"

File Attachments

- id: send_file
  type: reply
  config:
    message: "Here's your report"
    attachments:
      - contentType: "application/pdf"
        contentUrl: "https://example.com/report.pdf"
        name: "report.pdf"

Handling Card Actions

name: handle_card_action
version: "1.0"

nodes:
  - id: route_action
    type: branch
    config:
      conditions:
        - expression: "data.action == 'help'"
          to: show_help
        - expression: "data.action == 'ticket'"
          to: create_ticket
      default: unknown_action

  - id: show_help
    type: reply
    config:
      message: "Here's how I can help..."

triggers:
  - type: invoke
    name: "adaptiveCard/action"
    target: route_action

Channel Configuration

Team Channel

tenants:
  demo:
    teams:
      support:
        channels:
          teams:
            provider: messaging-teams
            config:
              team_id: "19:xxx@thread.tacv2"
              channel_id: "19:yyy@thread.tacv2"

Personal Chat

For personal 1:1 chats, no channel configuration needed. The bot responds to whoever messages it.

Proactive Messaging

Send messages without user initiation:

- id: proactive
  type: reply
  config:
    message: "Reminder: Your ticket #123 needs attention"
    conversation_reference:
      conversation_id: "{{stored_conversation_id}}"
      service_url: "{{stored_service_url}}"

Troubleshooting

Bot Not Responding

Check endpoint configuration in Azure Bot Service
Verify SSL certificate is valid
Check app credentials are correct
Review activity logs in Azure

”Unauthorized” Error

Verify App ID and Password
Check tenant ID for single-tenant apps
Ensure bot is enabled in Teams channel

Card Not Rendering

Validate card JSON with Adaptive Cards Designer
Check Teams supports the card version and action type
Verify all required fields are present

Messages Delayed

Teams can batch messages; this is normal
Check your server performance
Verify no rate limiting

Security

Greentic automatically validates:

JWT signature
Issuer and audience claims
Token expiration

Next Steps

Adaptive Cards Designer - Design cards visually
Slack Provider - Add Slack integration
WebChat Provider - Embed in websites