# Gửi tin nhắn vào hội thoại

Gửi tin nhắn vào một hội thoại có sẵn.

API 4.1

Dùng endpoint này khi bạn đã có ID hội thoại. Để liên hệ khách hàng qua định danh kênh, hãy dùng [Gửi tin nhắn cho khách hàng](/developers/vi/api-reference/messages/send-to-user).

## Trước khi gửi

- Lấy [Bearer access token](/developers/vi/get-started/authentication).
- Tìm ID hội thoại, ví dụ từ [sự kiện webhook](/developers/vi/webhooks/payloads) hoặc [Lấy thông tin hội thoại](/developers/vi/api-reference/conversations/retrieve).
- Dùng một hội thoại thử nghiệm khi phát triển. Mỗi yêu cầu thành công đều gửi một tin nhắn thật.

## Body yêu cầu

Body là một sự kiện. Tin nhắn đặt trong `data.message`.

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `cid` (đường dẫn) | string | Hội thoại cần gửi tới. |
| `type` | string | Tùy chọn. Mặc định là `message_sent`. |
| `data.message.format` | string | `plaintext` hoặc `block`. Xem [Định dạng tin nhắn](/developers/vi/messages/formats). |
| `data.message.text` | string | Nội dung văn bản cho `plaintext`. |
| `data.message.block` | object | Cây block cho tin nhắn `block`. |
| `data.message.attachments` | array | Tùy chọn: tệp, nút bấm hoặc thẻ. Xem [Tệp đính kèm](/developers/vi/messages/attachments). |

Một tin nhắn văn bản thuần:

```json
{
  "type": "message_sent",
  "data": {
    "message": {
      "format": "plaintext",
      "text": "Hello! How can we help?"
    }
  }
}
```

## Trường do Subiz đặt

Bạn không cần gửi các trường này. Subiz đặt chúng cho mọi yêu cầu:

- `created`: thời điểm hiện tại, tính bằng mili giây Unix.
- `account_id`: tài khoản của access token.
- `data.message.conversation_id` và `data.conversation.id`: giá trị `cid` trong URL. Giá trị trong body sẽ bị thay thế.

## Phản hồi

Yêu cầu thành công trả HTTP `200` cùng sự kiện đã gửi dưới dạng JSON, không có lớp bọc thêm. Một số trường:

```json
{
  "id": "event_example",
  "account_id": "account_example",
  "type": "message_sent",
  "created": 1763107200000,
  "data": {
    "message": {
      "conversation_id": "conversation_example",
      "format": "plaintext",
      "text": "Hello! How can we help?"
    }
  }
}
```

Trường rỗng bị lược bỏ. Lưu `id` của sự kiện nếu bạn cần đối chiếu tin nhắn sau này trong [lịch sử tin nhắn](/developers/vi/api-reference/conversations/history) hoặc sự kiện webhook.

Phản hồi `200` nghĩa là Subiz đã nhận tin nhắn. Nó không xác nhận tin đã tới kênh bên ngoài như Facebook hoặc Zalo.

## Giới hạn

- Tin nhắn gửi bằng token của agent được tính vào hạn mức của agent đó: 5 tin mỗi giây, 60 tin mỗi phút và 5.000 tin mỗi ngày UTC. Xem [Giới hạn gửi tin nhắn](/developers/vi/get-started/usage-limits#giới-hạn-gửi-tin-nhắn).
- Kích thước văn bản, tệp đính kèm và trường bị giới hạn. Xem [Giới hạn tin nhắn](/developers/vi/get-started/usage-limits#giới-hạn-tin-nhắn).

## Lỗi và thử lại

Kiểm tra mã trạng thái HTTP trước khi đọc body. Yêu cầu có thể thất bại do JSON không hợp lệ, lỗi xác thực, người gửi bị chặn, giới hạn tốc độ (`429`) hoặc kiểm tra dữ liệu ở dịch vụ hội thoại. Xem [Xử lý lỗi](/developers/vi/get-started/errors).

Đừng thử lại mù quáng sau khi hết thời gian chờ. Tin nhắn có thể đã được gửi, và endpoint này không có khóa idempotency. Hãy kiểm tra lịch sử tin nhắn trước.

## Yêu cầu HTTP

Thay `YOUR_CID` bằng ID hội thoại và `YOUR_ACCESS_TOKEN` bằng token của bạn.

```http
POST https://api.subiz.com.vn/4.1/conversations/YOUR_CID/messages
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "type": "message_sent",
  "data": {
    "message": {
      "text": "Hello! How can we help?",
      "format": "plaintext"
    }
  }
}
```