# Hướng Dẫn Thiết Lập Twitter API

## Mục Lục

1. [Yêu Cầu Trước Khi Bắt Đầu](#yêu-cầu-trước-khi-bắt-đầu)
2. [Tạo Tài Khoản Twitter Developer](#tạo-tài-khoản-twitter-developer)
3. [Tạo Twitter App](#tạo-twitter-app)
4. [Cấu Hình OAuth](#cấu-hình-oauth)
5. [Thiết Lập Account Activity API](#thiết-lập-account-activity-api)
6. [Cấu Hình Webhooks](#cấu-hình-webhooks)
7. [Kiểm Tra Tích Hợp](#kiểm-tra-tích-hợp)
8. [Xử Lý Sự Cố](#xử-lý-sự-cố)

---

## Yêu Cầu Trước Khi Bắt Đầu

Trước khi thiết lập tích hợp Twitter API, đảm bảo bạn có:

- ✅ Tài khoản Twitter (tốt nhất là tài khoản doanh nghiệp)
- ✅ MKT X Service đã triển khai và có thể truy cập qua HTTPS
- ✅ Chứng chỉ SSL hợp lệ cho webhook URL
- ✅ Quyền truy cập vào cấu hình server

---

## Tạo Tài Khoản Twitter Developer

### Bước 1: Đăng Ký Developer Access

1. Truy cập [Twitter Developer Portal](https://developer.twitter.com/)
2. Nhấp "Sign up" và đăng nhập bằng tài khoản Twitter
3. Điền form đăng ký:
   - **Loại tài khoản**: Chọn "Business" hoặc "Professional"
   - **Use case chính**: Marketing automation và customer service
   - **Bạn có chia sẻ nội dung Twitter cho chính phủ không?**: Không
4. Xem xét và chấp nhận Developer Agreement
5. Xác minh địa chỉ email

**Thời gian xử lý**: Thường ngay lập tức, nhưng có thể mất đến 24-48 giờ

### Bước 2: Tạo Project

1. Điều hướng đến [Developer Portal Dashboard](https://developer.twitter.com/en/portal/dashboard)
2. Nhấp "Create Project"
3. Điền thông tin project:
   - **Tên project**: "GoodGo Marketing"
   - **Use case**: Customer engagement
   - **Mô tả project**: "Twitter marketing automation for e-commerce"
4. Nhấp "Next" và "Create"

---

## Tạo Twitter App

### Bước 1: Tạo App Mới

1. Trong project của bạn, nhấp "+ Add App"
2. Chọn môi trường "Production"
3. Nhập tên app (vd: "GoodGo-MKT-X-Prod")
4. Lưu thông tin xác thực API:

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

**⚠️ Quan trọng**: Lưu trữ thông tin xác thực này an toàn. Chúng sẽ không hiển thị lại.

### Bước 2: Cấu Hình Quyền App

1. Vào cài đặt app
2. Điều hướng đến "User authentication settings"
3. Nhấp "Set up"
4. Cấu hình quyền:

```
Quyền app:
☑ Read
☑ Write  
☑ Direct Messages

Loại App:
☑ Web App, Automated App or Bot

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

5. Lưu thay đổi

---

## Cấu Hình OAuth

### Thiết Lập OAuth 1.0a

Twitter Direct Messages API yêu cầu xác thực OAuth 1.0a.

### Bước 1: Tạo Access Tokens

1. Trong cài đặt app, vào "Keys and tokens"
2. Dưới "Authentication Tokens", nhấp "Generate"
3. Lưu tokens:

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

### Bước 2: Thêm Thông Tin Xác Thực Vào Service

Cập nhật `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"
  }
}
```

**🔒 Bảo mật**: Sử dụng biến môi trường hoặc secrets manager cho 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"
```

---

## Thiết Lập Account Activity API

Account Activity API cho phép bạn nhận sự kiện Twitter thời gian thực qua webhooks.

### Bước 1: Đăng Ký Account Activity API Access

1. Truy cập trang [Account Activity API](https://developer.twitter.com/en/products/twitter-api/account-activity-api)
2. Yêu cầu quyền truy cập cho app của bạn
3. Chọn môi trường "Sandbox" cho phát triển (miễn phí)
4. Cho production, bạn cần tier "Enterprise" hoặc "Premium"

**Pricing**:
- **Sandbox**: Miễn phí (1 webhook, 15 subscriptions)
- **Premium**: Từ $149/tháng (5 webhooks, 500 subscriptions)
- **Enterprise**: Giá tùy chỉnh

### Bước 2: Đăng Ký Webhook URL

Đăng ký webhook URL của bạn với Twitter:

```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", ...' \
  -d 'url=https://your-domain.com/api/v1/mkt-x/webhooks/twitter'
```

**Hoặc sử dụng MKT X Service API**:

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

### Bước 3: Xác Minh CRC (Challenge-Response Check)

Twitter sẽ gửi GET request đến webhook URL với tham số `crc_token`. Service của bạn phải phản hồi:

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

Service tự động xử lý điều này qua endpoint `/webhooks/verify`.

---

## Cấu Hình Webhooks

### Sự Kiện Bạn Sẽ Nhận

**Direct Message Events**
```json
{
  "direct_message_events": [
    {
      "type": "message_create",
      "id": "123456789",
      "created_timestamp": "1642000000000",
      "message_create": {
        "sender_id": "987654321",
        "message_data": {
          "text": "Xin chào!"
        }
      }
    }
  ]
}
```

### Webhook Security

Tất cả webhook requests từ Twitter bao gồm:

1. **X-Twitter-Webhooks-Signature** header
2. HMAC-SHA256 signature của request body

Service tự động xác thực signature này.

---

## Kiểm Tra Tích Hợp

### Bước 1: Kiểm Tra Kết Nối OAuth

```bash
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"
  }'
```

**Phản hồi mong đợi**:
```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "twitterUserId": "123456789",
    "username": "your_username",
    "status": "active"
  }
}
```

### Bước 2: Kiểm Tra Webhook URL

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

### Bước 3: Gửi Test Direct Message

1. Gửi direct message đến tài khoản Twitter đã kết nối từ tài khoản khác
2. Kiểm tra service logs để xác nhận webhook event đã nhận
3. Xác minh conversation và message đã được tạo trong database

---

## Xử Lý Sự Cố

### Vấn Đề 1: Đăng Ký Webhook Thất Bại

**Lỗi**: `401 Unauthorized` khi đăng ký webhook

**Giải pháp**:
1. Xác minh thông tin xác thực OAuth đúng
2. Đảm bảo app có quyền "Read + Write + Direct Messages"
3. Kiểm tra webhook URL là HTTPS (không phải HTTP)
4. Xác nhận chứng chỉ SSL hợp lệ

### Vấn Đề 2: Không Nhận Webhook Events

**Triệu chứng**: Không có events trong logs sau khi gửi DM

**Giải pháp**:
1. Xác minh webhook đã đăng ký
2. Kiểm tra webhook subscription
3. Đảm bảo firewall cho phép traffic HTTPS đến
4. Kiểm tra service logs cho lỗi xác thực webhook

### Vấn Đề 3: Vượt Giới Hạn Tốc Độ

**Lỗi**: `429 Too Many Requests`

**Giải pháp**:
- Giới hạn Twitter DM: 500 tin nhắn / 24 giờ mỗi tài khoản
- Kiểm tra mức sử dụng hiện tại
- Triển khai hàng đợi tin nhắn để tuân thủ giới hạn

---

## Best Practices

### 1. Bảo Mật

- ✅ Lưu trữ thông tin xác thực API trong biến môi trường
- ✅ Sử dụng HTTPS cho tất cả webhook endpoints
- ✅ Xác thực webhook signatures
- ✅ Xoay vòng OAuth tokens định kỳ

### 2. Độ Tin Cậy

- ✅ Triển khai retry logic cho failed API calls
- ✅ Sử dụng message queues cho xử lý webhook
- ✅ Monitor webhook endpoint uptime
- ✅ Thiết lập alerting cho API errors

### 3. Hiệu Năng

- ✅ Xử lý webhooks bất đồng bộ
- ✅ Sử dụng caching cho user data
- ✅ Batch API requests khi có thể
- ✅ Monitor API quotas

---

## Giới Hạn Tốc Độ

### Twitter API v2 Limits

| Endpoint | Giới Hạn | Cửa Sổ |
|----------|-----------|---------|
| Direct Messages (Send) | 500 requests | 24 giờ |
| Direct Messages (Read) | 300 requests | 15 phút |
| User Lookup | 900 requests | 15 phút |

---

## Tài Nguyên Bổ Sung

- [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/)

---

## Hỗ Trợ

Để được hỗ trợ về tích hợp Twitter API:

- **Twitter Developer Forums**: https://twittercommunity.com/
- **Hỗ Trợ MKT X Service**: api-support@goodgo.com
