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

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:

The response returns the ID of the newly created integration:

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.

A successful response confirms that your credentials are valid:

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. 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 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:

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

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.