Skip to main content
The Liquid Rewards chat system is organized around conversations. Every interaction a user has with the RewardsBot shopping assistant — from sending a message to clicking a product to completing a signup — is grouped under a single conversation. This makes it easy to track session continuity, debug behavior, and tie affiliate events back to their originating chat.

​
What is a Conversation?

A conversation is identified by a convo_id: an opaque string you create and manage. It groups all interactions for a single user shopping session.
  • You choose the convo_id — it can be a UUID, a session token, or any unique string meaningful to your system.
  • The same convo_id must be used across chat messages, clickthrough events, and signup submissions to maintain session continuity.
  • The API never auto-generates a convo_id — ownership belongs entirely to you.
Generate a new convo_id for each unique user session. Reusing IDs across users may cause unexpected behavior.

​
Shopper Input

When a user sends a message, POST to /chat/{convo_id} with a ShopperInput body. 
POST https://rewardsbot-prod.liquidrewardsapi.com/chat/{convo_id}
Content-Type: application/json

{
  "chat": "I'm looking for running shoes under $100",
  "refinement_selection": null,
  "product_filter": null
}
​
chat
string
The user’s free-text message to the shopping assistant. This drives the AI’s product search and response generation.
​
refinement_selection
object
A category/selection pair for narrowing results after an initial search. For example:
{ "category": "brand", "selection": "Nike" }
Use this when a user picks from a list of refinement options returned in a prior ShopperReply.
​
product_filter
object
A price range filter to apply to the search. For example:
{ "low_price": 50, "high_price": 150 }
Both low_price and high_price are numeric values in the user’s currency.

​
Shopper Reply

The API responds with a ShopperReply containing the assistant’s message, matched products, refinement options, and pagination metadata. 
{
  "agent_reply": "Here are some great running shoes under $100!",
  "found_products": {
    "query": "running shoes under $100",
    "search_results": {
      "source-a": [{}, {}]
    },
    "price_range": [49.99, 99.99]
  },
  "product_warning": null,
  "refinement_result": {
    "category": "brand",
    "options": ["Nike", "Adidas", "New Balance"]
  },
  "pagination": {
    "conversation_id": "sess-abc123",
    "session_id": "rank-session-id",
    "current_page": 0,
    "page_size": 10,
    "page_count": 5,
    "has_next_page": true,
    "next_page_index": 1
  }
}
​
agent_reply
string
The AI-generated text response to display to the user.
​
found_products
object
Contains the search query the assistant used, a map of results by source, and the price range of returned products.
​
product_warning
string | null
An optional warning message if the assistant encountered limitations (e.g., no products found, query too broad). Display this to the user when present.
​
refinement_result
object | null
When present, contains a category and a list of options the user can select to narrow results. Use these to populate a filter UI and pass the user’s selection back as refinement_selection in the next request.
​
pagination
object | null
Pagination metadata for multi-page result sets. See Pagination in Conversations below.

​
Spying on Conversation State

During development and debugging, you can inspect the raw internal state of any conversation at any point using the spy endpoint. 
GET https://rewardsbot-prod.liquidrewardsapi.com/spy/{convo_id}
This returns the full internal state object for the conversation — including resolved queries, filter history, and session metadata — exactly as the API sees it. This is especially useful when diagnosing unexpected product results or verifying that refinements are being applied correctly.
The /spy/{convo_id} endpoint is intended for debugging purposes only. Do not use it in production user-facing flows or expose its output directly to end users.

​
Pagination in Conversations

When a ShopperReply includes a pagination object and has_next_page is true, there are additional product pages available for the current search.
1

Check for pagination

After receiving a ShopperReply, check if pagination is non-null and pagination.has_next_page is true.
2

Extract session identifiers

Pull the conversation_id and session_id from the pagination object. Also note the next_page_index.
3

Fetch the next page

Call the ranking session pages endpoint:
GET https://rewardsbot-prod.liquidrewardsapi.com/inventory/ranking-sessions/{conversation_id}/{session_id}/pages/{page_index}
Replace {conversation_id} with pagination.conversation_id, {session_id} with pagination.session_id, and {page_index} with pagination.next_page_index.
4

Continue paginating

Each page response includes updated pagination metadata. Repeat until has_next_page is false or the user stops scrolling.
The session_id in the pagination object is distinct from the convo_id. The convo_id identifies the overall user session; the session_id is a short-lived ranking context tied to a specific search query within that session.