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

string

required

The message to send to the agent.

string

required

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

string

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

string

Signed image URL for vision input.

object

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

Show agent_variables structure

object

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

object

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

Response

string

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

object

The agent’s reply: id (the interaction id — used for reruns and traces), text, 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
  }
}

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:

string

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

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.

boolean

Whether the agent flagged this card as its top recommendation.

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.

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

string

required

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

string

required

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

string

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

string

Signed image URL on the replayed message.

string

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

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

Get started

Messaging

Management

Send Messages

Send a message

POST `/messaging/v1/messages`

Request body

Response

Cards

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

​Cards

​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

Cards

Stream the reply (SSE)

Resuming a dropped stream

Rerun an interaction

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

Request body

Response