Skip to main content

​
Base path

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

{
  "conversationId": "optional-uuid",
  "message": "Where is my order #1234?"
}
  • conversationId (optional): if omitted, backend creates a new conversation.
  • message (required): 1–2000 characters.

​
Response

{
  "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

{
  "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

{
  "conversationId": "uuid",
  "reason": "Customer asked for human support"
}

​
Response

{
  "success": true,
  "ticketId": "tkt_xxx",
  "message": "I've created support ticket #tkt_xxx."
}