Microsoft Teams Bot Framework Connector Guide

Microsoft Teams integrations in Tealfabric help you automate outbound bot messages, process inbound activities, and keep conversation workflows reliable across channels. This guide explains how to configure the connector, validate authentication, and run common operations so you can move from setup to production with fewer errors.

When to use this connector

Use this connector when your ProcessFlow should post operational alerts to Teams, respond to user-driven bot events, or keep external systems in sync with conversation activity. The connector is especially useful when Teams is part of your support, approvals, or incident communication flow. A clear integration contract for channels, conversation IDs, and retry behavior keeps these automations predictable at scale.

Prerequisites

Before you configure the integration in Tealfabric, register your bot app in Microsoft Entra ID and ensure the bot is available in your Teams environment. Your integration should have an application ID and client secret with the permissions required for the bot scenario you are implementing. Confirm the target tenant, bot installation scope, and channel access first so you do not troubleshoot avoidable authorization issues later.

Configuration reference

The connector stores authentication and endpoint settings in the integration configuration, not in each execution payload. Keep these values stable and rotate sensitive credentials through your secure credential process.

• app_id (required): Bot application (client) ID from Microsoft Entra ID.
• app_password (required): Bot application secret used to obtain access tokens.
• tenant_id (optional): Tenant identifier. Use common only if your deployment is intentionally multi-tenant.
• endpoint_url (optional): Override for Bot Framework service URL when required by your environment.
• timeout_seconds (optional): Request timeout for connector calls.

Send a Teams message from a workflow

A common pattern is triggering a bot message from ProcessFlow after a business event such as a deployment, ticket update, or approval status change. The following examples call the integration execution endpoint using Tealfabric API credentials and send a message to a Teams conversation.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type TeamsSendResult = {
  activity_id?: string;
  conversation_id?: string;
  status?: string;
};

async function sendTeamsMessage(
  integrationId: string,
  conversationId: string
): Promise<TeamsSendResult> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "send",
        endpoint: `v3/conversations/${conversationId}/activities`,
        method: "POST",
        data: {
          type: "message",
          text: "Deployment finished successfully.",
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as { data?: TeamsSendResult };
  if (!payload.data) throw new Error("Missing Teams response payload");
  return payload.data;
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "send",
    "endpoint": "v3/conversations/<ENTITY_ID>/activities",
    "method": "POST",
    "data": {
      "type": "message",
      "text": "Deployment finished successfully."
    }
  }'

{
  "success": true,
  "data": {
    "activity_id": "a:01HXYZEXAMPLE",
    "conversation_id": "<ENTITY_ID>",
    "status": "queued"
  }
}

Receive activities for downstream processing

Use the receive operation when you need to fetch activity data and route it into business logic, such as ticket enrichment or automated approvals. Keep your query scope narrow and process records idempotently so retried runs do not duplicate downstream actions.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type TeamsActivity = {
  id: string;
  type?: string;
  text?: string;
  from?: { id?: string; name?: string };
};

async function receiveTeamsActivities(
  integrationId: string,
  conversationId: string
): Promise<TeamsActivity[]> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "receive",
        endpoint: `v3/conversations/${conversationId}/activities`,
        query: {
          limit: 20,
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as { data?: TeamsActivity[] };
  if (!payload.data) throw new Error("Missing activity payload");
  return payload.data;
}

Validate configuration before go-live

Run the connector test operation after any credential rotation, permission change, or tenant migration. This quick validation step catches auth drift early and reduces production incidents caused by expired secrets or bot registration changes.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "test"
  }'

{
  "success": true,
  "data": {
    "status": "ok",
    "authenticated": true
  }
}

Troubleshooting and reliability

Most connector issues come from credential mismatch, missing bot permissions, or conversation identifiers that are no longer valid for the target tenant. Treat integration calls as retryable where possible, but keep operations idempotent so retries do not create duplicate messages or state changes. When failures occur, capture execution IDs and response details in your logs so your team can quickly correlate connector runs with Teams-side diagnostics.

If you need to deepen platform-side troubleshooting, refer to the official Microsoft guidance for Bot Framework and Teams bot deployment: Microsoft Bot Framework documentation.

When configured with stable credentials, clear permission scope, and careful retry strategy, this connector provides a reliable bridge between Tealfabric workflows and Microsoft Teams conversations.