docs: Add send-message REST endpoint documentation#482
docs: Add send-message REST endpoint documentation#482
Conversation
Add documentation for the new POST /api/v1/app-conversations/{id}/send-message
endpoint that allows sending follow-up messages to conversations without
a WebSocket connection.
Includes:
- Request/response format examples
- Prerequisites (sandbox must be RUNNING)
- Error response codes
- Alternative approaches (WebSocket, direct agent server API)
- Design note about being a thin proxy
Related to: OpenHands/OpenHands#14182
Co-authored-by: openhands <openhands@all-hands.dev>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
Documentation is clear and well-structured. A few suggestions to improve completeness for end users.
| } | ||
| ``` | ||
|
|
||
| | Field | Type | Required | Description | |
There was a problem hiding this comment.
🟡 Suggestion: The description mentions "text and/or image" but only shows a text example. Consider adding an example of the image content block format:
{
"role": "user",
"content": [
{"type": "text", "text": "Check this image:"},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
],
"run": true
}Or add a link to documentation that describes the content block schema in detail.
| ``` | ||
|
|
||
| ### Error responses | ||
|
|
There was a problem hiding this comment.
🟡 Suggestion: The error description says "Resume it first" for STARTING/STOPPING states, but the prerequisites section (line 47) correctly says to "wait" for STARTING state, not resume it. Consider clarifying:
| | 409 | Sandbox is not running. For PAUSED state, resume it first. For STARTING state, wait for it to reach RUNNING. | |
| | 503 | Sandbox is in error state or agent server is unavailable. | | ||
|
|
||
| ### Alternative approaches | ||
|
|
There was a problem hiding this comment.
🟡 Suggestion: The conversation_url field is referenced but not explained. Consider either:
- Adding a sentence explaining what this field contains (e.g., "the base URL for direct agent server API calls")
- Linking to documentation for the
GET /api/v1/app-conversations/{id}endpoint response schema - Or providing an example showing what a conversation_url looks like
| This endpoint is a convenience wrapper. You can also interact with the agent server directly: | ||
|
|
||
| 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 <code>GET /api/v1/app-conversations/{id}</code>. |
There was a problem hiding this comment.
🟡 Suggestion: Webhook callbacks are mentioned but not explained or linked. Consider either:
- Linking to webhook callback documentation if it exists
- Or briefly explaining what webhook callbacks are in this context (e.g., "via the conversation's webhook configuration")
This helps users understand how to implement custom processing without having to search for webhook documentation separately.
4 participants
Summary
Add documentation for the new
POST /api/v1/app-conversations/{id}/send-messageREST endpoint that allows sending follow-up messages to conversations without establishing a WebSocket connection.Changes
Related
This documentation accompanies the feature PR: OpenHands/OpenHands#14182
This PR was created by an AI agent (OpenHands).
@malhotra5 can click here to continue refining the PR