Send Event

Updated at:

Writes events to a session: user messages, interrupts, tool approvals, and function result backfills. The request body contains only the top-level input field, which is an array of events (length 1-50).

Prerequisites

A session must already be created. For details, see Create Session.

Endpoint

POST /sessions/{session_id}/events

The request body contains only one top-level field input, which is an array of events (length 1-50). Each event must contain at least role and type.

Request body structure

{
  "input": [
    { "role": "user", "type": "message", "content": [...] }
  ]
}

Client event types

typerolePurpose and key fields
messageuserSends a user message, triggering the agent to enter running. Required: content (array)
interruptuserInterrupts the current turn; the session returns to idle. Optional top-level session_thread_id (in multi-agent scenarios, targets the interrupt at a specific sub-thread)
tool_approval_responseuserResponds to a tool approval. content is a single data block; data must contain batch_id, call_id, and result (allow / deny); optional deny_message (only for deny, passed back to the model as tool output). Multiple tool_approval_response in the same request must belong to the same batch_id
function_call_outputtoolBackfills the execution result of a self-hosted function. content is a single data block; data must contain call_id and output (string); optional top-level is_error, session_thread_id
tool_call_outputtoolBackfills the execution result of a self-hosted platform built-in tool, with the same structure as function_call_output (content contains call_id + output; optional top-level is_error, session_thread_id)

interrupt and a plain message may be sent together in the same request; the semantics are: finish the current approval batch first, then start chatting.

NoteThe

batch_id and call_id of tool_approval_response together identify an approval (a composite identity, both non-empty); do not match on call_id alone, and do not deduplicate by call_id at the session level. Tool approval is only supported on the main agent, not in sub-agents.

ContentBlock: message content

content is an array of ContentBlocks. Each block is distinguished by type and must use exactly one carrier.

typeMutually exclusive fieldsDescription
texttextPlain text
imageimage_url / file_id (choose one)Image, enters the model's vision channel: public URL or uploaded file ID (dereferenced to a temporary URL, rendered for this turn only, not persisted)
videovideo_url / file_id (choose one)Video, enters the model's vision channel: public URL or uploaded file ID
audiodata + format / file_id (choose one)Audio: only appears in server-side pushes/responses (as a tool output attachment); cannot be sent as client input
filefile_id + filenameFile: uploaded file ID, requires filename (used for the sandbox path and file manifest). Base64 input is not supported. The file is materialized to the session sandbox by the platform, and the model reads it on demand. file_id is the persistent source of truth
datadata (object)Structured data (JSON). Server-side status events also use this carrier
refusalrefusalModel refusal message; only appears in server-side pushes

Example: send a text message

curl -X POST "$AGENTSTUDIO_URL/sessions/sesn_01K8ZQX3/events" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {
        "role": "user",
        "type": "message",
        "content": [
          {"type": "text", "text": "Analyze Q3 sales trends in /mnt/session/uploads/sales.csv"}
        ]
      }
    ]
  }'
client.sessions.events.send(
    "sesn_01K8ZQX3",
    events=[user_message("Analyze Q3 sales trends in /mnt/session/uploads/sales.csv")],
)
client.sessions().events().send("sesn_01K8ZQX3",
    Collections.singletonList(
        ClientEvents.userMessage("Analyze Q3 sales trends in /mnt/session/uploads/sales.csv")));

Response

200 OK returns the echo of the successfully written events and the request ID:

{
  "data": [
    {
      "object": "message",
      "id": "msg_8f2a1c...",
      "created_at": "2025-10-24T08:15:30.123Z",
      "role": "user",
      "type": "message",
      "status": "completed",
      "content": [{"type": "text", "text": "..."}]
    }
  ],
  "request_id": "req_01K8ZQX..."
}

NoteA 200 only means the events were enqueued successfully; it does

not mean the agent has started processing or that a ruling has taken effect — especially for tool_approval_response, acceptance of the event does not mean the approval has been ruled and applied. Observe actual processing results via the SSE event stream or a subsequent GET /events.

Response fields

FieldTypeDescription
dataarray<object>Array of echoed accepted events, aligned with the request input order; the echo only means the event was enqueued, not that it has been processed or that a ruling has taken effect
data[].objectstringObject type, always message
data[].idstringServer-assigned message ID, format msg_&lt;ULID&gt;
data[].created_atstringServer write time, ISO 8601
data[].rolestringEvent role, echoes the user from the request
data[].typestringEvent type, echoes the type of the sent event (e.g., sending message echoes message; sending tool_approval_response echoes tool_approval_response), not always message
data[].statusstringWrite status, always completed
data[].contentarray<object>ContentBlock array, same structure as the request
request_idstringUnique identifier of this request