Send message to conversation
POST /api/v1/app-conversations/{conversation_id}/send-message
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: 1. WebSocket: Connect to the agent server's WebSocket endpoint for real-time bidirectional communication 2. Agent Server REST API: Call the agent server's REST endpoints directly using the conversation_url from GET /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}/resume first - 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
Parameters
| Name | In | Type | Required | Description |
|---|
conversation_id | path | string | yes | — |
Request body
| Field | Type | Required | Description |
|---|
role | string | no | The role of the message sender. Currently only "user" is supported. |
content | `TextContent | ImageContent[]` | yes |
run | boolean | no | Whether to automatically run the agent after sending the message. |
Responses
| Status | Description |
|---|
200 | Successful Response |
404 | Conversation or sandbox not found |
409 | Sandbox is not running. Resume it first via POST /sandboxes/{id}/resume |
410 | Conversation is archived (sandbox no longer exists) |
422 | Validation Error |
503 | Sandbox is in error state or agent server unavailable |
Response body
| Field | Type | Required | Description |
|---|
success | boolean | yes | Whether the message was successfully sent to the agent. |
sandbox_status | SandboxStatus | yes | The current status of the sandbox after the operation. |
message | `string | null` | no |
Operation ID: send_message_to_conversation_api_v1_app_conversations__conversation_id__send_message_post