X Integration Documentation

Overview

The X Integration for the Vantage analytics and data platform provides a structured interface for interacting with X's API. It is designed to facilitate seamless communication with X's OAuth 2.0 authentication system, enabling data retrieval and interaction with user profiles, tweets, and followers.

Purpose

The purpose of the X Integration is to enable developers to authenticate with X's API, retrieve user information, access tweets, send tweets, and manage followers and followings. It acts as a bridge between Vantage and X, allowing users to leverage X's data within the Vantage platform for analytics and reporting.

How It Works

1. Authentication: The integration handles OAuth 2.0 token management, including acquiring and refreshing access tokens.
2. API Calls: It provides methods for making API requests to retrieve and manipulate data, such as user profiles, tweets, and connections.
3. Error Management: It includes robust error handling for network issues, API errors, and authentication failures.

Settings

The integration uses several settings to configure its operation. Below are the details of these settings:

Constructor Settings

• encryptedRecord

  • Type: String
  • Description: An encrypted string containing user credentials used to authenticate with X. This must be generated during the initial integration setup. Changing this value will require re-authentication.
  • Default: N/A

• serviceId

  • Type: String
  • Description: A unique identifier for the service associated with this integration. This is necessary for managing and identifying this instance within the Vantage environment.
  • Default: N/A

• clientId

  • Type: String
  • Description: Represents the client ID provided by X for OAuth 2.0 authentication. If this value is not set correctly, authentication requests will fail.
  • Default: N/A

• credentialId

  • Type: String
  • Description: The identifier used to store and retrieve encrypted credentials in the database . Changing this will affect the ability to update stored credentials.
  • Default: N/A

Token Management

• _accessToken

  • Type: String or Null
  • Description: Stores the current OAuth 2.0 access token. This is used to authenticate API requests. If null, a new access token will be requested.
  • Default: Null

• _tokenExpiry

  • Type: Date or Null
  • Description: Indicates the expiry time of the currently stored access token. If the current time exceeds this value, the token must be refreshed.
  • Default: Null

Data Expectation

The integration expects the following types of data:

1. User Credentials: Encrypted data containing the access token, refresh token, and expiry time.
2. API Response Formats: All responses from the X API should be in JSON format, including user data, tweet information, and follower metrics.

Use Cases & Examples

Use Case 1: Monitoring Social Media Activity

A marketing team wants to monitor the social media engagement of their brand on X. They can utilize the X Integration to fetch user metrics and tweet performance for tailored reporting.

Use Case 2: Automated Posting

A user wants to automate tweet posting at specific times. They can configure the integration to handle scheduled tweets based on pre-defined triggers in Vantage.

Example Configuration for Automated Posting

The following is an example configuration that enables automated posting of tweets:

{
  "encryptedRecord": "encrypted_data_here",
  "serviceId": "unique_service_id",
  "clientId": "your_client_id",
  "credentialId": "your_credential_id"
}

Setting Up Automated Tweets

To automate tweeting, the following steps should be implemented:

1. Configure the integration with valid credentials as shown above.
2. Use the createTweet method to define the content of the tweet.

const tweetIntegration = new XIntegration(encryptedRecord, serviceId, clientId, credentialId);
const tweetData = {
  text: "Automated reminder: Attend our event on Saturday!",
};

tweetIntegration.createTweet(tweetData)
  .then(response => {
    console.log("Tweet posted successfully!", response);
  })
  .catch(error => {
    console.error("Error posting tweet:", error);
  });

Billing Impact

Utilizing the X Integration may incur costs based on the usage of the X API, including potential overage fees if you exceed the API usage limits defined by X. Users should regularly monitor API usage to manage costs effectively.

Conclusion

The X Integration in Vantage allows for extensive interaction with the X platform. By properly configuring the integration and using its powerful functionalities, users can gain valuable insights into their social media activity, automate interactions, and ultimately enhance their digital presence.