curl --request POST \
--url https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message \
--header 'Content-Type: application/json' \
--header 'X-Access-Token: <api-key>' \
--data '
{
"content": [
{
"text": "<string>",
"cache_prompt": false,
"type": "text"
}
],
"role": "user",
"run": true
}
'import requests
url = "https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message"
payload = {
"content": [
{
"text": "<string>",
"cache_prompt": False,
"type": "text"
}
],
"role": "user",
"run": True
}
headers = {
"X-Access-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Access-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
content: [{text: '<string>', cache_prompt: false, type: 'text'}],
role: 'user',
run: true
})
};
fetch('https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'content' => [
[
'text' => '<string>',
'cache_prompt' => false,
'type' => 'text'
]
],
'role' => 'user',
'run' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Access-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message"
payload := strings.NewReader("{\n \"content\": [\n {\n \"text\": \"<string>\",\n \"cache_prompt\": false,\n \"type\": \"text\"\n }\n ],\n \"role\": \"user\",\n \"run\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Access-Token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message")
.header("X-Access-Token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"content\": [\n {\n \"text\": \"<string>\",\n \"cache_prompt\": false,\n \"type\": \"text\"\n }\n ],\n \"role\": \"user\",\n \"run\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"content\": [\n {\n \"text\": \"<string>\",\n \"cache_prompt\": false,\n \"type\": \"text\"\n }\n ],\n \"role\": \"user\",\n \"run\": true\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"sandbox_status": "STARTING",
"message": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}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
curl --request POST \
--url https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message \
--header 'Content-Type: application/json' \
--header 'X-Access-Token: <api-key>' \
--data '
{
"content": [
{
"text": "<string>",
"cache_prompt": false,
"type": "text"
}
],
"role": "user",
"run": true
}
'import requests
url = "https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message"
payload = {
"content": [
{
"text": "<string>",
"cache_prompt": False,
"type": "text"
}
],
"role": "user",
"run": True
}
headers = {
"X-Access-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Access-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
content: [{text: '<string>', cache_prompt: false, type: 'text'}],
role: 'user',
run: true
})
};
fetch('https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'content' => [
[
'text' => '<string>',
'cache_prompt' => false,
'type' => 'text'
]
],
'role' => 'user',
'run' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Access-Token: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message"
payload := strings.NewReader("{\n \"content\": [\n {\n \"text\": \"<string>\",\n \"cache_prompt\": false,\n \"type\": \"text\"\n }\n ],\n \"role\": \"user\",\n \"run\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Access-Token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message")
.header("X-Access-Token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"content\": [\n {\n \"text\": \"<string>\",\n \"cache_prompt\": false,\n \"type\": \"text\"\n }\n ],\n \"role\": \"user\",\n \"run\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/app-conversations/{conversation_id}/send-message")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"content\": [\n {\n \"text\": \"<string>\",\n \"cache_prompt\": false,\n \"type\": \"text\"\n }\n ],\n \"role\": \"user\",\n \"run\": true\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"sandbox_status": "STARTING",
"message": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}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.
Response
Successful Response
Response from sending a message to a conversation.
Was this page helpful?

