103 lines
3.6 KiB
Markdown
103 lines
3.6 KiB
Markdown
# 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!
|