# Support Chat Integration Guide (App Frontend)

This guide is for the **user app frontend** (family/caretaker) to integrate support chat with admin.

## Base and Auth

- Base URL prefix: `/api/v1`
- All endpoints below require user auth middleware (`Bearer <token>`).
- Standard response shape from backend middleware:

```json
{
  "status": true,
  "message": "Support conversation fetched successfully",
  "data": {}
}
```

Error shape:

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

## Support conversation model notes

Support conversations are stored in `conversations` with:

- `conversationType`: `"support"`
- `supportStatus`: `"open" | "resolved" | "closed"`
- `supportRequestedBy`: user id who opened support
- `participants`: `[userId, adminId]`

## App API Endpoints

### 1) Get or create support chat

- **Method:** `GET`
- **URL:** `/api/v1/users/support/chat`
- **Purpose:** returns existing support conversation for current user, or creates one.

Success `data` example:

```json
{
  "_id": "68xxxx",
  "participants": [
    { "_id": "userId", "fullName": "User", "email": "user@mail.com" },
    { "_id": "adminId", "fullName": "Super Admin", "email": "superadmin@yopmail.com", "role": "superadmin" }
  ],
  "conversationType": "support",
  "supportStatus": "open",
  "supportRequestedBy": "userId",
  "lastMessage": null
}
```

Possible errors:
- `404`: `"Support admin is not available right now."`

---

### 2) Send support message

- **Method:** `POST`
- **URL:** `/api/v1/users/support/chat/send`
- **Content-Type:** `multipart/form-data` (supports text-only or attachments)
- **Body fields:**
  - `content` (optional if attachments exist)
  - file attachments (same uploader used by existing messenger endpoint)

Validation:
- At least one of `content` or file attachment must be present.

Success `data` is the created message:

```json
{
  "_id": "68xxxx",
  "conversation": "68conv",
  "sender": { "_id": "userId", "fullName": "User", "email": "user@mail.com" },
  "receiver": { "_id": "adminId", "fullName": "Super Admin", "email": "superadmin@yopmail.com" },
  "content": "I need help with booking payment",
  "attachments": [],
  "attachmentType": "none",
  "createdAt": "2026-04-22T..."
}
```

Possible errors:
- `400`: `"Please provide message content or attachments."`
- `404`: `"Support admin is not available right now."`

---

### 3) Get support messages

- **Method:** `GET`
- **URL:** `/api/v1/users/support/chat/:conversationId/messages`

Success `data`:

```json
{
  "conversation": {
    "_id": "68conv",
    "conversationType": "support",
    "supportStatus": "open"
  },
  "messages": [
    {
      "_id": "msg1",
      "sender": { "_id": "userId", "fullName": "User" },
      "receiver": { "_id": "adminId", "fullName": "Super Admin" },
      "content": "Hello support",
      "attachments": [],
      "attachmentType": "none",
      "createdAt": "2026-04-22T..."
    }
  ]
}
```

Possible errors:
- `404`: `"Support conversation not found"`

## Socket setup (real-time for app)

Socket server joins room by `userId` from handshake query.

Connect like:

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

Listen for incoming messages:

```js
socket.on("newMessage", (message) => {
  // append if message.conversation === activeConversationId
});
```

Useful existing optional events:
- `userTyping` (from `typing` / `stopTyping` events)

## Recommended app flow

1. On support screen open, call `GET /users/support/chat`.
2. Save `conversationId`.
3. Fetch message history using `GET /users/support/chat/:conversationId/messages`.
4. Connect socket with `userId`.
5. Send message via `POST /users/support/chat/send`.
6. Append optimistic bubble; confirm with API response and/or socket event.

## Notes

- Backend selects support admin by role (`superadmin`, `support`, `supportadmin`) and `userType` containing `admin`.
- No support-admin email env var is required.