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

# Chat

> Send messages and receive AI responses

## Request

Send a message to an agent and receive a streaming response.

<ParamField body="agentId" type="string" required>
  The ID of the agent to chat with
</ParamField>

<ParamField body="messages" type="array" required>
  Array of message objects with `role` and `content`
</ParamField>

<ParamField body="conversationId" type="string">
  Optional conversation ID to continue an existing conversation
</ParamField>

### Message Object

```json theme={null}
{
  "role": "user",
  "content": "What are your business hours?"
}
```

Roles:

* `user` - Messages from the end user
* `assistant` - Previous AI responses (for context)

## Response

The response is a Server-Sent Events (SSE) stream.

### Event Types

| Event                 | Description                 |
| --------------------- | --------------------------- |
| `message_start`       | Start of assistant response |
| `content_block_start` | Start of content block      |
| `content_block_delta` | Text chunk                  |
| `tool_use_start`      | Agent is calling a tool     |
| `tool_result`         | Tool execution result       |
| `content_block_stop`  | End of content block        |
| `message_stop`        | End of message              |

### Delta Object

```json theme={null}
{
  "type": "content_block_delta",
  "delta": {
    "type": "text_delta",
    "text": "Our business hours are "
  }
}
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.ansa.so/chat \
    -H "Content-Type: application/json" \
    -d '{
      "agentId": "agent_xxx",
      "messages": [
        {"role": "user", "content": "What are your business hours?"}
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.ansa.so/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agentId: 'agent_xxx',
      messages: [
        { role: 'user', content: 'What are your business hours?' }
      ]
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    // Parse SSE events
    const lines = chunk.split('\n');
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        if (data.delta?.text) {
          process.stdout.write(data.delta.text);
        }
      }
    }
  }
  ```

  ```python Python theme={null}
  import requests
  import json

  response = requests.post(
      'https://api.ansa.so/chat',
      json={
          'agentId': 'agent_xxx',
          'messages': [
              {'role': 'user', 'content': 'What are your business hours?'}
          ]
      },
      stream=True
  )

  for line in response.iter_lines():
      if line:
          line = line.decode('utf-8')
          if line.startswith('data: '):
              data = json.loads(line[6:])
              if 'delta' in data and 'text' in data['delta']:
                  print(data['delta']['text'], end='')
  ```
</RequestExample>

<ResponseExample>
  ```text SSE Stream theme={null}
  event: message_start
  data: {"type":"message_start","conversationId":"conv_xxx"}

  event: content_block_start
  data: {"type":"content_block_start","index":0}

  event: content_block_delta
  data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Our business hours are "}}

  event: content_block_delta
  data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Monday through Friday, 9 AM to 5 PM."}}

  event: content_block_stop
  data: {"type":"content_block_stop","index":0}

  event: message_stop
  data: {"type":"message_stop"}
  ```
</ResponseExample>