admin/pos-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a414d7d528df8a39a374c748bfdede8a93d2d363
pos-system/services/mkt-x-service-net/docs/en/TWITTER_SETUP.md

12 KiB
Raw Blame History

Twitter API Setup Guide

Table of Contents

  1. Prerequisites
  2. Create Twitter Developer Account
  3. Create Twitter App
  4. Configure OAuth Settings
  5. Set Up Account Activity API
  6. Configure Webhooks
  7. Testing the Integration
  8. 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
  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
  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
  1. 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:

{
  "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:

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 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:

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:

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:

{
  "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:

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

{
  "direct_message_events": [
    {
      "type": "message_create",
      "id": "123456789",
      "created_timestamp": "1642000000000",
      "message_create": {
        "sender_id": "987654321",
        "message_data": {
          "text": "Hello!"
        }
      }
    }
  ]
}

Follow Events

{
  "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

# 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:

{
  "success": true,
  "data": {
    "id": "uuid",
    "twitterUserId": "123456789",
    "username": "your_username",
    "status": "active"
  }
}

Step 2: Test Webhook URL

Test that your webhook endpoint is accessible:

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

Expected Response:

{
  "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:

docker-compose logs -f mkt-x-service-net | grep "Twitter webhook"

Step 4: Test Outbound Message

Send a message from the service:

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: 
    {"response_token": "sha256=..."}

Issue 3: No Webhook Events Received

Symptoms: No events in logs after sending DM

Solution:

  1. Verify webhook is registered: 
    curl -X GET \
  'https://api.twitter.com/1.1/account_activity/all/:env_name/webhooks.json' \
  -H 'Authorization: OAuth ...'
  2. Check webhook subscription: 
    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: 
    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
  • ✅ 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

Support

For issues with Twitter API integration:

Reference in New Issue View Git Blame Copy Permalink