> ## Documentation Index
> Fetch the complete documentation index at: https://docs.standardagentbuilder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/websocket/stream).
</Note>

<ParamField path="threadId" type="string" required>
  The unique thread identifier (UUID)
</ParamField>

<ParamField body="role" type="string" required>
  Message role: `"user"`, `"system"`, or `"assistant"`
</ParamField>

<ParamField body="content" type="string" required>
  The message content
</ParamField>

<ParamField body="attachments" type="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)

  All images are automatically processed: resized to fit under 1.5MB and converted to JPEG. The processed `width` and `height` are stored and returned in message attachments.
</ParamField>

<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.
</Note>

<ParamField body="userId" type="string">
  Optional user identifier for tracking
</ParamField>

<ResponseField name="success" type="boolean" required>
  Whether the message was successfully queued
</ResponseField>

<ResponseField name="messageId" type="string" required>
  The unique identifier for the created message
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages \
    -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 theme={null}
  const response = await fetch(
    'https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages',
    {
      method: 'POST',
      headers: { '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();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "messageId": "msg_550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</ResponseExample>