Teams Integration

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

To set up a Teams integration, you need:

  1. A Microsoft Azure account with a registered Bot Framework resource
  2. A Bot Framework App ID and App Secret from Azure Bot Service
  3. A configured messaging endpoint pointing to your integration's callback URL

Creating a Teams Integration

To create a Teams integration, send a POST request to the create endpoint with your Bot Framework credentials, a reference to the ChatBotKit bot, and optional configuration:

  • botFrameworkAppId — The Application (client) ID from your Azure Bot
  • botFrameworkAppSecret — The client secret from your Azure Bot
  • tenantId — Your Azure AD tenant ID (optional, defaults to multi-tenant)
  • botId — The ChatBotKit bot to power conversations
  • sessionDuration — How long conversation context persists (in ms)
  • stream — Enable streaming responses for progressive message delivery
  • contactCollection — Enable contact record creation for users

Setting Up Your Teams Integration

The setup endpoint validates your Bot Framework credentials by requesting an access token from Azure AD. This confirms that the App ID, App Secret, and Tenant ID are correctly configured.

Setup is automatically triggered when updating an integration, but can also be called manually to verify credentials.

Updating a Teams Integration

Update the configuration of an existing Teams integration. After updating, a setup event is automatically triggered to validate the updated Bot Framework credentials.

All fields are optional — only the provided fields will be updated. The meta field is merged with existing metadata rather than replaced.

Listing Teams Integrations

Retrieve a paginated list of all Teams integrations associated with your account. Use the cursor parameter to page through results and meta to filter by metadata key-value pairs.

Fetching a Teams Integration

Retrieve the full details of a specific Teams integration by its ID. The response includes all configuration fields except sensitive credentials like the Bot Framework App Secret and Tenant ID.

Deleting a Teams Integration

Permanently removes a Teams integration and its associated configuration. The bot will no longer receive messages from Teams after deletion.

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.

Go to cbk.ai