Send Message To Conversation
Send a follow-up message to an existing conversation.
This REST endpoint provides a simplified way to send messages to a running conversation without requiring a WebSocket connection.
Alternative Approaches:
This endpoint is a convenience wrapper. You can also interact with the agent server directly using:
- WebSocket: Connect to the agent server’s WebSocket endpoint for real-time bidirectional communication
- Agent Server REST API: Call the agent server’s REST endpoints directly
using the
conversation_urlfromGET /api/v1/app-conversations/{id}
Design Note:
This endpoint is intentionally a thin proxy that forwards messages to the agent server without additional processing logic. Any custom processing (validation, transformation, side effects) should be implemented via webhook callbacks, not in this endpoint. This ensures that direct agent server invocation and this convenience endpoint remain functionally equivalent.
Prerequisites:
- The sandbox must be in RUNNING state
- If the sandbox is PAUSED, call
POST /api/v1/sandboxes/{sandbox_id}/resumefirst - If the sandbox is STARTING, wait for it to reach RUNNING state
Error responses:
- 404: Conversation or sandbox not found
- 409: Sandbox exists but is not running (PAUSED, STARTING, STOPPING)
- 410: Conversation is archived (sandbox no longer exists)
- 503: Sandbox is in ERROR state or agent server is unavailable
Args: conversation_id: The UUID of the conversation to send the message to request: The message content and options
Returns: AppSendMessageResponse with success status and sandbox state
Authorizations
Path Parameters
Body
Request to send a follow-up message to a conversation.
This is used to send messages to an existing conversation via REST API, as an alternative to WebSocket communication.
The message content as a list of text and/or image content blocks.
1- TextContent
- ImageContent
The role of the message sender. Currently only "user" is supported.
"user"Whether to automatically run the agent after sending the message.
Response
Successful Response
Response from sending a message to a conversation.
Whether the message was successfully sent to the agent.
The current status of the sandbox after the operation.
STARTING, RUNNING, PAUSED, ERROR, MISSING Optional message with additional details (e.g., if sandbox was resumed).

