> For the complete documentation index, see [llms.txt](https://book.kamimind.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.kamimind.ai/api-tich-hop/api-gui-tin-nhan.md).

# API Gửi tin nhắn

🧩 **Endpoint**

```
POST https://api.dev.kamimind.ai/public/v1/response
```

#### 🧾 Cú pháp `curl` mẫu

```
curl --location 'https://api.dev.kamimind.ai/public/v1/response' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer ***********************' \
  --form 'story_id=""' \
  --form 'bot_token="b4732227-583f-4982-85d4-e4f731d1b64b"' \
  --form 'streaming="false"' \
  --form 'message="Xin chào"' \
  --form 'files=@"/home/Downloads/file_example.png"'
```

#### 🔐 Thông tin xác thực

Truy cập API yêu cầu **mã Bearer Token** hợp lệ.

* Tham số: `Authorization: Bearer <token>`
* Token được cấp bởi hệ thống KamiMind cho từng Trợ lý AI

#### 📤 Tham số gửi đi (Form Data)

| Tên trường  | Bắt buộc | Kiểu dữ liệu                        | Mô tả                                                                                                                                                              |
| ----------- | -------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `story_id`  | Không    | `string`                            | ID của hội thoại. Để trống ("") nếu muốn bắt đầu hội thoại mới. Nếu muốn tiếp tục hội thoại trước đó, truyền lại story\_id đã nhận được từ phản hồi trước.         |
| `bot_token` | Có       | `string`                            | Mã định danh của Trợ lý AI mà bạn muốn gọi.                                                                                                                        |
| `streaming` | Không    | `boolean` (`"true"` hoặc `"false"`) | Nếu bật `"true"`, phản hồi sẽ được gửi dạng luồng (stream) thay vì toàn bộ cùng lúc.                                                                               |
| `message`   | Có       | `string`                            | Nội dung tin nhắn bạn muốn gửi đến Trợ lý AI.                                                                                                                      |
| `files`     | Không    | `file`                              | Tệp đính kèm (hình ảnh, tài liệu, v.v.) để Trợ lý AI có thể xử lý hoặc tham chiếu. Có thể gửi nhiều tệp bằng cách thêm nhiều trường `--form 'files=@<đường_dẫn>'`. |

#### 📥 Phản hồi mẫu (Response)

```json
{
  "success": true,
  "message": "Chat successfully",
  "data": {
    "message": "Xin chào! Tôi có thể giúp gì cho bạn hôm nay?",
    "story_id": "c3f2d8a1-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}
```

| Trường          | Mô tả                                                           |
| --------------- | --------------------------------------------------------------- |
| `success`       | Trạng thái xử lý yêu cầu (`true` hoặc `false`).                 |
| `data.`message  | Câu trả lời do Trợ lý AI sinh ra.                               |
| `data.story_id` | ID của hội thoại. Dùng để tiếp tục hội thoại ở các lần gọi sau. |

#### 🔁 Cách duy trì hội thoại (`story_id`)

* Khi bạn **gọi API lần đầu**, hãy để trống `story_id`.\
  API sẽ tự động **tạo một `story_id` mới** trong phản hồi.
* Từ **lần gọi tiếp theo**, bạn **phải truyền lại giá trị `story_id` đó** để Trợ lý AI hiểu ngữ cảnh trước đó, giúp phản hồi mạch lạc và liên tục.

📘 **Ví dụ:**

1. Lần 1:

   ```bash
   --form 'story_id=""'
   ```

   👉 Nhận phản hồi chứa `story_id`: `"c3f2d8a1-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`
2. Lần 2:

   ```bash
   --form 'story_id="c3f2d8a1-xxxx-xxxx-xxxx-xxxxxxxxxxxx"'
   ```

   👉 Trợ lý AI hiểu đây là phần tiếp nối hội thoại trước.