Teams Chat Integration Documentation

Overview

The Teams Chat Integration is a component of the Vantage analytics and data platform that facilitates interactions with Microsoft Teams chats through the Microsoft Graph API. It allows users to create, read, and send messages in Microsoft Teams chats, making it an essential tool for organizations that rely on Teams for collaboration.

How It Works

This integration handles OAuth authentication to support sending requests to the Microsoft Graph API. It retrieves and refreshes access tokens as needed, allows for interaction with ongoing chats, and supports sending messages and extracting chat data for analytics purposes.

Data Expectations

This integration expects data in the form of structured requests to the Microsoft Graph API, including specific parameters defined by the API for chat and messaging actions. It manages encrypted credentials to maintain secure connections and adheres to the OAuth2 framework for authentication.

Settings

The following settings are used to configure the Teams Chat Integration:

1. apiUrl

• Type: String
• Description: This is the base URL for the Microsoft Graph API. This endpoint is where all requests to the API will be sent.
• Default Value: https://graph.microsoft.com/v1.0

2. tokenUrl

• Type: String
• Description: This URL is used to request an access token from Microsoft's OAuth 2.0 service. It is where the refresh token will be sent to retrieve a new access token when the current one expires.
• Default Value: https://login.microsoftonline.com/common/oauth2/v2.0/token

3. serviceId

• Type: String
• Description: Represents the identifier for the service integration. It uniquely identifies this integration instance within Vantage.
• Default Value: Not explicitly defined in the code; must be provided during initialization.

4. clientId

• Type: String
• Description: This is the application's client ID registered in Azure Active Directory. It is used when interacting with the Microsoft OAuth service to authenticate requests.
• Default Value: Not explicitly defined in the code; must be provided during initialization.

5. credentialId

• Type: String
• Description: Unique identifier for storing credentials securely within the Vantage platform. It ensures that tokens and other sensitive information are kept appropriately.
• Default Value: Not explicitly defined in the code; must be provided during initialization.

6. _accessToken

• Type: String or null
• Description: Stores the current access token used to authenticate requests to the Microsoft Graph API. It is refreshed as needed.
• Default Value: null

7. _tokenExpiry

• Type: Date or null
• Description: Holds the expiration date and time of the current access token. This helps in determining when to refresh the token.
• Default Value: null

Use Cases & Examples

Use Case 1: Real-Time Collaboration

Organizations may want their analytics platform to facilitate real-time collaboration by allowing users to initiate chats from the Vantage platform, improving workflow efficiency.

Use Case 2: Data Aggregation

Data teams may want to aggregate messages from several chats for analytics purposes. This integration allows them to pull chat and message data into Vantage for analysis.

Use Case 3: Alerting and Notification

Using this integration, a system could send alerts or notifications to specific Teams chats based on data thresholds or events detected in the Vantage analytics system.

Example Configuration

For the use case of Data Aggregation, a configuration might look like this:

{
    "serviceId": "unique-service-id",
    "clientId": "your-client-id",
    "credentialId": "your-credential-id"
}

Here, the service can call the listChats method to gather all chats the user is part of, thus allowing the organization to analyze conversations tied to key projects.

Sample request to list the last 50 chats:

const teamsChatIntegration = new TeamsChatIntegration(encryptedRecord, 'unique-service-id', 'your-client-id', 'your-credential-id');

teamsChatIntegration.listChats({ maxResults: 50 })
    .then(chats => {
        console.log('Fetched Chat List:', chats);
    })
    .catch(error => {
        console.error('Error fetching chats:', error);
    });

Billing Impacts

Utilizing the Teams Chat Integration may incur costs associated with API usage as defined by Microsoft’s pricing models for their Azure services and Microsoft Graph API access. Depending on the volume of the data being processed (e.g., number of messages read or sent), it is essential to monitor API usage to manage costs effectively.

This careful documentation encapsulates the Teams Chat Integration's functionality, settings, use cases, configurations, and billing impacts, providing users with a comprehensive understanding of how to leverage this powerful tool for enhanced analytics and collaboration.