Vantage Slack Integration Documentation

Overview

The Slack Integration in Vantage is designed to facilitate seamless interaction between the Vantage data analytics platform and Slack, a popular collaboration tool. This integration enables users to retrieve critical information from Slack, such as user profiles, conversation histories, app requests, and more. It allows analytics teams to analyze communication patterns and file sharing within their organizations, further enhancing productivity and insight generation.

Settings

The Slack Integration contains several configurable settings that dictate its behavior and functionality. Below are the details for each setting:

1. API Base URL

   • Input Type: String
   • Description: This setting defines the base URL for the Slack API. By default, it is set to https://slack.com/api. Changing this would affect all API requests made by the integration, and it is critical for routing requests to the correct endpoint.
   • Default Value: https://slack.com/api

2. Scopes

   • Input Type: Array of Strings
   • Description: Scopes dictate the permissions granted to the integration. It's used to determine which Slack API endpoints can be accessed. The integration will validate against these scopes when making requests.
   • Default Value: null (dynamically fetched from credentials)

3. Headers for API Requests

   • Input Type: Object
   • Description: This setting includes the necessary HTTP headers for making requests to the Slack API, specifically the Authorization header, which contains the Bearer token, and Content-Type, which is set to application/json.
   • Default Value: Constructed from provided credentials

4. Pagination Cursor

   • Input Type: String
   • Description: Used to manage pagination within API responses where results are returned in multiple pages. This cursor helps in pulling additional data as needed.
   • Default Value: null (extracted from API responses)

5. Limit

   • Input Type: Numeric
   • Description: This setting specifies the maximum number of results returned in a request. It is crucial for controlling API usage and performance.
   • Default Value: Various, depending on the specific API request being executed (e.g., 100 for app requests, 200 for user lists)

6. Query Parameters

   • Input Type: String
   • Description: This encompasses various parameters that can be used in search functions, such as query, sort, and sortDir, allowing further customization of search results.
   • Default Value: Varies based on the API endpoints

Detailed Functionality Underlying Settings

A critical aspect of this integration is the validation of scopes. The integration checks that required scopes are present before executing any API call. If missing, an error will be thrown, thus providing a layer of security and ensuring that the integration only accesses permitted data.

Request Methods

listAppRequests

• Purpose: To retrieve app installation requests for a team.
• Expected Data: teamId, enterpriseId, includeCertified, limit, cursor

getUserProfile

• Purpose: Fetches the profile of a specific user given their user ID.
• Expected Data: userId

listUsers

• Purpose: Lists users in a Slack workspace.
• Expected Data: teamId, limit, cursor

getConversationHistory

• Purpose: Retrieves history of messages in a specific channel.
• Expected Data: channel, oldest, latest, limit, cursor

listFiles

• Purpose: Lists files uploaded to Slack within specified timestamps.
• Expected Data: userId, tsFrom, tsTo, channel, limit, page

searchMessages

• Purpose: Searches for messages that contain a specific query within Slack.
• Expected Data: query, sort, sortDir, count, page

getAdminAnalyticsFile

• Purpose: Retrieves an admin analytics file for a specified date.
• Expected Data: date, teamId

getConversationTeams

• Purpose: Fetches teams associated with a conversation channel.
• Expected Data: channel_id, cursor

Use Cases & Examples

Use Case 1: User Activity Analysis

An organization wants to analyze user interactions within Slack to understand engagement levels and identify key contributors. By utilizing methods like listUsers and getUserProfile, the organization can gather data on user activity and profile information across different teams to assess productivity.

Use Case 2: File Sharing Insights

A company aims to audit file sharing across its Slack channels to ensure compliance with data policies. The listFiles method can be employed to retrieve all files shared, along with the user details, timestamps, and channels, facilitating a comprehensive audit trail.

Use Case 3: Conversation Analysis

A team conducts a sentiment analysis on conversations held within Slack channels to gauge team morale. By retrieving conversation histories through getConversationHistory, they can analyze text for sentiment insights using external AI tools.

Configuration Example for Use Case 1

To implement the User Activity Analysis, the following configuration can be used:

{
  "teamId": "T12345678",
  "limit": 100,
  "cursor": null
}

The integration would call listUsers function with this configuration, retrieve up to 100 users from a specific Slack workspace (denoted by teamId), and facilitate further analysis with the returned user data.

Conclusion

The Slack Integration within Vantage is a powerful tool that enhances data access and analysis related to user interactions on Slack. Through well-defined settings and robust functionality, organizations can leverage their API to extract valuable insights that drive decision-making and improve team collaboration.