> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aui.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api/messaging/websocket) |

***

## Send a message

```bash cURL theme={"dark"}
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

<ParamField body="text" type="string" required>
  The message to send to the agent.
</ParamField>

<ParamField body="user_id" type="string" required>
  Your identifier for the end user. New threads are attributed to this user.
</ParamField>

<ParamField body="thread_id" type="string">
  Continue an existing thread. Omit it to start a new one — the created
  thread's id is returned in the response.
</ParamField>

<ParamField body="image_url" type="string">
  Signed image URL for vision input.
</ParamField>

<ParamField body="agent_variables" type="object">
  Per-message values for the agent's configured context variables.

  <Expandable title="agent_variables structure">
    <ParamField body="static" type="object">
      Values substituted into the agent's static context `{{placeholders}}`.
    </ParamField>

    <ParamField body="dynamic" type="object">
      Values for the variables of the agent's dynamic-context API calls. On a
      key collision with `static`, the `dynamic` value wins.
    </ParamField>
  </Expandable>
</ParamField>

#### Response

<ResponseField name="thread_id" type="string">
  The thread the message landed on — newly created when the request omitted
  `thread_id`. Pass it back to continue the conversation.
</ResponseField>

<ResponseField name="message" type="object">
  The agent's reply: `id` (the interaction id — used for reruns and traces),
  `text`, rendered `cards`, `followup_suggestions`, and token counts.
</ResponseField>

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "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
    }
  }
  ```
</ResponseExample>

<CodeGroup>
  ```javascript Node.js theme={"dark"}
  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);
  ```

  ```python Python theme={"dark"}
  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"])
  ```
</CodeGroup>

***

## 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.

```bash cURL theme={"dark"}
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.

```text Example stream theme={"dark"}
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:

```bash theme={"dark"}
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.

```bash cURL theme={"dark"}
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

<ParamField body="interaction_id" type="string" required>
  The interaction to regenerate — the `message.id` from a previous response.
</ParamField>

<ParamField body="text" type="string" required>
  The message to replay: the original text, or an edited variant.
</ParamField>

<ParamField body="user_id" type="string">
  End user to attribute the rerun to. Omitted, the thread's original user is
  kept.
</ParamField>

<ParamField body="image_url" type="string">
  Signed image URL on the replayed message.
</ParamField>

<ParamField body="version_id" type="string">
  Pin the rerun to a specific agent version instead of the live one.
</ParamField>

<ParamField body="version_tag" type="string">
  Pin to a specific version tag (e.g. `v3.2`).
</ParamField>

#### Response

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

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "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": []
    }
  }
  ```
</ResponseExample>