> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Messages

> Send messages and interact with Aurora's AI agent

# Chat Messages

Messages are exchanged with Aurora's AI agent through WebSocket connections for real-time streaming responses. Use HTTP endpoints for session management and WebSocket for live chat interactions.

## Message Structure

Messages in Aurora follow a consistent structure for both user and assistant messages.

### User Messages

<ParamField path="sender" type="string" default="user">
  Always "user" for messages from the user
</ParamField>

<ParamField path="text" type="string" required>
  Message text content. Can include:

  * Natural language instructions
  * Questions about infrastructure
  * Commands for cloud operations
  * File attachment context (auto-appended)
</ParamField>

<ParamField path="images" type="array" optional>
  Attached images for multimodal messages (supports image analysis)
</ParamField>

**Example User Message:**

```json theme={null}
{
  "sender": "user",
  "text": "Deploy a load balancer in GCP us-central1"
}
```

### Assistant Messages

<ResponseField name="sender" type="string">
  Always "assistant" for AI responses
</ResponseField>

<ResponseField name="text" type="string">
  Response text with markdown formatting
</ResponseField>

<ResponseField name="tool_calls" type="array" optional>
  Array of tool invocations made by the agent

  <ResponseField name="tool_name" type="string">
    Name of the tool called (e.g., "gcp\_compute", "aws\_ec2")
  </ResponseField>

  <ResponseField name="input" type="object">
    Parameters passed to the tool
  </ResponseField>

  <ResponseField name="output" type="string">
    Tool execution result
  </ResponseField>
</ResponseField>

**Example Assistant Message:**

```json theme={null}
{
  "sender": "assistant",
  "text": "I'll create a load balancer in GCP us-central1 for you.",
  "tool_calls": [
    {
      "tool_name": "gcp_compute",
      "input": {
        "action": "create_load_balancer",
        "region": "us-central1"
      },
      "output": "Load balancer created: lb-prod-001"
    }
  ]
}
```

## Multimodal Messages

Aurora supports multimodal messages with images for visual analysis.

### Sending Images

Images are sent as part of the message content in data URL format:

```json theme={null}
{
  "query": "What's in this infrastructure diagram?",
  "attachments": [
    {
      "filename": "diagram.png",
      "file_type": "image/png",
      "file_data": "iVBORw0KGgoAAAANSUhEUg..."
    }
  ]
}
```

<ParamField path="attachments" type="array">
  Array of file attachments

  <ParamField path="filename" type="string" required>
    Original filename
  </ParamField>

  <ParamField path="file_type" type="string" required>
    MIME type (image/png, image/jpeg, application/pdf)
  </ParamField>

  <ParamField path="file_data" type="string" required>
    Base64-encoded file data (without data URL prefix for images)
  </ParamField>

  <ParamField path="is_server_path" type="boolean" default={false}>
    Whether file\_data is a server path reference
  </ParamField>

  <ParamField path="server_path" type="string" optional>
    Server-side file path (for large files like ZIP archives)
  </ParamField>
</ParamField>

### Supported File Types

* **Images:** PNG, JPEG, GIF, WebP (for visual analysis)
* **Documents:** PDF (text extraction)
* **Archives:** ZIP (server-side processing)

### Image Processing

When messages with images are retrieved:

1. Data URLs are parsed and split into components
2. Images are extracted into `images` array
3. Text content is separated from image data
4. Each image includes:
   * `displayData` - Full data URL for rendering
   * `type` - MIME type
   * `data` - Base64-encoded image data
   * `name` - Generated filename

**Example with Retrieved Images:**

```json theme={null}
{
  "sender": "user",
  "text": "Analyze this diagram",
  "images": [
    {
      "displayData": "data:image/png;base64,iVBORw0KGg...",
      "type": "image/png",
      "data": "iVBORw0KGg...",
      "name": "image_0.png"
    }
  ]
}
```

## Message Context

Aurora maintains conversation context across messages:

### Context Management

<ParamField path="llm_context_history" type="array">
  Complete conversation history sent to LLM

  * Includes all user and assistant messages
  * Contains tool call results
  * Used for context-aware responses
</ParamField>

<ParamField path="ui_messages" type="array">
  Simplified messages for UI display

  * User-facing message format
  * Excludes internal tool details
  * Shown in chat interface
</ParamField>

### Token Management

Messages are subject to token limits:

* **Input limit:** 20,000 tokens per user message (\~80,000 characters)
* **Context window:** Managed automatically by Aurora
* **Token counting:** Validated before processing

**Error Example:**

```json theme={null}
{
  "type": "error",
  "data": {
    "text": "Your message is too long (25000 tokens). Please limit your message to 20,000 tokens.",
    "severity": "error",
    "session_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

## Message Streaming

Messages are streamed in real-time via WebSocket. See [WebSocket Protocol](/api/chat/websocket) for details on:

* Sending chat messages
* Receiving streamed responses
* Handling tool call events
* Managing session state

## Auto-Generated Titles

Session titles are auto-generated from the first user message:

1. Extracts first 50 characters of first user message
2. Trims to last complete word
3. Appends "..." if truncated
4. Defaults to "New Chat" if no user message exists

**Example:**

```
Input: "Deploy a highly available Kubernetes cluster in GCP with auto-scaling enabled"
Title: "Deploy a highly available Kubernetes cluster..."
```

## Best Practices

### Message Composition

* Be specific with cloud resource requirements
* Include region/zone information when relevant
* Provide context for multi-step operations
* Reference previous messages naturally

### Attachments

* Optimize images before uploading (\< 5MB recommended)
* Use PNG for diagrams, JPEG for photos
* Include descriptive filenames
* Attach relevant context files

### Error Handling

* Check token count for large messages
* Validate file formats before uploading
* Handle WebSocket disconnections gracefully
* Retry failed operations with exponential backoff

## Message Lifecycle

1. **Compose** - User creates message with text/attachments
2. **Validate** - Token count and format validation
3. **Send** - Transmitted via WebSocket
4. **Process** - Aurora agent analyzes and executes
5. **Stream** - Response streamed back in chunks
6. **Store** - Messages persisted in session
7. **Display** - Rendered in chat UI