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

# Chat API

> Widget-facing endpoints for messages, conversation history, and escalation.

## Base path

```txt theme={null}
https://platform.watermelonn.app/api/v1/chat
```

All routes require widget auth (tenant JWT or API key).

***

## POST `/message`

Send a user message and receive an assistant response.

### Request body

```json theme={null}
{
  "conversationId": "optional-uuid",
  "message": "Where is my order #1234?"
}
```

* `conversationId` (optional): if omitted, backend creates a new conversation.
* `message` (required): 1–2000 characters.

### Response

```json theme={null}
{
  "conversationId": "uuid",
  "message": {
    "id": "uuid",
    "content": "Your order #1234 is in transit.",
    "role": "assistant",
    "createdAt": "2026-04-27T10:30:00.000Z"
  },
  "metadata": {
    "intentDetected": "track_order",
    "confidence": 0.93,
    "entitiesExtracted": {
      "orderId": "1234"
    }
  }
}
```

***

## GET `/conversations/:id`

Fetch full conversation history for one conversation.

### Response

```json theme={null}
{
  "conversation": {
    "id": "uuid",
    "tenantId": "uuid",
    "status": "active"
  },
  "messages": [
    {
      "id": "uuid",
      "role": "user",
      "content": "Where is my order #1234?"
    }
  ]
}
```

***

## POST `/escalate`

Force escalation to a human agent.

### Request body

```json theme={null}
{
  "conversationId": "uuid",
  "reason": "Customer asked for human support"
}
```

### Response

```json theme={null}
{
  "success": true,
  "ticketId": "tkt_xxx",
  "message": "I've created support ticket #tkt_xxx."
}
```