Microsoft Teams

Overview

Greentic has two Teams messaging packs:

Pack	Use this when
messaging-teams	You want the current Teams app setup wizard, Bot Framework-compatible ingress, Adaptive Card invokes, and Teams app installation links.
messaging-teams-graph	You want Graph-based channel sends and Graph subscription experiments.

The default Teams setup path is messaging-teams. It integrates your digital worker with Microsoft Teams through a Teams app and Bot Framework-compatible activity ingress. It supports:

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

Prerequisites

• Microsoft 365 tenant
• Permission to run Microsoft device-code login for Graph setup access
• Permission to create or update the Microsoft Entra application used by the Teams bot
• Permission to register or update the Bot Framework/Microsoft Teams bot endpoint
• Permission to publish and install the Teams app in your tenant app catalog

Setup

The messaging-teams pack ships a provider-owned setup wizard as a web component plus a backend contract. A generic setup host discovers this metadata from the pack:

• greentic.setup.web-component.v1 for the <greentic-teams-setup-v4> UI
• greentic.setup.backend-contract.v1 for setup routes and executor steps
• greentic.setup.actions.v1 for the final Add to Teams action

Setup is intentionally step-based. The wizard advances one managed action at a time, shows Microsoft device-code instructions when needed, and blocks install/open-chat actions until the public runtime endpoint has been registered.

1. Configure the setup answers

   Most fields can be collected by the web setup UI. In answers files, provide the public URL and optional naming/tenant hints:

   answers.json

   {
     "setup_answers": {
       "messaging-teams": {
         "public_base_url": "https://your-domain.com",
         "bot_display_name": "Greentic Digital Worker",
         "azure_auth_tenant": "organizations"
       }
     }
   }

   The setup contract has defaults for the Microsoft Graph Command Line Tools public client used by device-code login. Admins can override client ids when required by tenant policy.

2. Run setup and open the wizard

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

   In UI mode, setup mounts the Teams setup component from the pack. The component calls the provider setup routes declared by the backend contract.

3. Authorize Microsoft Graph setup access

   The wizard starts Microsoft device-code OAuth. Copy the code, open the verification URL, sign in with the admin account, and approve the requested Graph scopes.

   Greentic stores OAuth state server side. Browser-submitted OAuth tokens and device codes are ignored; only the setup-owned /oauth/{kind}/start and /oauth/{kind}/complete routes mutate the login state.

4. Create or reuse the bot app identity

   Setup creates or updates the Microsoft Entra application used by the Teams bot and generates the client secret stored by setup. This produces the bot app id and password used by the runtime.

5. Authorize Teams bot channel registration

   A second device-code login grants Azure management access for registering the Greentic Bot Framework endpoint with the Microsoft Teams bot channel registry.

6. Register the active Greentic endpoint

   Setup registers or updates the Bot Framework-compatible messaging endpoint using the current public_base_url:

   https://your-domain.com/v1/messaging/ingress/messaging-teams/{tenant}/{team}

   If your tunnel or public URL changes, re-run setup so the registered endpoint points at the active runtime URL.

7. Publish and install the Teams app

   Setup builds the Teams app package from the pack template, publishes it to the tenant app catalog, and can install it for the setup user. When the app is published, the pack exposes the generic Add to Teams link for manual installation fallback.

8. Start or restart the runtime

   gtc start ./my-bundle

   Keep the runtime and public tunnel alive while completing setup. Final setup status waits until greentic-start receives the first Teams Bot Framework activity and persists that proof.

9. Open Teams and send the first message

   Use the Add to Teams link, install the app, open the bot chat, and send a message. That first activity confirms that the app, endpoint, tenant/team binding, and runtime ingress are connected.

Configuration Options

Option	Required	Description
public_base_url	Yes	Public Greentic runtime URL used for the Bot Framework messaging endpoint
bot_display_name	No	Display name used for the Entra app and Teams app package
azure_auth_tenant	No	Authority tenant for Microsoft device-code login. Defaults to organizations
graph_setup_client_id	No	Override for the public client used for Graph setup login
azure_setup_client_id	No	Override for the public client used for Azure management login
azure_subscription_id	Conditional	Azure subscription used when setup must register/update Bot Framework channel resources
azure_resource_group	Conditional	Azure resource group used for Bot Framework channel resources
azure_resource_group_location	Conditional	Azure resource group location
azure_location	Conditional	Azure bot resource location
azure_bot_name	No	Azure bot resource name when setup creates or updates the resource
bot_app_id	Generated	Microsoft Entra application id used by the Teams bot
bot_app_password	Generated secret	Client secret generated and stored by setup
teams_app_version	No	Teams app manifest version override

Note

The setup wizard owns OAuth/device-code state and generated secrets. Regenerate answers with gtc setup --dry-run --emit-answers answers.json ./my-bundle instead of hand-writing hidden or generated fields.

Caution

Manual Teams app installation is not the final setup condition. Setup is complete only after the runtime receives a Teams Bot Framework activity for the configured tenant/team.

Add to Teams Action

The Teams pack declares a generic setup action:

Field	Value
Label	Add to Teams
Kind	deep_link
URL template	{add_to_teams_url}
Required setup output	add_to_teams_url

Setup hosts can render this as a button, show the URL, and provide an HTML snippet after setup returns setup_status.ok: true. The setup wizard may show the link earlier as a manual fallback after app publishing, but generic final-screen rendering should still respect the pack action metadata.

Network Access

The current messaging-teams setup path uses a Bot Framework-compatible Teams app endpoint for incoming Teams activity. 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 Bot Framework to Greentic	Teams activity callbacks to /v1/messaging/ingress/messaging-teams/{tenant}/{team}
Outgoing	HTTPS 443 from setup/runtime to login.microsoftonline.com	Device-code OAuth and token refresh
Outgoing	HTTPS 443 from setup/runtime to graph.microsoft.com	App registration, app catalog publishing, Teams app install, and Graph-backed setup calls
Outgoing	HTTPS 443 from setup to Azure management endpoints	Bot Framework/Microsoft Teams channel registration when required by the setup contract
Outgoing	HTTPS 443 from runtime to Bot Framework service URLs	Replies and proactive sends through the service URL from incoming Teams activities
Incoming, messaging-teams-graph	HTTPS 443 from Microsoft Graph to Greentic	Graph change notifications and lifecycle notifications for Teams message subscriptions

The registered Bot Framework messaging endpoint must point at the active public runtime URL. If gtc start creates a new Cloudflare Tunnel or ngrok URL, re-run setup so the endpoint registration is reconciled before using Add to Teams or testing the bot.

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

flows/on_card_action.ygtc

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

greentic.demo.yaml

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}}"

Note

Store the conversation reference when users first interact with your bot to enable proactive messaging later.

Troubleshooting

Bot Not Responding

1. Check the public URL in setup state and confirm it matches the current tunnel/runtime URL
2. Re-run setup so Bot Framework endpoint registration is reconciled
3. Verify the Teams app is installed with the Add to Teams link
4. Send the first message to the bot so setup can observe the first Bot Framework POST
5. Review runtime logs with gtc start ./my-bundle --verbose

”Unauthorized” Error

• Verify the generated bot_app_id and stored bot secret
• Check the tenant used by Microsoft device-code setup
• Re-run the setup wizard if admin consent or endpoint registration was incomplete

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

Caution

Always validate incoming Bot Framework authentication tokens to verify requests are from Microsoft.

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