Send Messages

Send a message and get the agent’s reply. The agent is identified by your access token, and the conversation thread is created automatically on the first message — there is no separate “create thread” call. Three ways to receive the reply:

Transport	Endpoint	Best for
REST	`POST /messaging/v1/messages`	Backends; one request, one complete reply
Server-sent events	`POST /messaging/v1/messages/stream`	Live typing UIs over plain HTTP
WebSocket	`wss .../messaging/v1/session`	Bidirectional chat UIs — see WebSocket

Send a message

cURL

curl -X POST "https://api-v3.aui.io/apollo-api/messaging/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "text": "I want to dispute a charge from May 30th",
    "user_id": "my-user-123"
  }'

POST `/messaging/v1/messages`

Request body

text

string

required

The message to send to the agent.

user_id

string

required

Your identifier for the end user. New threads are attributed to this user.

thread_id

string

Continue an existing thread. Omit it to start a new one — the created thread’s id is returned in the response.

image_url

string

Signed image URL for vision input.

agent_variables

object

Per-message values for the agent’s configured context variables.

Show agent_variables structure

static

object

Values substituted into the agent’s static context {{placeholders}}.

dynamic

object

Values for the variables of the agent’s dynamic-context API calls. On a key collision with static, the dynamic value wins.

Response

thread_id

string

The thread the message landed on — newly created when the request omitted thread_id. Pass it back to continue the conversation.

message

object

The agent’s reply: id (the interaction id — used for reruns and traces), text, rendered cards, followup_suggestions, and token counts.

{
  "thread_id": "68e78d0dc5a4b19a030d03d6",
  "message": {
    "id": "507f1f77bcf86cd799439011",
    "created_at": "2026-07-13T14:02:11Z",
    "text": "I can help with that. Our dispute window is 8 days, so a charge from May 30th is outside it — but here's what you can do instead.",
    "cards": [],
    "followup_suggestions": [
      "What other options do I have?",
      "Show me my recent transactions"
    ],
    "input_tokens": 412,
    "output_tokens": 96
  }
}

const response = await fetch(
  "https://api-v3.aui.io/apollo-api/messaging/v1/messages",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      text: "I want to dispute a charge from May 30th",
      user_id: "my-user-123",
    }),
  }
);

const { thread_id, message } = await response.json();
console.log(thread_id);      // continue the conversation with this
console.log(message.text);

import requests

response = requests.post(
    "https://api-v3.aui.io/apollo-api/messaging/v1/messages",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "text": "I want to dispute a charge from May 30th",
        "user_id": "my-user-123",
    },
)

body = response.json()
print(body["thread_id"])       # continue the conversation with this
print(body["message"]["text"])

Stream the reply (SSE)

POST /messaging/v1/messages/stream takes the same request body and streams the reply token-by-token over server-sent events.

cURL

curl -N -X POST "https://api-v3.aui.io/apollo-api/messaging/v1/messages/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer <access_token>" \
  -d '{ "text": "Hello!", "user_id": "my-user-123" }'

Events are JSON objects discriminated on type:

`type`	When	Payload
`thread`	First event of every stream	`data.thread_id` — the resolved thread (you can’t read headers mid-stream)
`event`	While the agent works	Token deltas carry the text under `data.text`
`message`	Turn complete	The full agent reply — same `message` object as the REST response
`error`	Something failed mid-turn	`data.message` and, when available, a status code

The stream ends with a standalone data: [DONE] terminator.

Example stream

data: {"type":"thread","data":{"thread_id":"68e78d0d..."}}

data: {"type":"event","seq":1,"data":{"text":"I can"}}

data: {"type":"event","seq":2,"data":{"text":" help with that."}}

data: {"type":"message","seq":3,"data":{"id":"507f1f77...","text":"I can help with that.", "followup_suggestions":[]}}

data: [DONE]

Resuming a dropped stream

event and message frames carry a monotonic seq. If the connection drops, reconnect with the standard Last-Event-ID header set to the last seq you saw — missed events replay without running the turn again:

curl -N -X POST ".../messaging/v1/messages/stream" \
  -H "Last-Event-ID: 2" \
  ...

Rerun an interaction

Regenerate a previous interaction — with the original or edited text — against the agent’s live version. The rerun happens on a new thread branched from the original, so the source conversation is untouched.

cURL

curl -X POST "https://api-v3.aui.io/apollo-api/messaging/v1/threads/{threadId}/rerun" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "interaction_id": "507f1f77bcf86cd799439011",
    "text": "Actually, the charge was from June 1st"
  }'

POST `/messaging/v1/threads/{threadId}/rerun`

Request body

interaction_id

string

required

The interaction to regenerate — the message.id from a previous response.

text

string

required

The message to replay: the original text, or an edited variant.

user_id

string

End user to attribute the rerun to. Omitted, the thread’s original user is kept.

image_url

string

Signed image URL on the replayed message.

version_id

string

Pin the rerun to a specific agent version instead of the live one.

version_tag

string

Pin to a specific version tag (e.g. v3.2).

Response

Same shape as send: thread_id is the new thread the rerun created, and message is the regenerated reply.

{
  "thread_id": "68e79a41c5a4b19a030d0f12",
  "message": {
    "id": "507f1f77bcf86cd799439099",
    "text": "A charge from June 1st is within our 8-day dispute window — let's start the dispute.",
    "followup_suggestions": ["What details do you need from me?"],
    "cards": []
  }
}

​Send a message

​POST /messaging/v1/messages

​Request body

​Response

​Stream the reply (SSE)

​Resuming a dropped stream

​Rerun an interaction

​POST /messaging/v1/threads/{threadId}/rerun

​Request body

​Response

Send a message

POST `/messaging/v1/messages`

Request body

Response

Stream the reply (SSE)

Resuming a dropped stream

Rerun an interaction

POST `/messaging/v1/threads/{threadId}/rerun`

Request body

Response