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

# Send messages

> Chat with a running agent.

Sends one or more messages to an agent session: additional instructions, answers to the agent's questions, or a redirection of the task.

**Returns** `202 Accepted`. The message is delivered asynchronously: the agent processes it on its next reasoning step.

Messages adapt to the session's state rather than failing. A `paused` session is auto-resumed before delivery, a [`queued`](/computer-use-agents/observe-and-steer#queued-sessions) session buffers the message until it starts, and a finished session is restarted (back to `pending`, subject to your [token budget](/computer-use-agents/plans-and-limits#token-usage)) with the message delivered to the relaunched agent.

***

## Path parameters

<ParamField path="id" type="string" required>
  The session ID.
</ParamField>

***

## Request body

The body is a discriminated union: send either a single message or a batch.

### Single message

<ParamField body="type" type="string" default="user_message">
  `"user_message"`. May be omitted.
</ParamField>

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

<ParamField body="images" type="array">
  Optional list of base64 data URIs to attach to the message (e.g. `data:image/png;base64,...`).
</ParamField>

<ParamField body="caller_id" type="string">
  Identifies the message sender. Defaults to `user`; leave it unset for normal user input.
</ParamField>

### Batch

<ParamField body="type" type="string" required>
  Must be `"batch"`.
</ParamField>

<ParamField body="messages" type="array" required>
  Array of message objects, each with `type: "user_message"` and `message`. Processed in order.
</ParamField>

***

## Examples

### Send a single message

<CodeGroup>
  ```bash CLI theme={null}
  hai sessions send "$SESSION_ID" 'Focus on hotels near Kiyomizu-dera temple, under $200/night'
  ```

  ```bash cURL theme={null}
  curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/messages \
    -H "Authorization: Bearer $HAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "user_message",
      "message": "Focus on hotels near Kiyomizu-dera temple, under $200/night"
    }'
  ```

  ```python Python theme={null}
  from hai_agents import Client
  from hai_agents.sessions import SendSessionMessagesRequestBody_UserMessage

  client = Client()

  client.sessions.send_session_messages(
      session_id,
      request=SendSessionMessagesRequestBody_UserMessage(
          message="Focus on hotels near Kiyomizu-dera temple, under $200/night",
      ),
  )
  ```

  ```typescript TypeScript theme={null}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  await client.sessions.sendSessionMessages({
    id: sessionId,
    body: {
      type: "user_message",
      message: "Focus on hotels near Kiyomizu-dera temple, under $200/night",
    },
  });
  ```
</CodeGroup>

### Send a batch of messages

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/messages \
    -H "Authorization: Bearer $HAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "batch",
      "messages": [
        {"type": "user_message", "message": "Also check availability for June 15-20"},
        {"type": "user_message", "message": "I prefer traditional ryokans over modern hotels"}
      ]
    }'
  ```

  ```python Python theme={null}
  from hai_agents import Client, UserMessageEvent
  from hai_agents.sessions import SendSessionMessagesRequestBody_Batch

  client = Client()

  client.sessions.send_session_messages(
      session_id,
      request=SendSessionMessagesRequestBody_Batch(
          messages=[
              UserMessageEvent(message="Also check availability for June 15-20"),
              UserMessageEvent(message="I prefer traditional ryokans over modern hotels"),
          ],
      ),
  )
  ```

  ```typescript TypeScript theme={null}
  import { HaiAgentsClient } from "hai-agents";

  const client = new HaiAgentsClient();

  await client.sessions.sendSessionMessages({
    id: sessionId,
    body: {
      type: "batch",
      messages: [
        { type: "user_message", message: "Also check availability for June 15-20" },
        { type: "user_message", message: "I prefer traditional ryokans over modern hotels" },
      ],
    },
  });
  ```
</CodeGroup>

***

## Errors

| Status | Cause                                                                                                                                                                       |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `402`  | The message would restart a finished session, but your organization's token budget is exhausted. See [Plans and limits](/computer-use-agents/plans-and-limits#token-usage). |
| `404`  | Session not found, or you don't have access.                                                                                                                                |
| `422`  | Invalid message body, for example an image that isn't a decodable base64 data URI.                                                                                          |