Skip to main content

​
Chat API

Interactive chat bot style conversation for item discovery. Pass in conversation_id to continue an existing conversation.

​
Endpoint

POST /chat

​
Request Body (ChatRequest)

FieldTypeRequiredDescription
messageStringYesThe chat message. Example: ‘I am looking for a birthday gift for my dad’.
conversation_idStringNoA string uniquely identifying a conversation. Pass this to continue an existing conversation.
session_idStringNoA string uniquely identifying a session.
user_idStringNoA string uniquely identifying a user.
eventsArrayNoA list of events associated with the conversation. See Event object structure.
limitIntegerNoThe maximum number of items to return. Default is 4.

​
Event Object Structure

The events array contains a list of Event objects, each describing a user interaction or context relevant to the conversation.
FieldTypeRequiredDescription
timestampStringYesISO 8601 timestamp of the event.
typeStringYesType of the event (e.g., browse, click, purchase).
item_idStringNoThe ID of the item associated with the event, if applicable.
descriptionStringNoA free-text description of the event.

​
Example Request

Example Body
{
  "message": "Which desk would you recommend for heavy tools?",
  "conversation_id": "c8a7d9f6-e4b1-42d3-8c2e-5a8d4f31b96f",
  "session_id": "2f396d29-fb98-44cf-996c-e8c66fc02fbe",
  "user_id": "u8a7d9f6",
  "events": [
    {
      "timestamp": "2024-06-14T10:00:00Z",
      "type": "browse",
      "item_id": "ST678VG",
      "description": "Viewed workshop desk details page"
    },
    {
      "timestamp": "2024-06-14T10:03:00Z",
      "type": "click",
      "item_id": "ST678VG",
      "description": "Clicked on product image"
    }
  ]
}

​
Response Body (ChatResponse)

FieldTypeDescription
conversation_idStringA string uniquely identifying the conversation.
messageStringThe chat message response.
itemsArrayA list of items (Item objects) related to the chat response.

​
Example Response

Example Response
{
  "conversation_id": "9b022f99-358e-4041-904d-abb9bd15731a",
  "message": "Here are some great gift ideas for your dad.",
  "items": [
    {
      "item_id": "ST678VG",
      "title": "Itelio workshop desk",
      "status": "active",
      "description": "Solid wood workshop desk for the discerning customer.",
      "price": "999.99"
    }
  ]
}

​
Responses

  • 200 OK: Successful Response (ChatResponse)
  • 422 Validation Error: (HTTPValidationError)