Chuyển tới nội dung chính

3. Zalo Account Management

3.1 List Zalo Accounts​

GET /api/v1/zalo-accounts

List all connected Zalo accounts with live status.

Query Parameters:

  • status - Filter by status: qr_pending, connected, disconnected
  • assignedTo - Filter by account owner user ID
  • search - Search by display name or phone

Response:

[
  {
    "id": "acc-001",
    "zaloUid": "1234567890",
    "displayName": "Zalo Official",
    "avatarUrl": "https://...",
    "phone": "+84.9.xxxx.xxxx",
    "status": "connected",
    "liveStatus": {
      "state": "connected",
      "connectedAt": "2026-06-05T10:00:00Z",
      "lastHeartbeat": "2026-06-05T17:30:00Z"
    },
    "ownerUserId": "user-123",
    "owner": {
      "id": "user-123",
      "fullName": "John Doe",
      "email": "[email protected]"
    },
    "hasProxy": false,
    "lastConnectedAt": "2026-06-05T10:00:00Z",
    "createdAt": "2026-01-15T10:30:00Z"
  }
]

3.2 Create Zalo Account​

POST /api/v1/zalo-accounts

Create new account record (before QR login).

Request Body:

{
  "displayName": "My Business Account",
  "proxyUrl": null
}

Response: 201

{
  "id": "acc-002",
  "displayName": "My Business Account",
  "status": "qr_pending",
  "createdAt": "2026-06-05T17:30:00Z"
}

3.3 Initiate QR Login​

POST /api/v1/zalo-accounts/:id/login

Start QR code login process. QR delivered via Socket.IO.

Socket Room: account:{id}

Response:

{
  "message": "QR login initiated — subscribe to account:acc-001 socket room"
}

3.4 Force Reconnect​

POST /api/v1/zalo-accounts/:id/reconnect

Reconnect using saved session data.

Response:

{
  "message": "Reconnect initiated"
}

3.5 Delete/Archive Account​

DELETE /api/v1/zalo-accounts/:id

Archive account (soft delete). Use ?purge=true to clear session data.

Query Parameters:

  • purge - Boolean. If true, wipes sessionData and zaloUid for fresh reconnect

Response: 204 No Content

3.6 Get Account Status​

GET /api/v1/zalo-accounts/:id/status

Get real-time status of specific account.

Response:

{
  "accountId": "acc-001",
  "liveStatus": {
    "state": "connected",
    "connectedAt": "2026-06-05T10:00:00Z",
    "lastHeartbeat": "2026-06-05T17:30:00Z"
  }
}

3.7 Update Proxy​

PUT /api/v1/zalo-accounts/:id/proxy

Update proxy configuration for account.

Request Body:

{
  "proxyUrl": "http://user:[email protected]:8080"
}

Response:

{
  "message": "Proxy updated",
  "hasProxy": true
}