Microsoft Teams, allowing conversational AI bots to interact with users through Teams channels, group chats, and direct messages.

Teams Integration allows you to bring ChatBotKit's conversational AI capabilities directly into Microsoft Teams workspaces. Users can interact with your AI bot through channels, group chats, and direct messages without leaving their Teams environment.

Prerequisites

Before creating a Teams integration, ensure you have the following from the Microsoft Azure portal:

1. A Microsoft Azure account with a registered Bot Framework resource
2. A Bot Framework App ID - the Application (client) ID shown in your Azure Bot Service resource under Configuration
3. A Bot Framework App Secret - a client secret generated under Certificates & Secrets in your Azure App registration
4. Your Tenant ID - the Azure AD directory ID; leave blank to allow multi-tenant bots that work across any Microsoft 365 organization

Creating a Teams Integration

To create a Teams integration, send a POST request with your Bot Framework credentials and a reference to the ChatBotKit bot that should handle conversations:

POST /api/v1/integration/teams/create
Content-Type: application/json

{
  "name": "My Teams Bot",
  "botId": "bot_abc123",
  "botFrameworkAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "botFrameworkAppSecret": "your-app-secret",
  "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "sessionDuration": 86400000,
  "contactCollection": true,
  "stream": true
}
http

The response returns the ID of the newly created integration:

{ "id": "teams_integration_xyz789" }
json

Integration Fields

After Creating the Integration

Once you have an integration ID, complete the setup in Azure Bot Service:

1. Copy your integration's callback URL from the ChatBotKit dashboard
2. In Azure Bot Service, set the Messaging Endpoint to this callback URL
3. Enable the Microsoft Teams channel in Azure Bot Service
4. Call the setup endpoint to validate your credentials (see below)

Note: Credentials are stored securely and the App Secret is never returned in list or fetch responses to protect sensitive information.

Setting Up and Validating Your Teams Integration

The setup endpoint validates your Microsoft Bot Framework credentials by requesting an access token from Azure Active Directory. This confirms that the App ID, App Secret, and Tenant ID stored in your integration are correctly configured and that ChatBotKit can communicate with the Bot Framework on your behalf.

Setup is automatically triggered after every successful update to a Teams integration. You can also call it manually at any time to re-verify credentials without making any other changes - useful after rotating secrets in Azure or when troubleshooting authentication issues.

POST /api/v1/integration/teams/{teamsIntegrationId}/setup
Content-Type: application/json

{}
http

A successful response confirms that your credentials are valid:

{ "id": "teams_integration_xyz789" }
json

What Setup Validates

The setup call performs a live credential check by requesting a client credentials token from Microsoft's OAuth 2.0 token endpoint. It requires:

• A non-empty botFrameworkAppId stored on the integration
• A non-empty botFrameworkAppSecret stored on the integration

If the Tenant ID is omitted, the validation uses the botframework.com authority, which supports multi-tenant bot registrations. If a Tenant ID is present, it uses login.microsoftonline.com/{tenantId} instead.

Troubleshooting Setup Failures

If setup returns a 409 Conflict error, the Bot Framework credential check failed. Common causes and remedies:

• Missing App ID or Secret: Update the integration with valid credentials before calling setup.
• Incorrect App Secret: The secret may have expired or been regenerated in Azure. Rotate a new secret, update the integration with the new value, then call setup again.
• Wrong Tenant ID: If your Azure Bot uses a single-tenant configuration, ensure the tenantId matches the Azure AD directory ID exactly. For multi-tenant bots, leave tenantId blank.
• App permissions not granted: Verify the App registration in Azure has the required API permissions for Bot Framework (https://api.botframework.com/.default).

Note: Setup does not modify any integration settings - it only verifies the credentials currently stored. To fix credential errors, use the update endpoint first, then call setup to confirm.

Updating a Teams Integration

Update the configuration of an existing Teams integration. Send a POST request with only the fields you want to change - all fields are optional. Only the fields you provide will be modified; all others remain unchanged.

POST /api/v1/integration/teams/{teamsIntegrationId}/update
Content-Type: application/json

{
  "name": "Updated Teams Bot",
  "botFrameworkAppId": "your-app-id",
  "botFrameworkAppSecret": "your-app-secret",
  "stream": true,
  "attachments": true
}
http

Updatable Fields

After Updating

A setup event is automatically triggered after every successful update to validate the Bot Framework credentials. If the botFrameworkAppId or botFrameworkAppSecret has changed, the validation will verify the new credentials against the Microsoft Bot Framework.

The response returns the integration ID on success:

{ "id": "teams_integration_abc123" }
json

Note: To rotate credentials securely, update botFrameworkAppSecret and botFrameworkAppId together in a single request to avoid a window where mismatched credentials could cause validation failures.

Listing Teams Integrations

Retrieve a paginated list of all Microsoft Teams integrations associated with your ChatBotKit account. Use this endpoint to audit existing integrations, build management dashboards, or discover integration IDs for use with other operations.

GET /api/v1/integration/teams/list
http

Pagination

Results are returned in descending order by default (newest first). Use the cursor value from a previous response to fetch the next page of results, and take to control how many items appear per page:

GET /api/v1/integration/teams/list?take=20&order=asc
http

Filtering

Filter integrations by metadata using deep object notation:

GET /api/v1/integration/teams/list?meta[region]=us-east
http

Response Fields

Each integration object includes:

• id: Unique identifier for the integration
• name: Human-readable label for the integration
• description: Optional description of the integration's purpose
• blueprintId: Associated blueprint ID (if linked)
• botId: The bot that handles incoming Teams messages
• botFrameworkAppId: The Microsoft Bot Framework Application ID registered in Azure. The botFrameworkAppSecret and tenantId fields are omitted from list responses for security reasons.
• contactCollection: Whether visitor contact data is collected
• sessionDuration: Conversation session timeout in milliseconds
• allowFrom: Restriction pattern for which sender types receive responses
• meta: Custom metadata key-value pairs
• createdAt: ISO timestamp of integration creation
• updatedAt: ISO timestamp of last modification

Security Note: The botFrameworkAppSecret and tenantId fields are intentionally excluded from list responses to prevent credential exposure. Use the fetch endpoint to retrieve individual integration details, where these fields are also masked for security.

Example Response

{
  "items": [
    {
      "id": "teams_abc123",
      "name": "Internal Helpdesk Bot",
      "description": "Handles IT support requests in Microsoft Teams",
      "botId": "bot_xyz789",
      "botFrameworkAppId": "12345678-aaaa-bbbb-cccc-dddddddddddd",
      "contactCollection": false,
      "sessionDuration": null,
      "allowFrom": null,
      "meta": { "team": "it-support" },
      "createdAt": "2025-02-01T09:00:00Z",
      "updatedAt": "2025-02-01T09:00:00Z"
    }
  ],
  "cursor": null
}
json

For managing individual integrations, use the fetch, update, and delete endpoints described in the following sections.

Fetching a Teams Integration

Retrieve the complete configuration details for a specific Microsoft Teams integration by its unique ID. Use this endpoint to inspect current settings, verify bot associations, or confirm configuration before making updates.

GET /api/v1/integration/teams/{teamsIntegrationId}/fetch
http

Replace {teamsIntegrationId} with the ID returned when the integration was created, or obtained from the list endpoint.

Response Fields

The response includes all configuration fields for the integration:

• id: Unique identifier for the integration
• name: Human-readable label for the integration
• description: Optional description of the integration's purpose
• blueprintId: Associated blueprint ID (if linked)
• botId: The bot that handles incoming Teams messages
• botFrameworkAppId: The Microsoft Bot Framework Application ID registered in the Azure portal. This value is safe to expose and is used when configuring the bot channel registration.
• contactCollection: Whether visitor contact data is collected during conversations
• sessionDuration: Conversation session timeout in milliseconds (null for unlimited)
• allowFrom: Restriction pattern for which sender types receive responses
• meta: Custom metadata key-value pairs attached to the integration
• createdAt: ISO timestamp of integration creation
• updatedAt: ISO timestamp of last modification

Security Note: The botFrameworkAppSecret and tenantId fields are intentionally excluded from fetch responses to prevent credential exposure. These are write-only fields - you can set them via create or update, but they are never returned in API responses.

Example Response

{
  "id": "teams_abc123",
  "name": "Internal Helpdesk Bot",
  "description": "Handles IT support requests in Microsoft Teams",
  "blueprintId": null,
  "botId": "bot_xyz789",
  "botFrameworkAppId": "12345678-aaaa-bbbb-cccc-dddddddddddd",
  "contactCollection": false,
  "sessionDuration": null,
  "allowFrom": null,
  "meta": { "team": "it-support" },
  "createdAt": "2025-02-01T09:00:00Z",
  "updatedAt": "2025-02-10T11:30:00Z"
}
json

If the integration does not exist or belongs to another account, the endpoint returns a 404 Not Found or 403 Forbidden error respectively.

Deleting a Teams Integration

Permanently removes a Teams integration and all of its associated configuration from your account. Once deleted, the integration's webhook endpoint will no longer accept messages from Microsoft Teams, and the connected ChatBotKit bot will stop receiving user interactions from Teams channels, group chats, and direct messages.

Deletion is an irreversible operation. Before deleting an integration, consider whether you need to archive conversation history or export any data associated with the integration. After deletion, you will need to create a new integration and reconfigure your Azure Bot Service messaging endpoint if you want to restore Teams connectivity.

To delete a Teams integration, send a POST request with the integration ID:

POST /api/v1/integration/teams/{teamsIntegrationId}/delete
Content-Type: application/json

{}
http

The response confirms the deletion by returning the ID of the removed integration:

{
  "id": "teams-integration-abc123"
}
json

What Happens During Deletion:

• The integration configuration is permanently removed from your account
• The integration's webhook endpoint stops accepting Bot Framework activities
• Any active conversation sessions associated with the integration will end
• The connected bot remains intact and can be reused with a new integration
• Previously logged conversations and event history are preserved

Before Deleting:

• Remove or update the messaging endpoint in your Azure Bot Service to avoid delivery failures to a non-existent endpoint
• Notify any Teams users who are actively using the bot
• Consider whether bot sessions should be terminated gracefully first

Important: Only the owner of the integration can delete it. Attempts to delete an integration belonging to another user will result in an authorization error.

Webhook Callbacks and Event Handling

The callback endpoint receives Bot Framework activity notifications from Microsoft Teams. This endpoint serves as the messaging endpoint configured in the Azure Bot Service, bridging Teams messaging with ChatBotKit's conversational AI.

Microsoft Bot Framework sends activity objects to this endpoint whenever users interact with the bot in Teams channels, group chats, or direct messages. The endpoint handles authentication, activity parsing, and queuing messages for asynchronous processing.

Authentication

Every request from Bot Framework includes a Bearer token in the Authorization header. The endpoint validates this JWT token against Microsoft's OpenID metadata to ensure the request is authentic. Requests with missing or invalid tokens are rejected with a 401 response.

Supported Activity Types

Message Activities: User-sent text messages are extracted and queued for processing by the conversational AI engine.

Conversation Update Activities: Events like members being added or removed from a conversation are logged for monitoring.

Installation Update Activities: Events related to the bot being installed or uninstalled are logged.

Webhook Troubleshooting

Authentication Failures: If callback requests fail authentication:

• Verify the Bot Framework App ID matches your Azure Bot registration
• Ensure the messaging endpoint URL in Azure Bot Service points to your integration's callback URL
• Check that the App Secret is correctly configured

Message Processing Issues: If messages aren't being processed:

• Check event logs for callback delivery confirmations
• Verify the bot has been properly added to the Teams channel or chat
• Ensure the Bot Framework App ID and Secret are valid

Teams Queue Processing and Background Operations

The Teams queue system handles asynchronous processing of message events and setup operations. This background processing architecture enables complex AI conversations and streaming responses without blocking the Bot Framework webhook response.

The queue processes two primary event types: interaction events that handle user messages and AI conversation processing, and setup events that validate Bot Framework credentials. Events are queued with deduplication to prevent duplicate processing of the same activity.

Interaction Event Processing

When a user sends a message in Teams, the callback endpoint queues an interaction event containing the activity ID, conversation ID, service URL, sender information, and message content. The queue handler processes these events asynchronously, managing conversation state, session management, and AI response generation.

The handler retrieves or creates a conversation session based on the user ID and integration configuration. Session duration is controlled by the integration's sessionDuration setting, defaulting to one day. Sessions enable contextual conversations where the bot remembers previous messages within the session window.

Conversation Processing and Streaming

After establishing a conversation session, the queue handler processes the user's message through the configured bot's conversation engine. If streaming is enabled, responses are sent to Teams in chunks for a progressive response experience using the Bot Framework connector API.

Session Management

Sessions are stored in Redis with keys in the format teams-session-{integrationId}-{userId}, ensuring each user has an independent conversation context. Users can restart their session by sending ///restart, ///reset, or ///new.