24 KiB
Dịch Vụ MKT X/Twitter - Tài Liệu API
Mục Lục
- Tổng Quan API
- Xác Thực
- Quản Lý Tài Khoản
- Quản Lý Liên Hệ
- Quản Lý Hội Thoại
- Quản Lý Template
- Quản Lý Chiến Dịch
- Quản Lý Segment
- Automation Flows
- AI Chatbot
- Phân Tích
- Webhooks
- Xử Lý Lỗi
Tổng Quan API
Base URL
Development: http://localhost:5000/api/v1/mkt-x
Production: https://api.goodgo.com/api/v1/mkt-x
Versioning
API versioning được xử lý thông qua URL path (/api/v1/).
Định Dạng Request
Tất cả requests với body nên sử dụng:
Content-Type: application/json
Định Dạng Response
Tất cả responses tuân theo cấu trúc này:
Success Response
{
"success": true,
"data": { ... },
"pagination": {
"page": 1,
"limit": 20,
"total": 100,
"totalPages": 5
}
}
Error Response
{
"success": false,
"error": "Mô tả lỗi"
}
Xác Thực
JWT Bearer Token
Tất cả API endpoints (ngoại trừ webhooks) yêu cầu xác thực qua JWT bearer token.
Request Header
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Lấy Token
Tokens được lấy từ IAM service:
POST /api/v1/auth/login
Content-Type: application/json
{
"email": "user@example.com",
"password": "password"
}
Response
{
"success": true,
"data": {
"accessToken": "eyJhbGci...",
"refreshToken": "refresh...",
"expiresIn": 3600
}
}
Quản Lý Tài Khoản
Kết Nối Tài Khoản Twitter
Kết nối tài khoản Twitter sử dụng OAuth 1.0a credentials.
Endpoint
POST /accounts
Request Body
{
"oauthToken": "oauth_token_từ_twitter",
"oauthTokenSecret": "oauth_token_secret_từ_twitter"
}
Response 200 OK
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"merchantId": "merchant-uuid",
"twitterUserId": "123456789",
"username": "goodgo_shop",
"displayName": "GoodGo Official",
"status": "active",
"connectedAt": "2026-01-18T10:00:00Z"
}
}
Mã Lỗi
400- OAuth credentials không hợp lệ401- Unauthorized409- Tài khoản đã được kết nối
Danh Sách Tài Khoản Đã Kết Nối
Lấy tất cả tài khoản Twitter đã kết nối bởi merchant.
Endpoint
GET /accounts
Query Parameters
status(tùy chọn) - Lọc theo trạng thái:active,inactive,error
Response 200 OK
{
"success": true,
"data": [
{
"id": "uuid",
"merchantId": "uuid",
"twitterUserId": "123456789",
"username": "goodgo_shop",
"displayName": "GoodGo Official",
"status": "active",
"connectedAt": "2026-01-18T10:00:00Z"
}
]
}
Lấy Chi Tiết Tài Khoản
Lấy thông tin chi tiết về tài khoản Twitter cụ thể.
Endpoint
GET /accounts/{accountId}
Response 200 OK
{
"success": true,
"data": {
"id": "uuid",
"merchantId": "uuid",
"twitterUserId": "123456789",
"username": "goodgo_shop",
"displayName": "GoodGo Official",
"profileImageUrl": "https://pbs.twimg.com/profile_images/...",
"status": "active",
"webhookId": "webhook-id",
"connectedAt": "2026-01-18T10:00:00Z",
"statistics": {
"totalContacts": 1234,
"totalConversations": 567,
"messagesThisMonth": 890
}
}
}
Mã Lỗi
404- Không tìm thấy tài khoản
Ngắt Kết Nối Tài Khoản
Ngắt kết nối tài khoản Twitter và thu hồi OAuth tokens.
Endpoint
DELETE /accounts/{accountId}
Response 200 OK
{
"success": true,
"data": null
}
Cập Nhật Cài Đặt Tài Khoản
Cập nhật cài đặt cấu hình tài khoản.
Endpoint
PUT /accounts/{accountId}
Request Body
{
"autoReplyEnabled": true,
"businessHours": {
"enabled": true,
"timezone": "Asia/Ho_Chi_Minh",
"schedule": {
"monday": { "start": "09:00", "end": "18:00" },
"tuesday": { "start": "09:00", "end": "18:00" }
}
}
}
Response 200 OK
Quản Lý Liên Hệ
Danh Sách Liên Hệ
Lấy danh sách liên hệ có phân trang với filtering.
Endpoint
GET /contacts
Query Parameters
accountId(tùy chọn) - Lọc theo tài khoản Twittertags(tùy chọn) - Tags phân cách bằng dấu phẩy:vip,customersearch(tùy chọn) - Tìm kiếm trong username/display nameskip(tùy chọn, mặc định: 0) - Pagination offsettake(tùy chọn, mặc định: 20, tối đa: 100) - Items per page
Response 200 OK
{
"success": true,
"data": [
{
"id": "uuid",
"accountId": "uuid",
"twitterUserId": "987654321",
"username": "customer_john",
"displayName": "John Doe",
"profileImageUrl": "https://...",
"tags": ["vip", "customer"],
"attributes": {
"purchaseCount": 5,
"totalSpent": 1250000,
"lastPurchaseDate": "2026-01-15"
},
"conversationCount": 3,
"firstInteractionAt": "2025-12-01T10:00:00Z",
"lastInteractionAt": "2026-01-18T09:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1234,
"totalPages": 62
}
}
Lấy Chi Tiết Liên Hệ
Lấy thông tin chi tiết về liên hệ cụ thể.
Endpoint
GET /contacts/{contactId}
Response 200 OK
{
"success": true,
"data": {
"id": "uuid",
"accountId": "uuid",
"twitterUserId": "987654321",
"username": "customer_john",
"displayName": "John Doe",
"profileImageUrl": "https://...",
"tags": ["vip", "customer"],
"attributes": {
"purchaseCount": 5,
"totalSpent": 1250000,
"lastPurchaseDate": "2026-01-15",
"preferredLanguage": "vi"
},
"source": "inbound_message",
"conversationCount": 3,
"firstInteractionAt": "2025-12-01T10:00:00Z",
"lastInteractionAt": "2026-01-18T09:30:00Z",
"engagement": {
"messagesSent": 15,
"messagesReceived": 18,
"averageResponseTime": "5m 30s"
}
}
}
Cập Nhật Liên Hệ
Cập nhật thông tin liên hệ.
Endpoint
PUT /contacts/{contactId}
Request Body
{
"displayName": "John Doe (VIP)",
"attributes": {
"preferredLanguage": "vi",
"notes": "Khách hàng cao cấp"
}
}
Response 200 OK
Thêm Tags vào Liên Hệ
Thêm một hoặc nhiều tags vào liên hệ.
Endpoint
POST /contacts/{contactId}/tags
Request Body
{
"tags": ["vip", "premium"]
}
Response 200 OK
Xóa Tag khỏi Liên Hệ
Xóa tag cụ thể khỏi liên hệ.
Endpoint
DELETE /contacts/{contactId}/tags/{tagName}
Response 200 OK
Cập Nhật Thuộc Tính Liên Hệ
Cập nhật hàng loạt thuộc tính tùy chỉnh cho liên hệ.
Endpoint
PUT /contacts/{contactId}/attributes
Request Body
{
"attributes": {
"purchaseCount": 6,
"totalSpent": 1500000,
"lastPurchaseDate": "2026-01-18",
"membershipTier": "gold"
}
}
Response 200 OK
Lấy Hội Thoại của Liên Hệ
Lấy tất cả hội thoại cho liên hệ cụ thể.
Endpoint
GET /contacts/{contactId}/conversations
Query Parameters
status(tùy chọn) - Lọc theo trạng thái:open,closedskip(tùy chọn) - Pagination offsettake(tùy chọn) - Items per page
Response 200 OK
{
"success": true,
"data": [
{
"id": "uuid",
"contactId": "uuid",
"status": "open",
"messageCount": 5,
"startedAt": "2026-01-18T09:00:00Z",
"lastMessageAt": "2026-01-18T09:30:00Z"
}
]
}
Xóa Liên Hệ
Xóa liên hệ và tất cả dữ liệu liên quan (tuân thủ GDPR).
Endpoint
DELETE /contacts/{contactId}
Response 200 OK
Quản Lý Hội Thoại
Danh Sách Hội Thoại
Lấy danh sách hội thoại có phân trang.
Endpoint
GET /conversations
Query Parameters
accountId(tùy chọn) - Lọc theo tài khoảnstatus(tùy chọn) - Lọc theo trạng thái:open,closedassignedTo(tùy chọn) - Lọc theo user ID được gánskip(tùy chọn) - Pagination offsettake(tùy chọn) - Items per page
Response 200 OK
{
"success": true,
"data": [
{
"id": "uuid",
"contactId": "uuid",
"accountId": "uuid",
"status": "open",
"channel": "direct_message",
"assignedToUserId": "uuid",
"messageCount": 12,
"startedAt": "2026-01-18T09:00:00Z",
"lastMessageAt": "2026-01-18T10:15:00Z",
"contact": {
"username": "customer_john",
"displayName": "John Doe"
}
}
],
"pagination": { ... }
}
Lấy Hội Thoại với Tin Nhắn
Lấy chi tiết hội thoại bao gồm tất cả tin nhắn.
Endpoint
GET /conversations/{conversationId}
Query Parameters
includeMessages(tùy chọn, mặc định: true) - Bao gồm lịch sử tin nhắn
Response 200 OK
{
"success": true,
"data": {
"id": "uuid",
"contactId": "uuid",
"accountId": "uuid",
"status": "open",
"channel": "direct_message",
"assignedToUserId": "uuid",
"startedAt": "2026-01-18T09:00:00Z",
"messages": [
{
"id": "uuid",
"conversationId": "uuid",
"direction": "inbound",
"type": "text",
"content": "Xin chào, tôi có câu hỏi về đơn hàng",
"attachments": [],
"isFromBot": false,
"sentAt": "2026-01-18T09:00:00Z"
},
{
"id": "uuid",
"conversationId": "uuid",
"direction": "outbound",
"type": "text",
"content": "Chào bạn! Tôi rất vui được hỗ trợ. Mã đơn hàng của bạn là gì?",
"attachments": [],
"isFromBot": false,
"sentAt": "2026-01-18T09:02:00Z"
}
]
}
}
Gửi Tin Nhắn
Gửi tin nhắn trong hội thoại.
Endpoint
POST /conversations/{conversationId}/messages
Request Body
{
"content": "Đơn hàng #12345 của bạn đã được gửi đi!",
"type": "text",
"attachments": [
{
"type": "image",
"url": "https://example.com/tracking.png"
}
]
}
Response 200 OK
{
"success": true,
"data": {
"id": "uuid",
"conversationId": "uuid",
"twitterMessageId": "123456789",
"direction": "outbound",
"type": "text",
"content": "Đơn hàng #12345 của bạn đã được gửi đi!",
"sentAt": "2026-01-18T10:30:00Z"
}
}
Mã Lỗi
400- Nội dung tin nhắn vượt quá giới hạn Twitter (10,000 ký tự)429- Vượt quá rate limit
Đóng Hội Thoại
Đóng hội thoại đang hoạt động.
Endpoint
PUT /conversations/{conversationId}/close
Request Body (tùy chọn)
{
"reason": "resolved"
}
Response 200 OK
Gán Hội Thoại
Gán hội thoại cho user/agent cụ thể.
Endpoint
POST /conversations/{conversationId}/assign
Request Body
{
"userId": "user-uuid"
}
Response 200 OK
Quản Lý Template
Tạo Template
Tạo template tin nhắn mới.
Endpoint
POST /templates
Request Body
{
"name": "Tin Nhắn Chào Mừng",
"type": "text",
"content": "Chào {{name}}, chào mừng đến {{shop_name}}! Sử dụng mã {{discount_code}} để được giảm giá 10% cho đơn hàng đầu tiên.",
"variables": ["name", "shop_name", "discount_code"]
}
Response 200 OK
{
"success": true,
"data": {
"id": "uuid",
"merchantId": "uuid",
"name": "Tin Nhắn Chào Mừng",
"type": "text",
"content": "Chào {{name}}, chào mừng đến...",
"variables": ["name", "shop_name", "discount_code"],
"createdAt": "2026-01-18T10:00:00Z"
}
}
Danh Sách Templates
Lấy tất cả templates của merchant.
Endpoint
GET /templates
Query Parameters
type(tùy chọn) - Lọc theo loại:text,quick_reply,cardsearch(tùy chọn) - Tìm kiếm trong tên template
Response 200 OK
Lấy Template
Lấy chi tiết template.
Endpoint
GET /templates/{templateId}
Response 200 OK
Cập Nhật Template
Cập nhật template hiện có.
Endpoint
PUT /templates/{templateId}
Request Body
{
"name": "Tin Nhắn Chào Mừng Đã Cập Nhật",
"content": "Xin chào {{name}}!..."
}
Response 200 OK
Xóa Template
Xóa template.
Endpoint
DELETE /templates/{templateId}
Response 200 OK
Mã Lỗi
409- Template đang được sử dụng bởi chiến dịch đang hoạt động
Xem Trước Template
Xem trước template đã render với dữ liệu mẫu.
Endpoint
POST /templates/{templateId}/preview
Request Body
{
"variables": {
"name": "John",
"shop_name": "GoodGo Shop",
"discount_code": "WELCOME10"
}
}
Response 200 OK
{
"success": true,
"data": {
"rendered": "Chào John, chào mừng đến GoodGo Shop! Sử dụng mã WELCOME10 để được giảm giá 10% cho đơn hàng đầu tiên."
}
}
Quản Lý Chiến Dịch
Tạo Chiến Dịch
Tạo chiến dịch tin nhắn mới.
Endpoint
POST /campaigns
Request Body
{
"name": "Khuyến Mãi Tết 2026",
"templateId": "template-uuid",
"segmentIds": ["segment-uuid-1", "segment-uuid-2"],
"schedule": {
"startAt": "2026-01-25T09:00:00Z",
"endAt": "2026-01-31T23:59:59Z"
},
"variables": {
"discount_code": "TET2026"
}
}
Response 200 OK
{
"success": true,
"data": {
"id": "uuid",
"merchantId": "uuid",
"name": "Khuyến Mãi Tết 2026",
"status": "scheduled",
"targetContactCount": 1500,
"createdAt": "2026-01-18T10:00:00Z"
}
}
Danh Sách Chiến Dịch
Lấy tất cả chiến dịch.
Endpoint
GET /campaigns
Query Parameters
status(tùy chọn) - Lọc theo trạng thái:draft,scheduled,running,paused,completedskip(tùy chọn) - Pagination offsettake(tùy chọn) - Items per page
Response 200 OK
Lấy Chi Tiết Chiến Dịch
Endpoint
GET /campaigns/{campaignId}
Response 200 OK
{
"success": true,
"data": {
"id": "uuid",
"name": "Khuyến Mãi Tết 2026",
"status": "running",
"templateId": "uuid",
"segmentIds": ["uuid"],
"schedule": {
"startAt": "2026-01-25T09:00:00Z",
"endAt": "2026-01-31T23:59:59Z"
},
"metrics": {
"totalSent": 1200,
"delivered": 1180,
"opened": 850,
"clicked": 320,
"replied": 45,
"failed": 20
}
}
}
Bắt Đầu Chiến Dịch
Bắt đầu thực thi chiến dịch.
Endpoint
POST /campaigns/{campaignId}/start
Response 200 OK
Tạm Dừng Chiến Dịch
Tạm dừng chiến dịch đang chạy.
Endpoint
POST /campaigns/{campaignId}/pause
Response 200 OK
Tiếp Tục Chiến Dịch
Tiếp tục chiến dịch đã tạm dừng.
Endpoint
POST /campaigns/{campaignId}/resume
Response 200 OK
Lấy Số Liệu Chiến Dịch
Lấy số liệu chi tiết cho chiến dịch.
Endpoint
GET /campaigns/{campaignId}/metrics
Response 200 OK
{
"success": true,
"data": {
"totalSent": 1200,
"delivered": 1180,
"deliveryRate": 98.3,
"opened": 850,
"openRate": 72.0,
"clicked": 320,
"clickRate": 37.6,
"replied": 45,
"replyRate": 5.3,
"failed": 20,
"failureRate": 1.7
}
}
Quản Lý Segment
Tạo Segment
Tạo phân khúc khách hàng mới.
Endpoint
POST /segments
Request Body
{
"name": "Khách Hàng VIP",
"conditions": [
{
"field": "attributes.purchaseCount",
"operator": "gte",
"value": 5
},
{
"field": "tags",
"operator": "contains",
"value": "vip"
}
]
}
Response 200 OK
Danh Sách Segments
Endpoint
GET /segments
Response 200 OK
Đánh Giá Segment
Lấy số lượng liên hệ khớp với điều kiện segment.
Endpoint
POST /segments/{segmentId}/evaluate
Response 200 OK
{
"success": true,
"data": {
"segmentId": "uuid",
"contactCount": 345,
"sampleContacts": [
{
"id": "uuid",
"username": "customer_1",
"displayName": "Customer 1"
}
]
}
}
Automation Flows
Tạo Automation Flow
Tạo workflow tự động hóa.
Endpoint
POST /automation/flows
Request Body
{
"name": "Chào Mừng Khách Hàng Mới",
"trigger": {
"type": "contact_created",
"config": {}
},
"nodes": [
{
"type": "send_message",
"templateId": "welcome-template-uuid",
"delay": 0
},
{
"type": "wait",
"duration": 86400
},
{
"type": "send_message",
"templateId": "followup-template-uuid",
"delay": 0
}
]
}
Response 200 OK
Kích Hoạt Flow
Kích hoạt automation flow.
Endpoint
POST /automation/flows/{flowId}/activate
Response 200 OK
Hủy Kích Hoạt Flow
Hủy kích hoạt automation flow.
Endpoint
POST /automation/flows/{flowId}/deactivate
Response 200 OK
AI Chatbot
Gửi Tin Nhắn AI
Gửi tin nhắn và nhận phản hồi AI.
Endpoint
POST /ai/conversations/{conversationId}/message
Request Body
{
"message": "Tôi muốn kiểm tra đơn hàng của tôi"
}
Response 200 OK
{
"success": true,
"data": {
"message": "Dạ, tôi có thể giúp bạn kiểm tra đơn hàng. Vui lòng cho tôi biết mã đơn hàng của bạn.",
"intent": "check_order",
"confidence": 0.95,
"needsHumanEscalation": false
}
}
Cấu Hình AI Chatbot
Cập nhật cài đặt AI chatbot cho tài khoản.
Endpoint
PUT /ai/accounts/{accountId}/config
Request Body
{
"enabled": true,
"model": "gpt-4",
"systemPrompt": "Bạn là trợ lý ảo của GoodGo Shop...",
"temperature": 0.7,
"escalationThreshold": 0.6
}
Response 200 OK
Phân Tích
Tổng Quan Analytics
Lấy số liệu tổng quan cho merchant.
Endpoint
GET /analytics/overview
Query Parameters
startDate(bắt buộc) - Ngày bắt đầu (YYYY-MM-DD)endDate(bắt buộc) - Ngày kết thúc (YYYY-MM-DD)accountId(tùy chọn) - Lọc theo tài khoản
Response 200 OK
{
"success": true,
"data": {
"period": {
"startDate": "2026-01-01",
"endDate": "2026-01-18"
},
"summary": {
"totalContacts": 1234,
"newContacts": 145,
"totalConversations": 567,
"activeConversations": 89,
"messagesSent": 2340,
"messagesReceived": 1890,
"campaignsCompleted": 12,
"averageResponseTime": "3m 45s"
},
"trends": {
"contactsGrowth": 12.5,
"conversationsGrowth": 8.3,
"messagesGrowth": -2.1
}
}
}
Phân Tích Liên Hệ
Lấy thống kê về liên hệ.
Endpoint
GET /analytics/contacts
Response 200 OK
Phân Tích Hội Thoại
Lấy số liệu về hội thoại.
Endpoint
GET /analytics/conversations
Response 200 OK
Phân Tích Chiến Dịch
Lấy hiệu suất chiến dịch.
**Endpoint``` GET /analytics/campaigns
**Response** `200 OK`
---
## Webhooks
### Endpoint Webhook
Twitter sẽ gửi events đến:
POST /webhooks/twitter
### Xác Minh CRC
Twitter gửi challenge để xác minh webhook:
GET /webhooks/verify?crc_token=xxx
**Response** `200 OK`
```json
{
"response_token": "sha256=..."
}
Sự Kiện Webhook
Direct Message Event
{
"direct_message_events": [
{
"type": "message_create",
"id": "123456789",
"created_timestamp": "1642000000000",
"message_create": {
"sender_id": "987654321",
"message_data": {
"text": "Xin chào!"
}
}
}
]
}
Xử Lý Lỗi
Mã Lỗi HTTP
| Mã | Ý Nghĩa | Mô Tả |
|---|---|---|
400 |
Bad Request | Request không hợp lệ hoặc thiếu tham số |
401 |
Unauthorized | Token xác thực không hợp lệ hoặc thiếu |
403 |
Forbidden | Không có quyền truy cập tài nguyên |
404 |
Not Found | Không tìm thấy tài nguyên |
409 |
Conflict | Xung đột với trạng thái hiện tại |
422 |
Unprocessable Entity | Validation failed |
429 |
Too Many Requests | Vượt quá rate limit |
500 |
Internal Server Error | Lỗi server |
Error Response Structure
{
"success": false,
"error": "Mô tả lỗi",
"errorCode": "ERROR_CODE",
"details": {
"field": "fieldName",
"message": "Chi tiết lỗi"
}
}
Validation Errors
{
"success": false,
"error": "Validation failed",
"errorCode": "VALIDATION_ERROR",
"details": [
{
"field": "templateId",
"message": "Template ID là bắt buộc"
},
{
"field": "segmentIds",
"message": "Cần ít nhất một segment"
}
]
}
Rate Limiting
Service thực thi các giới hạn sau:
- API Calls: 100 requests/phút mỗi merchant
- Message Sending: 500 tin nhắn/24 giờ mỗi tài khoản Twitter
- Webhook Processing: 1000 events/phút
Rate Limit Headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642000000
Pagination
Tất cả list endpoints hỗ trợ pagination:
Query Parameters:
skip- Offset (mặc định: 0)take- Limit (mặc định: 20, tối đa: 100)
Response:
{
"pagination": {
"page": 1,
"limit": 20,
"total": 1234,
"totalPages": 62
}
}
Best Practices
1. Sử Dụng Pagination
Luôn sử dụng pagination cho list endpoints để tránh timeout.
2. Xử Lý Rate Limits
Implement exponential backoff khi nhận 429 errors.
3. Validate Input
Validate dữ liệu trước khi gửi để giảm lỗi validation.
4. Sử Dụng Webhooks
Sử dụng webhooks thay vì polling để nhận real-time updates.
5. Cache Responses
Cache responses khi phù hợp để giảm API calls.
Tài Nguyên Bổ Sung
Hỗ Trợ
Để được hỗ trợ về API:
- Email: api-support@goodgo.com
- Documentation Issues: Mở issue trên GitHub
- Emergency Support: support-priority@goodgo.com