> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Chat API — Dashboard

Source: [`modules/Chat/Routes/api.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Chat/Routes/api.php).

> **Verification:** HTTP methods, paths, route-level authentication and route comments are confirmed from source. Exact request and response schemas are **not verified** unless explicitly described. Do not treat illustrative placeholders as real API payloads.

Endpoints in this file: **12**.

## `GET /api/v1/admin/chats/conversations`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** chats.view
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/v1/admin/chats/conversations/{id}`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** chats.view
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/v1/admin/chats/conversations/{id}/messages`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** chats.view
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/v1/admin/chats/conversations/{id}/history`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** chats.view
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/v1/admin/chats/messages`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** chats.view
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/v1/admin/chats/conversations/{id}/export`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** chats.export
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `POST /api/v1/admin/chats/messages/{id}/hide`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** chats.moderate
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `POST /api/v1/admin/chats/messages/{id}/restore`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** chats.moderate
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `POST /api/v1/admin/chats/messages/{id}/review-flag`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** chats.moderate
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/v1/admin/chats/settings`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** settings.manage
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `PATCH /api/v1/admin/chats/settings`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** settings.manage
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/v1/admin/chats/settings/history`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** settings.manage
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.


---
## Verified implementation handoff — Dashboard Chat (source inspection, 2026-11-22)

All routes below use `auth:sanctum`. `/api/v1` is the versioned public prefix. Reading chat **content** is audited on each request; administrators cannot send messages. Labels such as `status_label`, `role_label`, `flag_kind_labels` are **locale maps** (e.g. `ar`, `en`), unlike Flutter's localized strings. Never show bank/identity data in chat views.

### Endpoints and permissions

| Method | Path (under `/api/v1`) | Permission | Verified request | Response |
|---|---|---|---|---|
| GET | `/admin/chats/conversations` | `chats.view` | `per_page` 1..100, `sort`, `filter[...]` | Paginated conversation rows + `summary.open`, `summary.flags_pending` |
| GET | `/admin/chats/conversations/{id}` | `chats.view` | `limit` 1..100 (default 50) | `{data: conversation + order, disputes, messages, messages_meta, can, history_endpoint, export_endpoint}` |
| GET | `/admin/chats/conversations/{id}/messages` | `chats.view` | `before` integer >=1 OR `after` integer >=0, `limit` 1..100 (default 50) | `{data: Message[], meta: cursors}` |
| GET | `/admin/chats/conversations/{id}/history` | `chats.view` | `event` enum, `per_page` 1..100 (default 25) | Paginated audit rows |
| GET | `/admin/chats/conversations/{id}/export` | `chats.export` | `format=csv|xlsx` (default csv) | **Binary file**, not JSON; rate 20/min |
| GET | `/admin/chats/messages` | `chats.view` | `per_page` 1..100, `sort`, `filter[...]` | Paginated moderation queue; content access audited |
| POST | `/admin/chats/messages/{id}/hide` | `chats.moderate` | `{reason: string}` required | `{data:{changed:boolean,message:Message}}` |
| POST | `/admin/chats/messages/{id}/restore` | `chats.moderate` | `{reason: string}` required | Same shape; repeated operation harmless |
| POST | `/admin/chats/messages/{id}/review-flag` | `chats.moderate` | `{note?:string|null}` | Same shape |
| GET | `/admin/chats/settings` | `settings.manage` | — | `{data: settings + limits}` |
| PATCH | `/admin/chats/settings` | `settings.manage` | Partial settings fields below | `{data: settings + limits}` |
| GET | `/admin/chats/settings/history` | `settings.manage` | `per_page` 1..100 (default 25) | Paginated audit rows |

`{id}` is numeric; missing conversation is a not-found business error. `before` and `after` cannot coexist. Pagination envelope: `{data:[...],links:{first,last,prev,next},meta:{current_page,from,last_page,per_page,to,total}}`. Admin audit rows: `{id,event,subject,subject_id,old_values,new_values,actor_id,actor:{id,name}|null,tags,at}`.

### Conversation list — filters and sorting

| Query key | Type / constraints | Meaning |
|---|---|---|
| `filter[order_ref]` | string max 20 | Partial order reference |
| `filter[buyer_id]`, `filter[seller_id]`, `filter[participant_id]` | integer >=1 | Participant lookup |
| `filter[status]` | `open` or `closed` | Conversation status |
| `filter[close_reason]` | `completed`, `cancelled`, `refunded`, `dispute_decided` | Closing reason |
| `filter[flagged]`, `filter[flags_pending]`, `filter[has_hidden]`, `filter[disputed]` | boolean | Moderation/dispute conditions |
| `filter[messages_min]`, `filter[messages_max]` | integer >=0 | Message count bounds |
| `filter[search]` | string max 100 | Order ref, participant names, item title, numeric id |
| `sort` | `opened_at`, `last_message_at`, `closed_at`, `messages_count`, `flagged_count`, `id` | Prefix `-` for descending; default `-opened_at` |

Date-range filters are implemented for `opened`, `closed`, `last_message` via shared `AdminList::dateRules`; inspect that helper for exact key names before building date controls.

### Conversation row / detail — exact response fields

| Field | Type | Notes |
|---|---|---|
| `id`, `order_ref` | integer, string | Conversation id / order reference |
| `buyer`, `seller` | `{id:int,name:string}` | No private banking fields |
| `item` | `{title:string,count:int,image_url:string|null}` | Signed image URL may expire |
| `status`, `status_label` | string, locale-map | `open` / `closed` |
| `close_reason`, `close_reason_label` | string/null, locale-map/null | Nullable |
| `opened_at`, `closed_at`, `last_message_at` | ISO date/null | Nullable timestamps |
| `messages_count`, `flagged_count` | integer | Counts |
| `hidden_count`, `flags_pending_count` | integer/null | Nullable if not loaded |
| `has_dispute`, `dispute_refs` | boolean, string[] | Dispute linkage |
| `links` | `{detail:string,order:string}` | API paths |
| Detail `order` | object/null | `ref,status,conversation_open,closed_at,items_count` |
| Detail `disputes` | array | `{ref,links:{dispute,order}}` |
| Detail `messages` | Message[] | Latest page, chronological |
| Detail `messages_meta` | object | `has_more_before,before_cursor,limit` |
| Detail `can` | `{moderate:boolean,export:boolean}` | Server permissions; drive buttons from these |

### Admin Message — exact response fields

| Field | Type | Notes |
|---|---|---|
| `id`, `conversation_id`, `seq` | integer | Stable message/cursor IDs |
| `kind` | string | `user` or `system` |
| `sender` | object/null | `{id,role,role_label,name}`; null for system |
| `text`, `original_text` | string/null | Original preserved for moderation |
| `system` | object/null | `{code,text:locale-map,params}` |
| `images` | array | `{reference,url}` |
| `flagged`, `hidden` | boolean | Independent states |
| `flag_kinds`, `flag_kind_labels` | string[], locale-map[] | Contact flags |
| `flag_reviewed_at`, `flag_reviewed_by`, `flag_reviewed_by_user` | timestamp/null, int/null, object/null | Review audit |
| `hidden_at`, `hidden_by`, `hidden_by_user`, `hidden_reason` | nullable | Hide audit |
| `sent_at` | ISO timestamp | Message time |
| `actions` | object | `{hide:boolean,restore:boolean,review_flag:boolean}`; server-authoritative |

`GET /admin/chats/messages` also adds `order_ref` and `conversation_status` to each message row. Filters: `conversation_id`, `order_ref`, `sender_id`, `kind=user|system`, `flagged`, `flag_status=pending|reviewed`, `contact_kind` (settings-defined), `hidden`, `has_images`, `search` (max 100), and sent-date range. Sort: `sent_at`, `id`, `seq`, default `-sent_at`.

### Moderation requests and settings

- Hide and restore both require `reason` string; its exact min/max are `Message::REASON_MIN` and `Message::REASON_MAX` (do not hardcode values without checking constants). Review-flag accepts nullable `note`, max `Message::REASON_MAX`.
- `PATCH /admin/chats/settings` accepts optional `images_max` integer 0..10; `message_max_length` integer 1..4000; `block_contact_info` boolean; `contact_info_action` `mask|reject`; `contact_info_kinds` nonempty array of distinct valid contact kinds; `send_rate_per_minute` integer 1..120; `reason` nullable string max 500. `data.limits` returns supported ranges/enums for controls. Changes apply to subsequent messages and are audited.
- History `event` accepts `viewed`, `exported`, `message_hidden`, `message_restored`, `flag_reviewed`.
- Export CSV/XLSX contains original and delivered text, images, flags, hidden metadata, participants and timestamps. Treat as sensitive evidence; downloading is audited.

### JSON example — moderation response (illustrative values, exact field structure)

```json
{
  "data": {
    "changed": true,
    "message": {
      "id": 42, "conversation_id": 7, "seq": 12, "kind": "user",
      "sender": {"id": 10, "role": "buyer", "role_label": {"en": "Buyer"}, "name": "Example"},
      "text": "Example", "original_text": "Example", "system": null,
      "images": [], "flagged": false, "flag_kinds": [], "flag_kind_labels": [],
      "flag_reviewed_at": null, "flag_reviewed_by": null, "flag_reviewed_by_user": null,
      "hidden": true, "hidden_at": "2026-11-22T12:00:00+00:00", "hidden_by": 1,
      "hidden_by_user": {"id": 1, "name": "Moderator"}, "hidden_reason": "Policy violation",
      "sent_at": "2026-11-22T11:00:00+00:00",
      "actions": {"hide": false, "restore": true, "review_flag": false}
    }
  }
}
```

### Implementation rules

1. Require the appropriate permission for each screen/action; `chats.view` does **not** grant `chats.export` or `chats.moderate`.
2. List conversations without loading message bodies; reading messages/detail/export is audit-logged on every access.
3. Honor `actions` on each message and `can` on detail; do not infer permissions from statuses.
4. Use `before_cursor` / `after_cursor` for chronological thread paging; avoid offset pagination for messages.
5. Use blob download handling for export and preserve the filename from response headers.

Sources: [routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Chat/Routes/api.php), [conversation admin controller](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Chat/Interfaces/Http/Controllers/Admin/ConversationAdminController.php), [message admin controller](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Chat/Interfaces/Http/Controllers/Admin/MessageAdminController.php), [settings controller](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Chat/Interfaces/Http/Controllers/Admin/ChatSettingsController.php), [admin presenter](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Chat/Interfaces/Http/Presenters/AdminViews.php).

**Verification:** static code review; no live API or integration tests were run.
