# Send to a conversation

Send a message into an existing conversation.

API 4.1

Use this endpoint when you already have a conversation ID. To contact a customer through a channel identity instead, use [Send to a customer](/developers/api-reference/messages/send-to-user).

## Before you send

- Get a [Bearer access token](/developers/get-started/authentication).
- Find the conversation ID, for example from a [webhook event](/developers/webhooks/payloads) or [Get conversation details](/developers/api-reference/conversations/retrieve).
- Use a test conversation while developing. Each successful request sends a real message.

## Request body

The body is an event. The message goes in `data.message`.

| Field | Type | Description |
| --- | --- | --- |
| `cid` (path) | string | Conversation to send to. |
| `type` | string | Optional. Defaults to `message_sent`. |
| `data.message.format` | string | `plaintext` or `block`. See [Message formats](/developers/messages/formats). |
| `data.message.text` | string | Message text for `plaintext`. |
| `data.message.block` | object | Block tree for `block` messages. |
| `data.message.attachments` | array | Optional files, buttons, or cards. See [Attachments](/developers/messages/attachments). |

A plain-text message:

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

## Fields Subiz sets

You do not need to send these fields. Subiz sets them for every request:

- `created`: the current time, in Unix milliseconds.
- `account_id`: the account of your access token.
- `data.message.conversation_id` and `data.conversation.id`: the `cid` from the URL. Values in the body are replaced.

## Response

A successful request returns HTTP `200` with the sent event as JSON, without an extra wrapper. Selected fields:

```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?"
    }
  }
}
```

Empty fields are omitted. Store the event `id` if you need to match the message later in [message history](/developers/api-reference/conversations/history) or webhook events.

A `200` response means Subiz accepted the message. It does not confirm delivery to an external channel such as Facebook or Zalo.

## Limits

- Message sends made with an agent's token count toward that agent's allowance: 5 per second, 60 per minute, and 5,000 per UTC day. See [Message sending limits](/developers/get-started/usage-limits#message-sending-limits).
- Text, attachment, and field sizes are limited. See [Message limits](/developers/get-started/usage-limits#message-limits).

## Errors and retries

Check the HTTP status before reading the body. Requests can fail because of invalid JSON, authentication, a blocked sender, rate limits (`429`), or validation in the conversation service. See [Errors](/developers/get-started/errors).

Do not retry blindly after a timeout. The message may already have been sent, and this endpoint has no idempotency key. Check message history first.

## HTTP request

Replace `YOUR_CID` with the conversation ID and `YOUR_ACCESS_TOKEN` with your token.

```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"
    }
  }
}
```