Send messages

Send a running agent more context, a correction, or an answer to its question.

POST /api/v2/sessions/{id}/messages

CLI

holo sessions send "$SESSION_ID" 'Focus on hotels near Kiyomizu-dera temple, under $200/night'

Behavior

The agent reads messages on its next step.

Delivery adapts to the session’s state: a paused session is resumed first, a queued session buffers the message until it starts, and a finished session restarts (back to pending, billed as in Token usage) with the message delivered to the relaunched agent.

Path parameters

id · string · required

The session ID.

Request body

Send either a single message or a batch, discriminated by type.

Single message

type · string · default: "user_message"

"user_message". May be omitted.

message · string · required

The message text.

images · string[]

Base64 data URIs to attach, for example data:image/png;base64,....

files · object[]

Files to attach, up to 10 and 7 MB in total. Each is { name, source, type: "base64", media_type? } (media_type is guessed if omitted). Saved under files/ in a code sandbox workspace, and ~/Downloads on a cloud browser.

caller_id · string · default: "user"

The sender. Leave it unset for normal user input.

skills · object[]

Skills for this message only, as inline skill objects (name, description, body). The agent gets their instructions with this message, and the agent’s own skills are unchanged.

"skills": [
  {"name": "team-tone", "description": "Write like our team", "body": "Answer in three short bullets."}
]

Batch

type · string · required

"batch".

messages · object[] · required

At least one single-message object, processed in order.

Response

202 Accepted. The message is delivered asynchronously.

CLI

holo sessions send "$SESSION_ID" 'Focus on hotels near Kiyomizu-dera temple, under $200/night'

More examples

Send a batch of messages

Python

from hai_agents import Client

client = Client()

client.sessions.send_session_messages(
    session_id,
    request={
        "type": "batch",
        "messages": [
            {"message": "Also check availability for June 15-20"},
            {"message": "I prefer traditional ryokans over modern hotels"},
        ],
    },
)

Errors

Status	Cause
404	Not found, or not in your organization.
409	The session just stopped and is still shutting down. detail[].type is session_stopping. Send the message again after Retry-After to restart it.
422	Invalid message body, for example an image that isn’t a decodable base64 data URI.
429	The message would restart a finished session, but no slot is free: you are at your concurrency limit, or the platform is at capacity. detail[].type says which limit was hit. The session stays finished and the message is not delivered. A restart never queues, so retry later.