> 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/xay-dung-va-tich-hop-tro-ly-ai/api-tich-hop/api-gui-tin-nhan.md).

# API Gửi tin nhắn

API này cho phép bạn gửi tin nhắn văn bản (và tùy chọn kèm theo tệp đính kèm) đến  KamiMind để nhận phản hồi từ Trợ lý AI đã được tạo.

🧩 **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.