# Send Message

Sends a message to a thread and triggers an agent response.

> **Note:**
>
> This endpoint queues the message and returns immediately. To receive the agent's response in real-time, use the [WebSocket stream](/docs/api-reference/websocket/stream).

> **Note:**
>
> A message sent while the thread is running joins that run. The run adds it to the conversation before its next model request, after the results of the step in progress, and takes no extra turn for it. Several messages sent during a run reach the model in the order they were sent. A message sent to an idle thread starts a run.

- threadId (string), required

  The unique thread identifier (UUID)

* role (string), required

  Message role: `"user"`, `"system"`, or `"assistant"`

- content (string)

  Message text. Provide non-whitespace content or at least one attachment.

* attachments (array)

  Array of file attachments. Each attachment object:

  - `name` (string, required): Filename
  - `mimeType` (string, required): MIME type (e.g., `image/jpeg`)
  - `data` (string, required): Base64-encoded file data
  - `width` (number): Image width in pixels (optional, returned in response)
  - `height` (number): Image height in pixels (optional, returned in response)
  - `thumbnail` (string): Optional base64-encoded thumbnail. Invalid base64 returns `400`.

  The message is accepted whole or not at all. If any attachment's `data` is not valid base64, the request returns `400`: no file and no message is stored, and no run starts. If an attachment cannot be stored, the request returns a `5xx` status and the message is not queued.

  Images larger than approximately 2 MiB or in formats other than JPEG and PNG are submitted for processing.
  Processing targets a 1.5 MiB JPEG.
  A processing failure preserves the original file.
  JPEG and PNG images below the threshold retain their input bytes.
  Processed dimensions are returned in the attachment reference.

  Each stored attachment is returned on the message as a reference whose `size` is the number of bytes in the stored file.

- silent (boolean), default: false

  Set `true` to store the message as a silent message. A silent message is left out of message reads and stream frames unless the reader asks for silent messages (`includeSilent`), and it does not change the thread's list preview or recency. `silent` controls presentation only: the model receives the message, and it starts or joins a run like any other message. A value that is not a boolean returns `400`.

> **Note:**
>
> A thread that is being deleted refuses the message with `423`, and a deleted thread returns `404`.
>
> A terminated thread refuses the message with `423` and the error body `{ "error": { "code", "message" }, "requestId" }`. No message is stored and no run starts. Non-execution routes, including thread and message reads and updates, files, stop, the stream, and thread deletion, remain available. The debug continuation endpoint also refuses execution on a terminated thread.

> **Note:**
>
> This endpoint queues a message only. It does not seed `ThreadState.arguments` or `state.context`; invocation and subagent creation arguments are runtime execution data, not message body fields.

- status ('queued'), required

  The message was accepted durably for delivery.

* messageId (string), required

  The unique identifier for the created message

```bash cURL
curl -X POST https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages \
  -H "Authorization: Bearer $STANDARD_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "Here is a photo of the issue",
    "attachments": [
      {
        "name": "photo.jpg",
        "mimeType": "image/jpeg",
        "data": "/9j/4AAQSkZJRg...",
        "width": 4000,
        "height": 3000
      }
    ]
  }'
```

```typescript JavaScript
const response = await fetch(
  'https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages',
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      role: 'user',
      content: 'Here is a photo of the issue',
      attachments: [{
        name: 'photo.jpg',
        mimeType: 'image/jpeg',
        data: base64EncodedImage,
        width: 4000,
        height: 3000
      }]
    })
  }
);
const result = await response.json();
```

```json 202
{
  "status": "queued",
  "messageId": "msg_550e8400-e29b-41d4-a716-446655440000"
}
```