# 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](#overview)
2. [Prerequisites](#prerequisites)
3. [X Developer Portal Setup](#x-developer-portal-setup)
4. [Environment Configuration](#environment-configuration)
5. [OAuth Redirect URI Configuration](#oauth-redirect-uri-configuration)
6. [Permissions & Scopes](#permissions--scopes)
7. [API Tiers & Limitations](#api-tiers--limitations)
8. [Development vs Production](#development-vs-production)
9. [Troubleshooting](#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://developer.twitter.com/)
- 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](https://developer.twitter.com/en/portal/dashboard)
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](https://developer.twitter.com/en/portal/dashboard)
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!