Send Messages

Send messages to your agent — complete responses, token streaming, and reruns.

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, cards, followup_suggestions, and token counts.

200

{
  "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
  }
}

Cards

When the agent surfaces entities — products, bookings, search results — the reply carries them as cards. Each card is the same entity in two self-contained representations, so you pick the one that fits your stack:

cards[].rendered_jsx · string

The card as a ready-to-render JSX string — drop it straight into a React UI.

cards[].json_data · object

The card as structured JSON — build your own UI in any framework (Vue, Angular, mobile, …). entity is a flat key–value map of the card’s fields; sub_entities holds nested groups such as product variants, each with a name and a list of items in the same key–value shape.

cards[].is_recommended · boolean

Whether the agent flagged this card as its top recommendation.

cards[].index · number

The card’s position in the reply.

Example card

{
  "rendered_jsx": "<Card>...</Card>",
  "is_recommended": true,
  "index": 0,
  "json_data": {
    "entity": {
      "product-name": "Honda CR-V, LX",
      "year": 2023,
      "price": 25582,
      "mileage": 10958,
      "image": "https://cdn.example.com/crv.jpg"
    },
    "sub_entities": [
      {
        "name": "Variants",
        "items": [
          { "item-number": "B01HI7WP0U", "price": 329.00 }
        ]
      }
    ]
  }
}

The keys inside entity and sub_entities[].items are defined by your agent’s card templates — treat them as data, not as a fixed schema.

Node.js

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.

200

{
  "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": []
  }
}