FB Messenger API#

API nhắn tin Facebook Messenger với E2EE (End-to-End Encryption). Hỗ trợ gửi/nhận tin nhắn text, ảnh, file, reaction, quản lý accounts qua GoLogin profiles.

Base URL: https://fbmessenger.socialking.vn/api/v1

Authentication: Tất cả API yêu cầu header X-API-Key

X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tổng Quan#

1. Security Architecture#

15 Layers Bảo Mật#

Request Signing (Optional)#

Bảo vệ chống MITM + replay attack. Client tạo signature:

timestamp = unix seconds
payload = timestamp + "." + METHOD + "." + path + "." + body
signature = HMAC-SHA256(payload, api_key)

Headers:

X-API-Key: sk_xxxxx
X-Signature: t=1774921613,v1=abc123def456...

Không bắt buộc — backward compatible. Khi không gửi X-Signature → skip verification.

Idempotency Key#

Chống duplicate request. Gửi cùng Idempotency-Key → server trả cached response, không xử lý lại.

POST /e2ee/accounts/:id/send
Idempotency-Key: unique-request-id-123

Multi-Tenant#

-- Admin key: access tất cả accounts
INSERT INTO fb_api_key (name, key_hash, scopes, allowed_accounts)
VALUES ('Admin', '...', '{admin:*}', NULL);

-- Tenant key: chỉ access accounts được chỉ định
INSERT INTO fb_api_key (name, key_hash, scopes, allowed_accounts, allowed_ips)
VALUES ('Dự án A', '...', '{messages:send,accounts:read}',
        '{uuid-1, uuid-2}', '103.82.21.45');

2. Health Check#

GET /health#

Không cần API Key.

{
  "status": "ok",
  "ws_clients": {
    "accounts_subscribed": 2,
    "total_clients": 5
  }
}

3. E2EE Account Management#

POST /e2ee/accounts/connect#

Kết nối Facebook account qua GoLogin profile. Tự động: lấy cookies + proxy + fingerprint → register E2EE → connect MQTT + E2EE WebSocket.

**Thời gian:** 15-30 giây (E2EE handshake)

// Request
{"gologin_id": "697322c4156a30fda9d1d11d"}

// Response 201
{
  "success": true,
  "data": {
    "account_id": "a2566272-9062-4726-8315-dee16b74ff99",
    "fb_uid": "61559330365827",
    "status": "connected",
    "e2ee": true
  }
}

GET /e2ee/accounts/:id/status#

Hỗ trợ cả UUID và FB UID.

{
  "connected": true, "mqtt": true, "e2ee": true,
  "status": "active",
  "fb_uid": "61559330365827",
  "last_activity": "2026-03-31T01:46:53Z",
  "reconnect_count": 0
}

GET /e2ee/accounts/:id/precheck?recipient_uid=xxx#

Kiểm tra 7 điều kiện trước khi gửi:

{
  "ok": true,
  "details": {
    "account_exists": true,
    "account_active": true,
    "e2ee_connected": true,
    "mqtt_connected": true,
    "proxy_alive": true,
    "rate_limit_ok": true,
    "not_emergency": true
  }
}

DELETE /e2ee/accounts/:id#

Ngắt kết nối E2EE.

4. Messaging#

POST /e2ee/accounts/:id/send#

Gửi tin nhắn text E2EE. Tự động Human Behavior Sequence:

1. Mở thread (mark as read) — 0.5-1.5s
2. Đọc tin nhắn cũ — 1-5s
3. Typing indicator ON
4. Giả lập gõ — tỉ lệ với độ dài (50-80ms/char)
5. Typing indicator OFF
6. Pause — 200-800ms
7. Gửi (E2EE encrypted)
8. Nhìn tin đã gửi — 1-3s

**Response time:** 5-20 giây (bao gồm human delay)

// Request
{"recipient_uid": "100008732229767", "text": "xin chào"}

// Response 201
{"message_id": "7444560668238152496", "status": "sent", "e2ee": true}

POST /e2ee/accounts/:id/send-image#

Gửi ảnh inline (hiển thị trong chat). Upload file.

Content-Type: multipart/form-data
Fields:
  recipient_uid: "100008732229767"
  caption: "Ảnh đẹp" (optional)
  file: <binary image data>

// Response 201
{"message_id": "...", "status": "sent", "type": "image"}

POST /e2ee/accounts/:id/send-image-url#

Gửi ảnh inline từ URL (MinIO, CDN…).

// Request
{
  "recipient_uid": "100008732229767",
  "image_url": "https://s3.socialking.vn/messages/.../photo.jpg",
  "caption": "Ảnh từ MinIO"
}

POST /e2ee/accounts/:id/send-file#

Gửi file (PDF, DOC, ZIP…).

Content-Type: multipart/form-data
Fields:
  recipient_uid: "100008732229767"
  file: <binary file data>

POST /e2ee/accounts/:id/react#

React emoji.

{"recipient_uid": "100008732229767", "message_id": "744...", "emoji": "❤️"}

Errors#

5. Threads & Messages#

GET /accounts/:id/threads#

?folder=inbox&search=Nguyễn&limit=20&offset=0

GET /accounts/:id/threads/:threadKey/messages#

?limit=30&before_ms=1774890266000

Trả về cả tin gửi (is_from_me: true) và tin nhận (is_from_me: false).

POST /accounts/:id/threads/:threadKey/read#

Đánh dấu đã đọc.

6. Connection Lifecycle & Realtime#

Luồng hoạt động#

┌─────────────────────────────────────────────────────┐
│  SOCIALKING BE                                      │
│                                                     │
│  User mở trang messaging                            │
│    → WebSocket connect tới fb_messenger             │
│    → fb_messenger: GIỮ E2EE connection              │
│                                                     │
│  User gửi tin nhắn                                  │
│    → POST /e2ee/accounts/:id/send                   │
│    → fb_messenger: auto-connect nếu chưa → gửi     │
│                                                     │
│  User nhận tin nhắn                                  │
│    → fb_messenger push qua WebSocket → hiển thị     │
│                                                     │
│  User rời trang messaging                           │
│    → WebSocket đóng                                 │
│    → 15 phút không có request → TỰ DISCONNECT      │
│                                                     │
│  User quay lại                                      │
│    → WebSocket reconnect → auto-connect lại         │
└─────────────────────────────────────────────────────┘

Lazy Connection#

fb_messenger KHÔNG tự connect khi khởi động. Account chỉ connect khi:

• BE gọi /send (auto-connect trước khi gửi)
• BE connect WebSocket subscribe account

Account tự disconnect khi:

• Không có WebSocket subscriber + 15 phút không có API call
• Facebook kick session (checkpoint/ban)
• Gọi DELETE /e2ee/accounts/:id

**SOCIALKING BE không cần quản lý connect/disconnect.** Chỉ cần gọi `/send` — fb_messenger tự xử lý.

WebSocket#

WS wss://fbmessenger.socialking.vn/ws

Auth (first message, 5s timeout):

{"action": "auth", "api_key": "sk_xxx", "account_id": "61559330365827"}

Server response:

{"type": "auth.success", "account_id": "61559330365827"}

Server push events (tự động):

{"type": "message", "account_id": "...", "data": {"text": "hello", "is_from_me": false, ...}}

Connection lifecycle:

• WebSocket sống → fb_messenger giữ E2EE connection (account online)
• WebSocket đóng → fb_messenger đếm idle → disconnect sau 15 phút (account offline)
• WebSocket reconnect → fb_messenger auto-connect lại

Webhook (HMAC-SHA256 signed)#

Đăng ký webhook trong fb_api_key:

UPDATE fb_api_key SET
  webhook_url = 'https://your-system.com/webhook',
  webhook_secret = 'your-secret',
  webhook_events = '{message.received,message.sent,account.checkpoint}'
WHERE id = '...';

Request tới webhook URL:

POST https://your-system.com/webhook
X-Webhook-Signature: t=1774919744,v1=hmac_hex...
X-Webhook-Event: message.received

{
  "event": "message.received",
  "timestamp": 1774919744,
  "account_id": "uuid",
  "fb_uid": "61559330365827",
  "data": {"message_id": "...", "text": "hello", "sender_uid": 100008732229767}
}

Verify signature (Go):

import "github.com/socialking/fb-messenger/internal/service"
ok := service.VerifyWebhookSignature(payload, signatureHeader, "your-secret")

Events:

Đấu nối hệ thống khác#

┌──────────────┐     WebSocket      ┌──────────────────┐
│ SOCIALKING   │◄──────────────────►│                  │
│ BE / FE      │     REST API       │  fb_messenger    │
│              │◄──────────────────►│  service         │
└──────────────┘                    │                  │
                                    │  Port: 8090      │
┌──────────────┐     Webhook        │                  │
│ Hệ thống     │◄───────────────────│                  │
│ khác         │     (HMAC signed)  │                  │
└──────────────┘                    └──────────────────┘

Mỗi hệ thống nhận API Key riêng với:

• allowed_accounts — chỉ access accounts được phép
• allowed_ips — chỉ từ IP được phép
• scopes — phân quyền (read/send/admin)
• webhook_url — push events riêng

7. Rate Limits#

API Rate Limits#

Message Rate Limits — Bạn Bè#

Message Rate Limits — Người Lạ (Non-Friends)#

Gửi cho người lạ rủi ro **gấp 5-10 lần** bạn bè. Facebook đặc biệt theo dõi tin nhắn tới non-friends.

Adaptive Rate (Auto-adjust)#

Rate limit tự động giảm khi account health score thấp:

Health check tự động chạy mỗi 5 phút.

Warm Up (account mới)#

Response Headers#

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1774890400

8. Content Safety#

Hệ thống tự động kiểm tra nội dung trước khi gửi:

Auto-Block (không cho gửi)#

Auto-Warning (vẫn cho gửi, log cảnh báo)#

Khi Bị Block/Chặn#

9. Account Safety#

Human Behavior Simulation#

Mỗi tin nhắn đều qua Pre-Send Sequence giả lập người thật:

1. Mở thread (mark as read) ——— 0.5-1.5s
2. Đọc tin nhắn cũ ——————————— 1-5s
3. Typing indicator ON
4. Giả lập gõ ————————————————— 50-80ms/char + pause giữa từ
5. Typing indicator OFF
6. Pause trước Enter ——————————— 200-800ms
7. GỬI (E2EE encrypted)
8. Nhìn tin đã gửi ———————————— 1-3s

Tất cả delay dùng Gaussian distribution (không đều, giống người thật).

Pre-Check (7 checks trước mỗi tin)#

✓ Emergency stopped?
✓ Account exists + active?
✓ E2EE connected?
✓ MQTT connected?
✓ Proxy alive? (TCP ping)
✓ Rate limit OK?
✓ Content safety OK?

Bảng tổng hợp#

9. Docker Deployment#

docker pull ghcr.io/daominhngoc2003/fbmessenger-socialking-vn:latest
docker-compose up -d

Container: fbmessenger-socialking-vn Port: 8090 Network: npm_network

Environment Variables#

10. Database#

78+ tables trên PostgreSQL, partitioned cho scale tỉ records:

Views: v_account_health, v_system_overview

11. Scale Architecture#

                    Load Balancer (Nginx)
                         │
         ┌───────────────┼───────────────┐
         │               │               │
    Worker 1        Worker 2        Worker N
    (500 acc)       (500 acc)       (500 acc)
         │               │               │
         └───────────────┼───────────────┘
                         │
              ┌──────────┼──────────┐
              │          │          │
          PostgreSQL   Valkey    MinIO

• Max 500 accounts per worker
• Staggered connection (2-5s delay per account)
• Shared device store (1 DB pool)
• Auto-reconnect on restart