Deliver a structured event to a conversation thread as a turn
curl --request POST \
--url https://api.example.com/api/conversations/{route_name}/events \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"event": {
"event_id": "<string>",
"kind": "<string>",
"payload": {}
},
"address": "<string>",
"thread_id": "<string>",
"wait_seconds": 0
}
'import requests
url = "https://api.example.com/api/conversations/{route_name}/events"
payload = {
"event": {
"event_id": "<string>",
"kind": "<string>",
"payload": {}
},
"address": "<string>",
"thread_id": "<string>",
"wait_seconds": 0
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
event: {event_id: '<string>', kind: '<string>', payload: {}},
address: '<string>',
thread_id: '<string>',
wait_seconds: 0
})
};
fetch('https://api.example.com/api/conversations/{route_name}/events', 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/conversations/{route_name}/events",
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([
'event' => [
'event_id' => '<string>',
'kind' => '<string>',
'payload' => [
]
],
'address' => '<string>',
'thread_id' => '<string>',
'wait_seconds' => 0
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <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/conversations/{route_name}/events"
payload := strings.NewReader("{\n \"event\": {\n \"event_id\": \"<string>\",\n \"kind\": \"<string>\",\n \"payload\": {}\n },\n \"address\": \"<string>\",\n \"thread_id\": \"<string>\",\n \"wait_seconds\": 0\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<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/conversations/{route_name}/events")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"event\": {\n \"event_id\": \"<string>\",\n \"kind\": \"<string>\",\n \"payload\": {}\n },\n \"address\": \"<string>\",\n \"thread_id\": \"<string>\",\n \"wait_seconds\": 0\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/conversations/{route_name}/events")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"event\": {\n \"event_id\": \"<string>\",\n \"kind\": \"<string>\",\n \"payload\": {}\n },\n \"address\": \"<string>\",\n \"thread_id\": \"<string>\",\n \"wait_seconds\": 0\n}"
response = http.request(request)
puts response.read_body{
"data": {
"message_id": "<string>",
"thread_id": "<string>",
"answer": {
"message_id": "<string>",
"status": "answered",
"thread_id": "<string>",
"answer": "<string>",
"parts": [
{
"data": {
"options": {},
"values": {}
},
"footer": "<string>",
"form_tag": "<string>",
"header": {
"kind": "image",
"url": "<string>",
"caption": "<string>",
"filename": "<string>"
},
"location": {
"latitude": 123,
"longitude": 123,
"address": "<string>",
"name": "<string>"
},
"media": [
{
"kind": "image",
"url": "<string>",
"caption": "<string>",
"filename": "<string>"
}
],
"message": "",
"options": [
{
"text": "<string>",
"description": "<string>",
"id": "<string>",
"kind": "reply"
}
],
"pages": [
{
"fields": [
"<string>"
],
"title": "<string>",
"button_label": "<string>",
"display": [],
"kind": "input"
}
],
"schema": {},
"sections": [
{
"rows": [
{
"text": "<string>",
"description": "<string>",
"id": "<string>",
"kind": "reply"
}
],
"title": "<string>"
}
],
"template": {
"language": "<string>",
"name": "<string>",
"parameters": {}
},
"wording": {
"answer": {
"confirm": "<string>",
"decline": "<string>",
"open": "<string>",
"rejected": "<string>",
"rejected_final": "<string>",
"reply_hint": "<string>",
"submit": "<string>"
},
"answer_page": {
"awaiting": {
"heading": "<string>",
"text": "<string>"
},
"confirm": {
"heading": "<string>",
"text": "<string>"
},
"done": {
"heading": "<string>",
"text": "<string>"
},
"form": {
"choose_one": "<string>",
"date_unavailable": "<string>",
"failed": "<string>",
"network_error": "<string>"
},
"submitted": {
"heading": "<string>",
"text": "<string>"
}
},
"choice": {
"group_label": "<string>",
"label": "<string>",
"reply_hint": "<string>"
},
"form": {
"back": "<string>",
"cancel": "<string>",
"error_line": "<string>",
"fields": {},
"open": "<string>",
"review_empty": "<string>",
"step_progress": "<string>",
"submit": "<string>",
"title": "<string>",
"update_failed": "<string>"
},
"lines": {
"answer_link": "<string>",
"deadline": "<string>",
"options": "<string>",
"reply": "<string>"
},
"status": {
"answered": "<string>",
"closed": "<string>",
"countdown": {
"one_second_left": "<string>",
"seconds_left": "<string>",
"under_half_minute": "<string>",
"under_minute": "<string>",
"under_ten_seconds": "<string>"
},
"expired": "<string>",
"sending": "<string>",
"sent": "<string>",
"unavailable": "<string>"
}
}
}
],
"successor_id": "<string>"
}
}
}{
"data": {
"message_id": "<string>",
"thread_id": "<string>",
"answer": {
"message_id": "<string>",
"status": "answered",
"thread_id": "<string>",
"answer": "<string>",
"parts": [
{
"data": {
"options": {},
"values": {}
},
"footer": "<string>",
"form_tag": "<string>",
"header": {
"kind": "image",
"url": "<string>",
"caption": "<string>",
"filename": "<string>"
},
"location": {
"latitude": 123,
"longitude": 123,
"address": "<string>",
"name": "<string>"
},
"media": [
{
"kind": "image",
"url": "<string>",
"caption": "<string>",
"filename": "<string>"
}
],
"message": "",
"options": [
{
"text": "<string>",
"description": "<string>",
"id": "<string>",
"kind": "reply"
}
],
"pages": [
{
"fields": [
"<string>"
],
"title": "<string>",
"button_label": "<string>",
"display": [],
"kind": "input"
}
],
"schema": {},
"sections": [
{
"rows": [
{
"text": "<string>",
"description": "<string>",
"id": "<string>",
"kind": "reply"
}
],
"title": "<string>"
}
],
"template": {
"language": "<string>",
"name": "<string>",
"parameters": {}
},
"wording": {
"answer": {
"confirm": "<string>",
"decline": "<string>",
"open": "<string>",
"rejected": "<string>",
"rejected_final": "<string>",
"reply_hint": "<string>",
"submit": "<string>"
},
"answer_page": {
"awaiting": {
"heading": "<string>",
"text": "<string>"
},
"confirm": {
"heading": "<string>",
"text": "<string>"
},
"done": {
"heading": "<string>",
"text": "<string>"
},
"form": {
"choose_one": "<string>",
"date_unavailable": "<string>",
"failed": "<string>",
"network_error": "<string>"
},
"submitted": {
"heading": "<string>",
"text": "<string>"
}
},
"choice": {
"group_label": "<string>",
"label": "<string>",
"reply_hint": "<string>"
},
"form": {
"back": "<string>",
"cancel": "<string>",
"error_line": "<string>",
"fields": {},
"open": "<string>",
"review_empty": "<string>",
"step_progress": "<string>",
"submit": "<string>",
"title": "<string>",
"update_failed": "<string>"
},
"lines": {
"answer_link": "<string>",
"deadline": "<string>",
"options": "<string>",
"reply": "<string>"
},
"status": {
"answered": "<string>",
"closed": "<string>",
"countdown": {
"one_second_left": "<string>",
"seconds_left": "<string>",
"under_half_minute": "<string>",
"under_minute": "<string>",
"under_ten_seconds": "<string>"
},
"expired": "<string>",
"sending": "<string>",
"sent": "<string>",
"unavailable": "<string>"
}
}
}
],
"successor_id": "<string>"
}
}
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "reloading — the server is applying a config reload; retry shortly",
"reloading": true
}conversations
Deliver a structured event to a conversation thread as a turn
Run a structured event as a turn on an EXISTING thread of route_name.
The thread must already exist: an event enters a conversation as a turn and never mints a
thread. Address it by the address its listing shows or by its thread_id (exactly
one). The turn runs the route’s TOOL target AS the route’s execution key — an
agent-target route is refused (409) since an event carries no rendered text. The
event is IDEMPOTENT on event_id: a redelivery returns the original turn’s
message_id (202) and runs no second turn.
The answer is delivered by the TARGET route’s door — a channel route texts the thread’s
address, an api route POSTs the route’s signed callback (a wait_seconds body field,
clamped to sync_wait_max_seconds, returns a finished turn’s answer inline in the
200 and suppresses the callback, but only while the client is still connected — a
hung-up caller’s answer falls to the callback or its terminal poll record). Default is
202 {message_id, thread_id}.
This is a TRUSTED-integration door: an authorized writer may address ANY existing thread
of the route by thread_id (a channel participant’s included), so a deployment grants its
write action to service principals, not to low-trust API keys.
POST
/
api
/
conversations
/
{route_name}
/
events
Deliver a structured event to a conversation thread as a turn
curl --request POST \
--url https://api.example.com/api/conversations/{route_name}/events \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"event": {
"event_id": "<string>",
"kind": "<string>",
"payload": {}
},
"address": "<string>",
"thread_id": "<string>",
"wait_seconds": 0
}
'import requests
url = "https://api.example.com/api/conversations/{route_name}/events"
payload = {
"event": {
"event_id": "<string>",
"kind": "<string>",
"payload": {}
},
"address": "<string>",
"thread_id": "<string>",
"wait_seconds": 0
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
event: {event_id: '<string>', kind: '<string>', payload: {}},
address: '<string>',
thread_id: '<string>',
wait_seconds: 0
})
};
fetch('https://api.example.com/api/conversations/{route_name}/events', 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/conversations/{route_name}/events",
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([
'event' => [
'event_id' => '<string>',
'kind' => '<string>',
'payload' => [
]
],
'address' => '<string>',
'thread_id' => '<string>',
'wait_seconds' => 0
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <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/conversations/{route_name}/events"
payload := strings.NewReader("{\n \"event\": {\n \"event_id\": \"<string>\",\n \"kind\": \"<string>\",\n \"payload\": {}\n },\n \"address\": \"<string>\",\n \"thread_id\": \"<string>\",\n \"wait_seconds\": 0\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<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/conversations/{route_name}/events")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"event\": {\n \"event_id\": \"<string>\",\n \"kind\": \"<string>\",\n \"payload\": {}\n },\n \"address\": \"<string>\",\n \"thread_id\": \"<string>\",\n \"wait_seconds\": 0\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/conversations/{route_name}/events")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"event\": {\n \"event_id\": \"<string>\",\n \"kind\": \"<string>\",\n \"payload\": {}\n },\n \"address\": \"<string>\",\n \"thread_id\": \"<string>\",\n \"wait_seconds\": 0\n}"
response = http.request(request)
puts response.read_body{
"data": {
"message_id": "<string>",
"thread_id": "<string>",
"answer": {
"message_id": "<string>",
"status": "answered",
"thread_id": "<string>",
"answer": "<string>",
"parts": [
{
"data": {
"options": {},
"values": {}
},
"footer": "<string>",
"form_tag": "<string>",
"header": {
"kind": "image",
"url": "<string>",
"caption": "<string>",
"filename": "<string>"
},
"location": {
"latitude": 123,
"longitude": 123,
"address": "<string>",
"name": "<string>"
},
"media": [
{
"kind": "image",
"url": "<string>",
"caption": "<string>",
"filename": "<string>"
}
],
"message": "",
"options": [
{
"text": "<string>",
"description": "<string>",
"id": "<string>",
"kind": "reply"
}
],
"pages": [
{
"fields": [
"<string>"
],
"title": "<string>",
"button_label": "<string>",
"display": [],
"kind": "input"
}
],
"schema": {},
"sections": [
{
"rows": [
{
"text": "<string>",
"description": "<string>",
"id": "<string>",
"kind": "reply"
}
],
"title": "<string>"
}
],
"template": {
"language": "<string>",
"name": "<string>",
"parameters": {}
},
"wording": {
"answer": {
"confirm": "<string>",
"decline": "<string>",
"open": "<string>",
"rejected": "<string>",
"rejected_final": "<string>",
"reply_hint": "<string>",
"submit": "<string>"
},
"answer_page": {
"awaiting": {
"heading": "<string>",
"text": "<string>"
},
"confirm": {
"heading": "<string>",
"text": "<string>"
},
"done": {
"heading": "<string>",
"text": "<string>"
},
"form": {
"choose_one": "<string>",
"date_unavailable": "<string>",
"failed": "<string>",
"network_error": "<string>"
},
"submitted": {
"heading": "<string>",
"text": "<string>"
}
},
"choice": {
"group_label": "<string>",
"label": "<string>",
"reply_hint": "<string>"
},
"form": {
"back": "<string>",
"cancel": "<string>",
"error_line": "<string>",
"fields": {},
"open": "<string>",
"review_empty": "<string>",
"step_progress": "<string>",
"submit": "<string>",
"title": "<string>",
"update_failed": "<string>"
},
"lines": {
"answer_link": "<string>",
"deadline": "<string>",
"options": "<string>",
"reply": "<string>"
},
"status": {
"answered": "<string>",
"closed": "<string>",
"countdown": {
"one_second_left": "<string>",
"seconds_left": "<string>",
"under_half_minute": "<string>",
"under_minute": "<string>",
"under_ten_seconds": "<string>"
},
"expired": "<string>",
"sending": "<string>",
"sent": "<string>",
"unavailable": "<string>"
}
}
}
],
"successor_id": "<string>"
}
}
}{
"data": {
"message_id": "<string>",
"thread_id": "<string>",
"answer": {
"message_id": "<string>",
"status": "answered",
"thread_id": "<string>",
"answer": "<string>",
"parts": [
{
"data": {
"options": {},
"values": {}
},
"footer": "<string>",
"form_tag": "<string>",
"header": {
"kind": "image",
"url": "<string>",
"caption": "<string>",
"filename": "<string>"
},
"location": {
"latitude": 123,
"longitude": 123,
"address": "<string>",
"name": "<string>"
},
"media": [
{
"kind": "image",
"url": "<string>",
"caption": "<string>",
"filename": "<string>"
}
],
"message": "",
"options": [
{
"text": "<string>",
"description": "<string>",
"id": "<string>",
"kind": "reply"
}
],
"pages": [
{
"fields": [
"<string>"
],
"title": "<string>",
"button_label": "<string>",
"display": [],
"kind": "input"
}
],
"schema": {},
"sections": [
{
"rows": [
{
"text": "<string>",
"description": "<string>",
"id": "<string>",
"kind": "reply"
}
],
"title": "<string>"
}
],
"template": {
"language": "<string>",
"name": "<string>",
"parameters": {}
},
"wording": {
"answer": {
"confirm": "<string>",
"decline": "<string>",
"open": "<string>",
"rejected": "<string>",
"rejected_final": "<string>",
"reply_hint": "<string>",
"submit": "<string>"
},
"answer_page": {
"awaiting": {
"heading": "<string>",
"text": "<string>"
},
"confirm": {
"heading": "<string>",
"text": "<string>"
},
"done": {
"heading": "<string>",
"text": "<string>"
},
"form": {
"choose_one": "<string>",
"date_unavailable": "<string>",
"failed": "<string>",
"network_error": "<string>"
},
"submitted": {
"heading": "<string>",
"text": "<string>"
}
},
"choice": {
"group_label": "<string>",
"label": "<string>",
"reply_hint": "<string>"
},
"form": {
"back": "<string>",
"cancel": "<string>",
"error_line": "<string>",
"fields": {},
"open": "<string>",
"review_empty": "<string>",
"step_progress": "<string>",
"submit": "<string>",
"title": "<string>",
"update_failed": "<string>"
},
"lines": {
"answer_link": "<string>",
"deadline": "<string>",
"options": "<string>",
"reply": "<string>"
},
"status": {
"answered": "<string>",
"closed": "<string>",
"countdown": {
"one_second_left": "<string>",
"seconds_left": "<string>",
"under_half_minute": "<string>",
"under_minute": "<string>",
"under_ten_seconds": "<string>"
},
"expired": "<string>",
"sending": "<string>",
"sent": "<string>",
"unavailable": "<string>"
}
}
}
],
"successor_id": "<string>"
}
}
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "reloading — the server is applying a config reload; retry shortly",
"reloading": true
}Authorizations
Path Parameters
Body
application/json
The inbound body of the event door POST /api/conversations/{route_name}/events.
An :class:ConversationEvent addressed to an EXISTING thread by EXACTLY ONE (non-blank)
of address (the thread's client address) or thread_id (the id the monitoring
listing exposes). wait_seconds bounds a sync-wait window exactly as
:attr:ConversationMessage.wait_seconds. There is NO callback field — an event's answer
is delivered against the target thread's route. Frozen.
A structured event delivered to an existing thread as a turn.
event_id (non-blank after trim, ≤ EVENT_ID_MAX_CHARS) is the idempotency key;
kind is an identifier-like label matching EVENT_KIND_RE; payload is opaque,
untrusted data bounded as pure transport by :func:validate_bounded_object. Frozen.
Show child attributes
Show child attributes
Bounded sync-wait window (seconds); 0 = async 202. The door clamps to its runtime cap.
Required range:
x >= 0Response
Success.
The ack a message/event submission returns: the accepted turn's message_id and thread_id.
answer is present on every inline-waited turn that finished in time (a 200) — including a silent one,
which carries the silent marker (status silent, no answer text, dumped exclude_none); it is
absent only on the default deferred 202, whose turn produced no outcome yet.
Show child attributes
Show child attributes