Microsoft Teams (teams)

Category: io | Form: | Symbol: Te

Connect flows to Microsoft Teams for receiving and sending messages, mentions, and Adaptive Cards

Unified Microsoft Teams connector — receives activities (messages, mentions, reactions, conversation updates) from the Bot Framework messaging endpoint and sends replies, proactive messages, and Adaptive Cards back to channels, group chats, and 1:1 personal scope. Configure spec.app_id (Microsoft App ID, public GUID), spec.client_secret_ref (Bot Framework client secret — stored encrypted), and spec.tenant_id (Microsoft Entra tenant GUID). Inbound: point Azure Bot’s messaging endpoint at this element’s ops/events URL — the handler validates the Bot Framework JWT against Microsoft’s well-known JWKS and rejects activities from any tenant other than spec.tenant_id. Outbound: every reply target carries its own service_url (the Bot Framework regional endpoint); the element caches the service_url-per-conversation map so proactive messages can find the right region without a fresh activity. The generated Teams app manifest requests ChatMessageReadReceipt.Read.Chat so personal-scope read receipts can be recorded, and auto_reply mode sends typing indicators while an agent response is pending. Common mistake: missing spec.client_secret_ref — all outbound operations 401.

Guide

Teams is a channel adapter. For agent chat, configure the Teams element as an IO binding to a conversational element such as triton. For workflow-only events, point it at an automation and use reply_mode=dispatch_only.

Agent Chat Setup

1. Create a secret variable for the Bot Framework client secret:

   {
     "element_type": "variable",
     "slug": "dango-client-secret",
     "name": "Dango Client Secret",
     "spec": {
       "type": "secret",
       "value_type": "secret",
       "sensitive": true,
       "scope": "environment",
       "required": true
     }
   }
   

   Then set the value with POST /api/{circle}/dango-client-secret/ops/set_value.

2. Create the Teams connector in the same circle as the target agent:

   {
     "element_type": "teams",
     "slug": "dango",
     "name": "Dango",
     "spec": {
       "app_id": "<microsoft-app-id>",
       "client_secret_ref": "variable://dango-client-secret",
       "tenant_id": "<microsoft-entra-tenant-id>",
       "bot_handle": "Dango",
       "target_ref": "triton",
       "reply_mode": "auto_reply",
       "mention_only": false,
       "activity_types": ["message", "messageReaction", "event", "conversationUpdate", "installationUpdate"],
       "conversation_types": ["personal", "channel", "groupChat"],
       "typing_indicator_enabled": true,
       "typing_indicator_interval_seconds": 5,
       "message_format": "markdown",
       "default_service_url": "https://smba.trafficmanager.net/teams/"
     }
   }
   

3. Set the Azure Bot Service messaging endpoint to:

   https://triform.dev/api/{circle}/dango/ops/events
   

4. Publish or update the Teams app package, then install it for the user or team. Use ops/setup_status to confirm credentials, catalog status, and known conversation refs.

Interaction Modes

• reply_mode=auto_reply: inbound Teams messages are stored in a Triform conversation, routed to target_ref, and agent replies are delivered back to Teams.
• reply_mode=dispatch_only: inbound Teams activities invoke target_ref without the chat reply bridge. Use this for automations and event handling.
• ops/send, ops/update, ops/delete, and ops/proactive_dm support outbound automation messages. ops/send and ops/update accept Adaptive Card JSON in the card field.
• ops/send_typing sends a transient Teams typing indicator. In reply_mode=auto_reply, Triform sends this automatically while an agent reply is pending.
• Read receipts arrive as type=event, name=application/vnd.microsoft.readReceipt, and value.lastReadMessageId. The generated manifest includes the ChatMessageReadReceipt.Read.Chat resource-specific permission. Microsoft only delivers these for user-to-bot personal chat, and only when Teams read receipts are enabled by the tenant/user.

Product Model

Do not model a direct agent chat as an app or automation first. The Triformer is the conversational owner; Teams is one of its channels. An app or automation can create, install, or orchestrate the Teams connector, but the direct chat binding is:

Triformer target_ref <- Teams IO element <- Microsoft Bot Framework

Relationships

• Attaches to: rate-limit, auth-policy
• Uses: variable

Capabilities

• bot-framework-webhook: Receive activities via Bot Framework messaging endpoint with JWT validation
• channel-send: Send messages to Teams channels and group chats
• dm-send: Send messages in 1:1 personal scope
• threading: Reply within a Teams thread via reply_to_id
• adaptive-cards: Send rich Adaptive Card payloads with buttons, inputs, and layouts
• proactive-messaging: Start a new conversation with a user using their AAD object ID
• typing-indicators: Send transient typing indicators while an agent response is being computed
• read-receipts: Record Teams user-to-bot read receipt events when the app manifest includes ChatMessageReadReceipt.Read.Chat and Teams read receipts are enabled
• persona-header: Surface which Triform agent is speaking (card header chip or text suffix)
• tenant-isolation: Reject activities from any tenant other than spec.tenant_id

Properties

Property	Type	Default	Description
app_id	string	—	Microsoft App ID (GUID) from Azure Bot Service registration
client_secret_ref	string	—	Reference to secret element containing Bot Framework client secret (value, NOT the Secret ID)
tenant_id	string	—	Microsoft Entra tenant ID (GUID). Inbound activities from any other tenant are rejected.
bot_handle	string	—	Bot display name as shown in Teams (e.g. ‘Triform’). Cosmetic — actual display name lives in the Teams app manifest.
manifest_version	string	"1.0.0"	Version written into the generated Teams app manifest package.
web_application_resource	string	—	Optional Teams manifest webApplicationInfo.resource. Defaults to api://botid-<app_id>, which matches the standard Teams bot SSO convention.
validate_jwt	boolean	true	Validate the Bot Framework JWT on inbound activities against Microsoft’s JWKS. Disable only for local stub testing.
activity_types	array	["message","messageReaction","event"]	Teams activity types to forward downstream. event includes read receipts such as application/vnd.microsoft.readReceipt; conversationUpdate fires when the bot is added/removed from a team or channel.
conversation_types	array	["personal","channel","groupChat"]	Conversation scopes to listen on. personal = 1:1 DM, channel = team channel, groupChat = N-person ad-hoc chat.
mention_only	boolean	false	Only forward channel messages that @-mention the bot. DMs always come through regardless. Useful in noisy channels.
reply_mode	string	"auto_reply"	Inbound handling mode. auto_reply stores Teams messages in a Triform conversation, routes them to target_ref, and sends agent replies back to Teams. dispatch_only invokes target_ref directly for automation-style event handling without chat replies.
delivery_retry_limit	integer	3	Maximum Bot Framework delivery attempts for an agent reply before the Teams delivery bridge leaves it failed for operator review.
typing_indicator_enabled	boolean	true	Send transient Teams typing indicators while an auto_reply agent response is pending.
typing_indicator_interval_seconds	integer	5	Seconds between typing indicator refreshes while an agent reply is pending. Teams clients expire typing indicators quickly, so keep this short.
default_conversation_id	string	—	Default conversation ID for outbound sends when input.conversation_id is omitted. Conversation IDs are opaque strings from Bot Framework — copy from a prior inbound activity or use ops/conversations.
default_service_url	string	—	Default Bot Framework regional service URL for proactive messages (e.g. https://smba.trafficmanager.net/teams/). Auto-populated from the first received activity; override only for static-conversation deployments.
message_format	string	"markdown"	Default outbound message format. Adaptive Card requires the input.card field.
target_ref	string	—	Slug or path of the element that handles inbound Teams activities. In auto_reply mode this should be a conversational agent; in dispatch_only mode it may be an automation or other invokable element.
persona_header_style	string	"card_header"	How to surface which Triform agent is speaking. card_header renders a small chip at the top of the Adaptive Card. suffix appends ‘— ’ to plain messages. Set to ‘none’ to suppress.

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

catalog_publish

Post /ops/catalog_publish | Auth: Write

Publish or update this Teams app in the tenant org app catalog

Uploads the generated manifest zip to Microsoft Graph. Microsoft requires delegated admin Graph access for catalog publish in many tenants; pass graph_access_token/delegated_access_token when application permissions are rejected.

catalog_status

Post /ops/catalog_status | Auth: Read

Check whether this Teams app exists in the tenant org app catalog

Uses Microsoft Graph appCatalogs/teamsApps. Provide graph_access_token for delegated admin Graph access, or grant the app Microsoft Graph application permissions and let Triform use client credentials.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

conversations

Get /ops/conversations | Auth: Read

List conversations the bot is currently a member of

Returns the conversation cache the events handler has built up — Bot Framework does not expose a “list my installed conversations” API, so this reflects everywhere the bot has received an activity from since last cache eviction. For a complete inventory, the org admin must install the bot via app setup policy and inspect via the Teams Admin Center.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Post /ops/delete | Auth: Write

Delete a previously-sent activity

deliver_pending

Post /ops/deliver_pending | Auth: Write

Retry pending Teams deliveries for agent replies in a Teams-backed Triform conversation

Scans agent messages linked to a Teams-sourced user message and sends any reply whose metadata.teams_delivery is absent, failed, or stale. Use this for operator retry after transient Bot Framework failures; the normal auto_reply path starts the same delivery bridge automatically.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

events

Post /ops/events | Auth: None

Bot Framework webhook receiver — validates JWT, normalises messages/read receipts, emits teams.activity.received

This is the URL you paste into the Azure Bot Service “Messaging endpoint” field: https://{circle}.triform.dev/api/{circle}/{slug}/ops/events. The handler validates the Bot Framework JWT (signature + iss + aud + exp), enforces spec.tenant_id, records application/vnd.microsoft.readReceipt events when the Teams manifest has ChatMessageReadReceipt.Read.Chat, then emits teams.activity.received. The activity’s service_url is cached against conversation.id so later proactive_dm / send calls can find the right region. Returns 200 with an empty body for normal activities; returns the verification token verbatim for emulator/install handshakes.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

install_team

Post /ops/install_team | Auth: Write

Install the Teams app into one team

install_user

Post /ops/install_user | Auth: Write

Install the Teams app for one user

Calls Microsoft Graph users/{id}/teamwork/installedApps with teamsApp@odata.bind. user_id may be an AAD object ID or UPN. If teams_app_id is omitted, Triform discovers it from the org catalog.

install_users

Post /ops/install_users | Auth: Write

Install the Teams app for up to 50 users

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

manifest

Post /ops/manifest | Auth: Read

Generate the Teams app manifest package for this connector

Returns manifest JSON plus a base64 application/zip package containing manifest.json, color.png, and outline.png. endpoint_url defaults to the connector’s public ops/events URL when TRIFORM_PUBLIC_HOST is configured.

proactive_dm

Post /ops/proactive_dm | Auth: Write

Start a new 1:1 personal-scope conversation with a user, addressed by their Azure AD object ID

POSTs to /v3/conversations to create-or-fetch a personal-scope conversation with members=[user-AAD-ID], then immediately sends the first activity. Requires the bot to have been installed for that user via tenant app catalog OR app setup policy. Without prior install, Bot Framework returns 403 with Bot is not part of the conversation.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

receive

Post /ops/receive | Auth: None

Receive incoming external traffic

Entry point for external traffic reaching this IO element. Declared auth: none to bypass platform auth — element-level auth is enforced by IoReceiveExecutor before dispatching into the flow graph. The flow/app that wires this element as an entry point determines what happens next.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

send

Post /ops/send | Auth: Write

Send a message to a Teams conversation (channel, group chat, or DM)

Posts an activity to Bot Framework’s {service_url}/v3/conversations/{conversation_id}/activities endpoint. conversation_id is opaque — copy it from a prior inbound activity’s conversation.id, or use ops/conversations to list installed targets. Supports plain text (text_format=plain), Teams markdown (text_format=markdown), and Adaptive Cards (set card, omit text). To reply in a thread, set reply_to_id to the parent activity’s id. Persona label is rendered according to spec.persona_header_style.

send_typing

Post /ops/send_typing | Auth: Write

Send a transient Teams typing indicator to a conversation

Posts a Bot Framework Activity with type=typing to {service_url}/v3/conversations/{conversation_id}/activities. This is not a durable message and Teams clients may expire it within seconds. In reply_mode=auto_reply, Triform sends this automatically while an agent reply is pending when spec.typing_indicator_enabled is true.

setup_status

Post /ops/setup_status | Auth: Read

Summarize Teams credential, manifest, catalog, and conversation readiness

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

test_connection

Post /ops/test_connection | Auth: Read

Verify the bot can mint a Bot Framework access token with the configured credentials

Calls the AAD token endpoint with spec.app_id + spec.client_secret_ref and grant_type=client_credentials, scope=https://api.botframework.com/.default. Returns connected: true on a 200 with a token. Use this to validate credentials before installing the bot in a channel.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Post /ops/update | Auth: Write

Update a previously-sent activity (edit message text or replace its Adaptive Card)

PUT to {service_url}/v3/conversations/{conversation_id}/activities/{activity_id}. Teams allows editing the bot’s own activities within 24 hours; older edits return TEAMS_SEND_FAILED. Useful for “thinking…” → final-answer flows.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
TEAMS_AUTH_FAILED	auth	no	Bot Framework returned 401/403 — client secret invalid, expired, or app not consented
TEAMS_JWT_VERIFICATION_FAILED	auth	no	Inbound activity JWT failed signature, issuer, or audience verification against Microsoft JWKS
TEAMS_TENANT_MISMATCH	auth	no	Inbound activity originated from a tenant other than spec.tenant_id
TEAMS_SEND_FAILED	internal	yes	Outbound POST to Bot Framework service URL failed
TEAMS_CONVERSATION_NOT_FOUND	validation	no	Target conversation_id no longer exists or the bot was removed from it
TEAMS_RATE_LIMITED	internal	yes	Bot Framework / Graph API rate limit exceeded
TEAMS_CARD_INVALID	validation	no	Adaptive Card payload failed schema validation
TEAMS_SERVICE_URL_MISSING	validation	no	No service_url on the request, no cached value for the conversation, and no spec.default_service_url