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

5. Contacts & CRM

5.1 List Contacts​

GET /api/v1/contacts

List contacts with advanced filtering.

Query Parameters:

  • page - Page number (default: 1)
  • limit - Items per page (default: 50)
  • search - Search by name, phone, email
  • source - Filter by source: zalo, facebook, manual, etc.
  • status - Filter by status (e.g., lead, customer, lost)
  • statusId - Filter by custom status ID
  • assignedUserId - Filter by assigned user
  • threadType - Filter by conversation type: user, group
  • hasZalo - Filter by Zalo connection: true, false, unknown
  • scoreMin / scoreMax - Filter by lead score range
  • dateFrom / dateTo - Filter by activity date range
  • sortBy - Sort field: lastActivity, createdAt, leadScore
  • direction - asc or desc

Response:

{
  "data": [
    {
      "id": "contact-001",
      "name": "Nguyen Van A",
      "email": "[email protected]",
      "phone": "+84.9.xxxx.xxxx",
      "source": "zalo",
      "status": "lead",
      "statusId": "status-001",
      "assignedUserId": "user-123",
      "avatar": "https://...",
      "leadScore": 85,
      "hasZalo": true,
      "friends": [
        {
          "zaloUid": "1234567890",
          "displayName": "Nguyen Van A",
          "accountId": "acc-001"
        }
      ],
      "notes": "Interested in premium plan",
      "tags": ["hot-lead", "vip"],
      "lastActivity": "2026-06-05T16:45:00Z",
      "createdAt": "2026-03-10T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 500,
    "page": 1,
    "limit": 50,
    "pages": 10
  }
}

5.2 Get Contact Details​

GET /api/v1/contacts/:id

Get full contact information.

Response:

{
  "id": "contact-001",
  "name": "Nguyen Van A",
  "email": "[email protected]",
  "phone": "+84.9.xxxx.xxxx",
  "source": "zalo",
  "status": "lead",
  "statusId": "status-001",
  "assignedUserId": "user-123",
  "avatar": "https://...",
  "leadScore": 85,
  "hasZalo": true,
  "friends": [
    {
      "zaloUid": "1234567890",
      "displayName": "Nguyen Van A",
      "accountId": "acc-001"
    }
  ],
  "conversations": [
    {
      "id": "conv-001",
      "zaloAccountId": "acc-001",
      "messageCount": 45,
      "lastMessageAt": "2026-06-05T16:45:00Z"
    }
  ],
  "notes": [
    {
      "id": "note-001",
      "content": "Interested in premium plan",
      "createdBy": "user-123",
      "createdAt": "2026-06-01T10:00:00Z"
    }
  ],
  "tags": ["hot-lead", "vip"],
  "appointments": [
    {
      "id": "apt-001",
      "title": "Demo Call",
      "scheduledAt": "2026-06-10T14:00:00Z",
      "status": "scheduled"
    }
  ],
  "activities": [
    {
      "type": "message_received",
      "timestamp": "2026-06-05T16:45:00Z",
      "data": "Customer sent message"
    }
  ],
  "createdAt": "2026-03-10T08:00:00Z",
  "updatedAt": "2026-06-05T17:35:00Z"
}

5.3 Create Contact​

POST /api/v1/contacts

Create new contact.

Request Body:

{
  "name": "Tran Thi B",
  "email": "[email protected]",
  "phone": "+84.9.yyyy.yyyy",
  "source": "facebook",
  "status": "lead",
  "statusId": "status-001",
  "assignedUserId": "user-123",
  "notes": "Referred by existing customer",
  "tags": ["referral"]
}

Response: 201

{
  "id": "contact-002",
  "name": "Tran Thi B",
  "email": "[email protected]",
  "phone": "+84.9.yyyy.yyyy",
  "source": "facebook",
  "status": "lead",
  "createdAt": "2026-06-05T17:35:00Z"
}

5.4 Update Contact​

PUT /api/v1/contacts/:id

Update contact information.

Request Body:

{
  "name": "Tran Thi B",
  "email": "[email protected]",
  "status": "customer",
  "assignedUserId": "user-124",
  "tags": ["vip", "referral"]
}

Response: 200

{
  "id": "contact-002",
  "name": "Tran Thi B",
  "email": "[email protected]",
  "status": "customer",
  "updatedAt": "2026-06-05T17:40:00Z"
}

5.5 Delete Contact​

DELETE /api/v1/contacts/:id

Delete contact.

Response: 204 No Content

5.6 Get Contact Friends​

GET /api/v1/contacts/:id/friends

Get Zalo friend connections for contact.

Response:

[
  {
    "id": "friend-001",
    "zaloUid": "1234567890",
    "displayName": "Nguyen Van A",
    "accountId": "acc-001",
    "relationshipKind": "friend",
    "addedAt": "2026-03-10T08:00:00Z"
  }
]

5.7 Create Appointment​

POST /api/v1/appointments

Schedule appointment with contact.

Request Body:

{
  "contactId": "contact-001",
  "title": "Product Demo",
  "description": "Show premium features",
  "scheduledAt": "2026-06-10T14:00:00Z",
  "duration": 60,
  "type": "meeting",
  "location": "Video Call",
  "assignedUserId": "user-123"
}

Response: 201

{
  "id": "apt-001",
  "contactId": "contact-001",
  "title": "Product Demo",
  "scheduledAt": "2026-06-10T14:00:00Z",
  "status": "scheduled",
  "createdAt": "2026-06-05T17:35:00Z"
}

5.8 List Appointments​

GET /api/v1/appointments

List all appointments.

Query Parameters:

  • page - Page number
  • limit - Items per page
  • status - Filter: scheduled, completed, cancelled
  • contactId - Filter by contact
  • dateFrom / dateTo - Date range

Response:

{
  "data": [
    {
      "id": "apt-001",
      "contactId": "contact-001",
      "contactName": "Nguyen Van A",
      "title": "Product Demo",
      "scheduledAt": "2026-06-10T14:00:00Z",
      "status": "scheduled",
      "createdAt": "2026-06-05T17:35:00Z"
    }
  ],
  "pagination": { "total": 25, "page": 1, "limit": 50 }
}

5.9 Add Note to Contact​

POST /api/v1/contacts/:id/notes

Add note/comment to contact.

Request Body:

{
  "content": "Customer interested in annual plan. Follow up next week."
}

Response: 201

{
  "id": "note-002",
  "contactId": "contact-001",
  "content": "Customer interested in annual plan...",
  "createdBy": "user-123",
  "createdAt": "2026-06-05T17:35:00Z"
}