marwan/HH
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
HH/apps/social/setup_docs/x_twitter.md
Faheed 4f2c8e2dbb changes to tik tok
2026-02-12 15:09:48 +03:00

11 KiB
Raw Blame History

X (Twitter) API Setup Guide

This guide provides step-by-step instructions for setting up X (formerly Twitter) API integration for managing tweets and replies.

Table of Contents

  1. Overview
  2. Prerequisites
  3. X Developer Portal Setup
  4. Environment Configuration
  5. OAuth Redirect URI Configuration
  6. Permissions & Scopes
  7. API Tiers & Limitations
  8. Development vs Production
  9. Troubleshooting

Overview

API Version: X API v2 Base URL: https://api.twitter.com/2 Auth URL: https://twitter.com/i/oauth2/authorize Token URL: https://api.twitter.com/2/oauth2/token Auth Method: OAuth 2.0 with PKCE (Proof Key for Code Exchange)

Features Supported

  • Fetch user tweets
  • Read tweet replies (conversation threads)
  • Reply to tweets
  • Automatic token refresh

⚠️ Important Limitations

  • Search API (for fetching replies) requires Basic tier or higher
  • Free tier cannot search for replies - only direct mentions accessible
  • The system supports both tiers with graceful degradation

Prerequisites

  • An X (Twitter) account
  • Access to X Developer Portal
  • HTTPS-enabled server for production (required for OAuth redirect URIs)

X Developer Portal Setup

Step 1: Apply for Developer Access

  1. Navigate to X Developer Portal
  2. Sign in with your X account
  3. Click "Sign up" for free access (or choose a paid tier)
  4. Fill out the application form:
    • Country: Select your country
    • Use Case: Select "Building tools for my own use" or appropriate option
    • Description: Describe your use case in detail:

      "We are building a social media management dashboard that allows organizations to manage and respond to comments and replies on their X/Twitter posts from a centralized interface. This helps community managers respond faster to audience engagement."

  5. Review and accept the developer agreement
  6. Click "Submit"

Step 2: Create a Project & App

  1. Once approved, go to the Developer Portal
  2. Create a Project:
    • Project Name: e.g., "PX360 Social"
    • Use Case: Select "Building tools for my own use"
    • Project Description: Brief description of your application
  3. Create an App within the project:
    • App Name: Unique name for your app (must be globally unique)
    • Environment: Select "Production"

Step 3: Configure OAuth 2.0

  1. In your app settings, go to "Settings" tab

  2. Scroll to "User authentication settings"

  3. Click "Set up"

  4. Select "Web App, Automated App or Bot"

  5. Configure OAuth 2.0:

    General Settings:

    • Callback URI / Redirect URL:
      • Development: http://127.0.0.1:8000/social/callback/X/
      • Production: https://yourdomain.com/social/callback/X/
    • Website URL: Your application URL
    • Terms of Service URL: (Optional) Your ToS URL
    • Privacy Policy URL: (Optional) Your privacy policy URL

  6. Click "Save"

Step 4: Get API Credentials

  1. Go to "Keys and Tokens" tab in your app
  2. Under "OAuth 2.0 Client ID and Client Secret":
    • Click "Regenerate" if needed
    • Copy the Client ID → This is your X_CLIENT_ID
    • Copy the Client Secret → This is your X_CLIENT_SECRET

⚠️ Important: The Client Secret is only shown once. Store it securely!

Environment Configuration

Django Settings (settings.py)

# X (Twitter) API Configuration
X_CLIENT_ID = 'your_client_id_here'
X_CLIENT_SECRET = 'your_client_secret_here'
X_REDIRECT_URI = 'https://yourdomain.com/social/callback/X/'

# TIER CONFIGURATION
# Set to True if you have Enterprise Access (Full-Archive Search)
# Set to False for Free/Basic/Pro tiers (Recent Search)
X_USE_ENTERPRISE = False

Environment Variables (.env)

X_CLIENT_ID=your_client_id_here
X_CLIENT_SECRET=your_client_secret_here
X_REDIRECT_URI=https://yourdomain.com/social/callback/X/
X_USE_ENTERPRISE=False

OAuth Redirect URI Configuration

The redirect URI must match exactly what's configured in the X Developer Portal.

Development

http://127.0.0.1:8000/social/callback/X/
http://localhost:8000/social/callback/X/

Production

https://yourdomain.com/social/callback/X/

⚠️ Note: X requires HTTPS for production redirect URIs. Localhost is allowed for development.

Permissions & Scopes

The application requests the following OAuth scopes:

Scope Description Required
tweet.read Read tweets and timeline ✅ Yes
tweet.write Post and reply to tweets ✅ Yes
users.read Read user profile information ✅ Yes
offline.access Refresh tokens for long-term access ✅ Yes

Code Reference

# apps/social/utils/x.py
class XConfig:
    BASE_URL = "https://api.twitter.com/2"
    AUTH_URL = "https://twitter.com/i/oauth2/authorize"
    TOKEN_URL = "https://api.twitter.com/2/oauth2/token"
    
    SCOPES = [
        "tweet.read", 
        "tweet.write", 
        "users.read", 
        "offline.access"
    ]

API Tiers & Limitations

X API has different access tiers with varying capabilities:

Free Tier ($0/month)

Feature Limit
Post Tweets 1,500/month
User Lookup 500/month
Search API ❌ NOT AVAILABLE

⚠️ Critical: Free tier cannot use the search endpoint, which means fetching tweet replies is not possible. You will see a 403 Forbidden error when trying to search.

Basic Tier ($100/month)

Feature Limit
Post Tweets 3,000/month
Recent Search 60 requests/15 min
User Lookup 900/15 min
Reply Fetching ✅ SUPPORTED

✅ Recommended: Basic tier is the minimum required for full functionality.

Pro Tier ($5,000/month)

Feature Limit
Post Tweets 100,000/month
Recent Search 300 requests/15 min
Full-Archive Search Available

Enterprise Tier (Custom)

Feature Limit
Full-Archive Search ✅ Available
Higher Rate Limits Custom

Setting the Tier

# For Basic/Pro tiers (Recent Search)
X_USE_ENTERPRISE = False  # Uses tweets/search/recent

# For Enterprise tier (Full-Archive Search)
X_USE_ENTERPRISE = True   # Uses tweets/search/all

Development vs Production

Development Setup

Setting Value
X_REDIRECT_URI http://127.0.0.1:8000/social/callback/X/
Protocol HTTP allowed for localhost
X_USE_ENTERPRISE False
Rate Limits Lower limits per 15-min window

Production Setup

Setting Value
X_REDIRECT_URI https://yourdomain.com/social/callback/X/
Protocol HTTPS required
X_USE_ENTERPRISE Based on your tier
Rate Limits Higher limits for paid tiers

Using ngrok for Local Testing

If you need to test with HTTPS locally:

# Install ngrok
npm install -g ngrok

# Create tunnel to local server
ngrok http 8000

# Use the ngrok URL as your redirect URI
# Example: https://abc123.ngrok.io/social/callback/X/

# Update X Developer Portal with the ngrok URL

Troubleshooting

Common Error: "403 Forbidden on Search"

Cause: You're on the Free tier which doesn't include Search API access.

Solution:

  1. Upgrade to at least Basic tier ($100/month)
  2. Or, accept limited functionality (cannot fetch replies)
  3. Check your tier in X Developer Portal → Products

Common Error: "Invalid Redirect URI"

Cause: The redirect URI doesn't match what's configured in X Developer Portal.

Solution:

  1. Go to X Developer Portal → Your App → Settings
  2. Check "User authentication settings"
  3. Ensure redirect URI matches exactly (including trailing slash)
  4. Wait a few minutes for changes to propagate

Common Error: "Client Authentication Failed"

Cause: Invalid Client ID/Secret or incorrect auth header format.

Solution:

  1. Verify credentials in X Developer Portal → Keys and Tokens
  2. Ensure you're using Basic Auth for token exchange: 
    # Correct: Base64 encoded "client_id:client_secret"
Authorization: Basic base64(client_id:client_secret)
  3. Regenerate credentials if needed

Common Error: "Rate Limit Exceeded (429)"

Cause: Too many API requests in the rate limit window.

Solution:

  • Application handles rate limits with automatic retry
  • Check x-rate-limit-reset header for reset time
  • Wait for the window to reset (usually 15 minutes)
  • Consider upgrading to a higher tier for more capacity

Common Error: "Token Expired"

Cause: Access token expired (typically after 2 hours).

Solution:

  • Application automatically refreshes tokens using offline.access scope
  • If refresh fails, user needs to re-authenticate
  • Check that refresh token is stored in database

Common Error: "PKCE Verification Failed"

Cause: Code verifier doesn't match the challenge used during authorization.

Solution:

  • Application generates PKCE pair automatically
  • Ensure code_verifier is stored in session during auth flow
  • Verify S256 challenge method is used

API Rate Limits

Free Tier

Endpoint Rate Limit
Post Tweet 1,500/month
Get User 500/month

Basic Tier

Endpoint Rate Limit
Post Tweet 3,000/month
Recent Search 60/15 min
Get User 900/15 min

Pro Tier

Endpoint Rate Limit
Post Tweet 100,000/month
Recent Search 300/15 min
Get User 900/15 min

Verification

After setup, verify the integration:

  1. Navigate to /social/ in your application
  2. Click "Connect X (Twitter)"
  3. Authorize with your X account
  4. Verify your profile is fetched
  5. Check if tweets are loaded
  6. Test posting a reply to a tweet

Testing Search (Basic+ Tier Required)

# In Django shell
from apps.social.services.x import XService
from apps.social.models import SocialAccount

account = SocialAccount.objects.filter(platform='X').first()
tweets = XService.get_user_tweets(account)
print(f"Fetched {len(tweets)} tweets")

Support Resources

Last Updated: February 2026 API Version: X API v2