# Twitter API Setup Guide

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Create Twitter Developer Account](#create-twitter-developer-account)
3. [Create Twitter App](#create-twitter-app)
4. [Configure OAuth Settings](#configure-oauth-settings)
5. [Set Up Account Activity API](#set-up-account-activity-api)
6. [Configure Webhooks](#configure-webhooks)
7. [Testing the Integration](#testing-the-integration)
8. [Troubleshooting](#troubleshooting)

---

## Prerequisites

Before setting up Twitter API integration, ensure you have:

- ✅ Twitter account (preferably business account)
- ✅ MKT X Service deployed and accessible via HTTPS
- ✅ Valid SSL certificate for webhook URL
- ✅ Access to server configuration

---

## Create Twitter Developer Account

### Step 1: Apply for Developer Access

1. Go to [Twitter Developer Portal](https://developer.twitter.com/)
2. Click "Sign up" and log in with your Twitter account
3. Fill out the application form:
   - **Account type**: Choose "Business" or "Professional"
   - **Primary use case**: Marketing automation and customer service
   - **Will you make Twitter content available to government entities?**: No
4. Review and accept the Developer Agreement
5. Verify your email address

**Processing Time**: Usually instant, but can take up to 24-48 hours

### Step 2: Create a Project

1. Navigate to the [Developer Portal Dashboard](https://developer.twitter.com/en/portal/dashboard)
2. Click "Create Project"
3. Fill in project details:
   - **Project name**: "GoodGo Marketing"
   - **Use case**: Customer engagement
   - **Project description**: "Twitter marketing automation for e-commerce"
4. Click "Next" and "Create"

---

## Create Twitter App

### Step 1: Create New App

1. In your project, click "+ Add App"
2. Choose "Production" environment
3. Enter app name (e.g., "GoodGo-MKT-X-Prod")
4. Save your API credentials:

```
API Key: xxxxxxxxxxxxxxxxxxxxx
API Key Secret: xxxxxxxxxxxxxxxxxxxxx
Bearer Token: xxxxxxxxxxxxxxxxxxxxx
```

**⚠️ Important**: Store these credentials securely. They won't be shown again.

### Step 2: Configure App Permissions

1. Go to your app settings
2. Navigate to "User authentication settings"
3. Click "Set up"
4. Configure permissions:

```
App permissions:
☑ Read
☑ Write  
☑ Direct Messages

Type of App:
☑ Web App, Automated App or Bot

App info:
Callback URI: https://your-domain.com/api/v1/mkt-x/oauth/callback
Website URL: https://your-domain.com
```

5. Save changes

---

## Configure OAuth Settings

### OAuth 1.0a Setup

Twitter Direct Messages API requires OAuth 1.0a authentication.

### Step 1: Generate Access Tokens

1. In app settings, go to "Keys and tokens"
2. Under "Authentication Tokens", click "Generate"
3. Save the tokens:

```
Access Token: xxxxxxxxxxxxxxxxxxxxx
Access Token Secret: xxxxxxxxxxxxxxxxxxxxx
```

### Step 2: Add Credentials to Service

Update your `appsettings.json`:

```json
{
  "Twitter": {
    "ApiKey": "your_api_key",
    "ApiKeySecret": "your_api_key_secret",
    "BearerToken": "your_bearer_token",
    "AccessToken": "your_access_token",
    "AccessTokenSecret": "your_access_token_secret",
    "WebhookUrl": "https://your-domain.com/api/v1/mkt-x/webhooks/twitter"
  }
}
```

**🔒 Security**: Use environment variables or secrets manager for production:

```bash
export TWITTER__API_KEY="your_api_key"
export TWITTER__API_KEY_SECRET="your_api_key_secret"
export TWITTER__ACCESS_TOKEN="your_access_token"
export TWITTER__ACCESS_TOKEN_SECRET="your_access_token_secret"
```

---

## Set Up Account Activity API

The Account Activity API allows you to receive real-time Twitter events via webhooks.

### Step 1: Apply for Account Activity API Access

1. Go to [Account Activity API](https://developer.twitter.com/en/products/twitter-api/account-activity-api) page
2. Request access for your app
3. Select "Sandbox" environment for development (free)
4. For production, you'll need "Enterprise" or "Premium" tier

**Pricing**:
- **Sandbox**: Free (1 webhook, 15 subscriptions)
- **Premium**: Starting from $149/month (5 webhooks, 500 subscriptions)
- **Enterprise**: Custom pricing

### Step 2: Register Webhook URL

Register your webhook URL with Twitter using the Twitter API:

```bash
curl -X POST \
  'https://api.twitter.com/1.1/account_activity/all/:env_name/webhooks.json' \
  -H 'Authorization: OAuth oauth_consumer_key="YOUR_API_KEY", oauth_token="YOUR_ACCESS_TOKEN", oauth_signature="SIGNATURE", oauth_signature_method="HMAC-SHA1", oauth_timestamp="TIMESTAMP", oauth_nonce="NONCE", oauth_version="1.0"' \
  -d 'url=https://your-domain.com/api/v1/mkt-x/webhooks/twitter'
```

**Or use the MKT X Service API**:

```bash
POST /api/v1/mkt-x/accounts/{accountId}/register-webhook
```

### Step 3: Verify CRC (Challenge-Response Check)

Twitter will send a GET request to your webhook URL with a `crc_token` parameter. Your service must respond with:

```json
{
  "response_token": "sha256=base64_encoded_hmac"
}
```

The service automatically handles this via the `/webhooks/verify` endpoint.

### Step 4: Subscribe to User Activity

Subscribe to receive events for your Twitter account:

```bash
curl -X POST \
  'https://api.twitter.com/1.1/account_activity/all/:env_name/subscriptions.json' \
  -H 'Authorization: OAuth ...'
```

---

## Configure Webhooks

### Events You'll Receive

When properly configured, you'll receive these webhook events:

#### Direct Message Events
```json
{
  "direct_message_events": [
    {
      "type": "message_create",
      "id": "123456789",
      "created_timestamp": "1642000000000",
      "message_create": {
        "sender_id": "987654321",
        "message_data": {
          "text": "Hello!"
        }
      }
    }
  ]
}
```

#### Follow Events
```json
{
  "follow_events": [
    {
      "type": "follow",
      "created_timestamp": "1642000000000",
      "source": {
        "id": "987654321"
      },
      "target": {
        "id": "123456789"
      }
    }
  ]
}
```

### Webhook Security

All webhook requests from Twitter include:

1. **X-Twitter-Webhooks-Signature** header
2. HMAC-SHA256 signature of the request body

The service automatically validates this signature using your API key secret.

---

## Testing the Integration

### Step 1: Test OAuth Connection

```bash
# Test OAuth credentials
curl -X POST http://localhost:5000/api/v1/mkt-x/accounts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "oauthToken": "YOUR_ACCESS_TOKEN",
    "oauthTokenSecret": "YOUR_ACCESS_TOKEN_SECRET"
  }'
```

**Expected Response**:
```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "twitterUserId": "123456789",
    "username": "your_username",
    "status": "active"
  }
}
```

### Step 2: Test Webhook URL

Test that your webhook endpoint is accessible:

```bash
curl -X GET 'https://your-domain.com/api/v1/mkt-x/webhooks/verify?crc_token=test'
```

**Expected Response**:
```json
{
  "response_token": "sha256=..."
}
```

### Step 3: Send Test Direct Message

1. Send a direct message to your connected Twitter account from another account
2. Check service logs to confirm webhook event was received
3. Verify conversation and message were created in the database

**Check logs**:
```bash
docker-compose logs -f mkt-x-service-net | grep "Twitter webhook"
```

### Step 4: Test Outbound Message

Send a message from the service:

```bash
curl -X POST http://localhost:5000/api/v1/mkt-x/conversations/{conversationId}/messages \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from MKT X Service!",
    "type": "text"
  }'
```

Verify the message appears in Twitter DMs.

---

## Troubleshooting

### Issue 1: Webhook Registration Fails

**Error**: `401 Unauthorized` when registering webhook

**Solution**:
1. Verify OAuth credentials are correct
2. Ensure your app has "Read + Write + Direct Messages" permissions
3. Check that webhook URL is HTTPS (not HTTP)
4. Confirm SSL certificate is valid

### Issue 2: CRC Verification Fails

**Error**: Twitter webhook shows "Invalid response_token"

**Solution**:
1. Verify API Key Secret is correct in configuration
2. Check HMAC calculation in `/webhooks/verify` endpoint
3. Ensure response format matches Twitter requirements:
   ```json
   {"response_token": "sha256=..."}
   ```

### Issue 3: No Webhook Events Received

**Symptoms**: No events in logs after sending DM

**Solution**:
1. Verify webhook is registered:
   ```bash
   curl -X GET \
     'https://api.twitter.com/1.1/account_activity/all/:env_name/webhooks.json' \
     -H 'Authorization: OAuth ...'
   ```
2. Check webhook subscription:
   ```bash
   curl -X GET \
     'https://api.twitter.com/1.1/account_activity/all/:env_name/subscriptions/list.json' \
     -H 'Authorization: OAuth ...'
   ```
3. Ensure firewall allows inbound HTTPS traffic
4. Check service logs for webhook validation errors

### Issue 4: Rate Limit Exceeded

**Error**: `429 Too Many Requests`

**Solution**:
- Twitter DM limit: 500 messages / 24 hours per account
- Check current usage:
  ```bash
  curl -X GET \
    'https://api.twitter.com/1.1/application/rate_limit_status.json' \
    -H 'Authorization: Bearer YOUR_BEARER_TOKEN'
  ```
- Implement message queuing to respect limits
- Consider using multiple Twitter accounts for high-volume scenarios

### Issue 5: OAuth Signature Error

**Error**: `401 Unauthorized - Invalid OAuth signature`

**Solution**:
1. Verify all OAuth parameters are correctly encoded
2. Check system time is synchronized (NTP)
3. Ensure no extra spaces in OAuth header
4. Use a library like `OAuth.DotNetCore` instead of manual implementation

---

## Best Practices

### 1. Security

- ✅ Store API credentials in environment variables or secrets manager
- ✅ Use HTTPS for all webhook endpoints
- ✅ Validate webhook signatures
- ✅ Rotate OAuth tokens periodically
- ✅ Implement rate limiting on your endpoints

### 2. Reliability

- ✅ Implement retry logic for failed API calls
- ✅ Use message queues for webhook processing
- ✅ Monitor webhook endpoint uptime
- ✅ Set up alerting for API errors
- ✅ Keep backup of webhook events

### 3. Performance

- ✅ Process webhooks asynchronously
- ✅ Use caching for user data
- ✅ Batch API requests when possible
- ✅ Implement connection pooling
- ✅ Monitor API quotas

### 4. Compliance

- ✅ Follow Twitter's [Developer Policy](https://developer.twitter.com/en/developer-terms/policy)
- ✅ Respect user privacy and data protection laws (GDPR, CCPA)
- ✅ Include unsubscribe options in automated messages
- ✅ Clearly identify bot messages
- ✅ Don't spam users

---

## Rate Limits

### Twitter API v2 Limits

| Endpoint | Limit | Window |
|----------|-------|--------|
| Direct Messages (Send) | 500 requests | 24 hours |
| Direct Messages (Read) | 300 requests | 15 minutes |
| User Lookup | 900 requests | 15 minutes |
| Tweet Lookup | 300 requests | 15 minutes |

### Service Rate Limits

The MKT X Service implements these internal limits:

- **Campaigns**: Max 10,000 contacts per day per account
- **API Calls**: 100 requests per minute per merchant
- **Webhook Processing**: 1000 events per minute

---

## Monitoring

### Key Metrics to Track

1. **Webhook Health**
   - Webhook uptime
   - CRC verification success rate
   - Event processing latency

2. **API Usage**
   - Requests per day
   - Error rate
   - Rate limit hits

3. **Business Metrics**
   - Messages sent/received
   - Conversation response time
   - Campaign delivery rate

### Recommended Tools

- **Prometheus + Grafana**: For metrics and dashboards
- **Sentry**: For error tracking
- **Twitter Developer Portal**: For API quota monitoring

---

## Additional Resources

- [Twitter API Documentation](https://developer.twitter.com/en/docs/twitter-api)
- [Account Activity API Guide](https://developer.twitter.com/en/docs/twitter-api/enterprise/account-activity-api/overview)
- [OAuth 1.0a Specification](https://oauth.net/core/1.0a/)
- [Twitter Developer Community](https://twittercommunity.com/)

---

## Support

For issues with Twitter API integration:

- **Twitter Developer Forums**: https://twittercommunity.com/
- **MKT X Service Support**: api-support@goodgo.com
- **Emergency**: support-priority@goodgo.com
