marwan/HH
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
HH/apps/social/setup_docs/x_twitter.md
ismail e119312a9c clean up version
2026-04-19 10:53:12 +03:00

3.6 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!