# Support Chat Integration Guide (Admin Dashboard Frontend)

This guide is for the **admin dashboard frontend** to manage support conversations and reply to users.

## Base and Auth

- Base URL prefix: `/api/v1`
- Endpoints below require admin auth middleware (`Bearer <token>`).
- Admin auth checks `userType` includes `"admin"`.
- Standard response format:

```json
{
  "status": true,
  "message": "Support conversations fetched successfully",
  "data": []
}
```

Error format:

```json
{
  "status": false,
  "message": "Support conversation not found",
  "data": null
}
```

## Admin API Endpoints

### 1) List support conversations

- **Method:** `GET`
- **URL:** `/api/v1/admin/support-chats`
- **Purpose:** dashboard conversation list, sorted by `updatedAt desc`.

Each conversation includes populated:
- `participants` (`fullName`, `email`, `image`, `role`, `userType`, `is_active`)
- `supportRequestedBy`
- `lastMessage`
- support metadata (`conversationType`, `supportStatus`)

---

### 2) Get messages for one support conversation

- **Method:** `GET`
- **URL:** `/api/v1/admin/support-chats/:conversationId/messages`

Response `data`:

```json
{
  "conversation": {
    "_id": "68conv",
    "conversationType": "support",
    "supportStatus": "open",
    "participants": [{}, {}]
  },
  "messages": [
    {
      "_id": "msg1",
      "sender": { "_id": "userId", "fullName": "App User" },
      "receiver": { "_id": "adminId", "fullName": "Super Admin" },
      "content": "Need help",
      "attachments": [],
      "attachmentType": "none"
    }
  ]
}
```

---

### 3) Reply to user from admin

- **Method:** `POST`
- **URL:** `/api/v1/admin/support-chats/:conversationId/reply`
- **Content-Type:** `multipart/form-data`
- **Body fields:**
  - `content` (optional if attachment exists)
  - file attachments (optional)

Validation:
- Must provide `content` or at least one attachment.

Behavior:
- Saves `Message` with sender = admin, receiver = support user.
- Updates conversation `lastMessage`.
- Sets `supportStatus = "open"`.
- Emits socket event `newMessage` to user room.

---

### 4) Update support chat status

- **Method:** `PATCH`
- **URL:** `/api/v1/admin/support-chats/:conversationId/status`
- **Body JSON:**

```json
{
  "status": "resolved"
}
```

Allowed values:
- `open`
- `resolved`
- `closed`

## Socket setup (real-time for admin dashboard)

Admin should also connect socket with admin user id:

```js
const socket = io(SOCKET_URL, { query: { userId: adminUserId } });
```

Listen:

```js
socket.on("newMessage", (message) => {
  // update conversation preview + active thread
});
```

This receives user support messages in real-time because backend emits:
- user -> admin: `io.to(adminId).emit("newMessage", fullMessage)`
- admin -> user: `io.to(userId).emit("newMessage", fullMessage)`

## Suggested dashboard UX flow

1. Load list with `GET /admin/support-chats`.
2. Open one thread using `GET /admin/support-chats/:conversationId/messages`.
3. Keep socket connected to update list badges and active thread.
4. Reply via `POST /admin/support-chats/:conversationId/reply`.
5. Resolve/close thread via `PATCH /admin/support-chats/:conversationId/status`.

## Implementation notes

- Support conversations are filtered by `conversationType: "support"`.
- If you need unread badges, add counters in conversation or compute from messages + last read timestamp.
- Current backend returns `200` for success and uses a normalized `status/message/data` contract via `res.success`/`res.error`.