Overview

The Netcore Unbxd Shopping Agent, is an AI-driven chatbot integrated into e-commerce websites. It assists customers by understanding their preferences, guiding them in product selection, and offering tailored suggestions based on their interactions with the agent.

Key Features of a Shopping Agent:

1. Personalized Recommendations: Based on user queries, browsing behavior, and past interactions, the assistant suggests products that the user will likely be interested in.
2. Real-time Interaction: It engages users in real-time conversations, offering immediate answers to questions about products, shipping details, availability, and more.
3. Search Assistance: It helps users refine their search by applying filters (e.g., size, color, brand) or guiding them through a product catalog.
4. Product Discovery: If the user is unsure about what to buy, the assistant offers curated product options, helping users explore a variety of choices.

Why is a Shopping Agent Useful?

1. Improved Customer Experience:

   By offering immediate assistance, personalized product suggestions, and easy navigation, shopping assistants make the shopping process more intuitive and enjoyable for users. This leads to higher customer satisfaction.

2. Increased Conversions and Sales:

   Personalized product recommendations can directly influence purchasing decisions. By presenting the right products at the right time, a shopping agent can drive higher conversion rates and more sales.

3. 24/7 Availability:

   Unlike human customer support, a shopping agent is always available, providing instant responses to users' queries at any time of the day. This is particularly useful for global ecommerce platforms where users might be browsing at different times.

4. Efficient Handling of Queries:

   The agent can handle a large volume of queries simultaneously, reducing the need for human agents. It can answer repetitive questions like product details, availability, price, and shipping, freeing up customer support staff to focus on more complex issues and so on.

Integration of Shopping Agent to Netcore Unbxd console.

We support the following methods for integrating the Shopping Agent:

• API-driven approach
• React-based SDK Integration: For the prebuilt chat widget or React SDK, refer the React-based SDK integration.

API-Driven Implementation

This method allows for greater control and customization of the integration by making API calls from your backend or frontend to interact with the Shopping Assistant. It covers starting conversations, sending messages, streaming responses, surfacing page specific conversation starters, and listing or reloading a shopper's previous conversations.

Base URLs by Region

Use the base URL assigned to your site. Replace {BASE_URL} in the examples throughout this guide.

A site key belongs to one region. Calling a different regional host with that site key will not work.

Authentication

Every request must include the API token:

x-unx-sa-token: {YOUR_API_TOKEN}

Authentication failure behavior: a missing or invalid token returns HTTP 200 with Content-Type: text/plain and the body No soup for you!. Always validate the response content type before parsing JSON.

• Keep the token on your backend.
• Do not expose it in browser JavaScript, mobile application bundles, or public repositories.
• Request token rotation or revocation from the Netcore Unbxd AI team.

Core Concepts

The assistant stores conversation context server side. Send only the new message on each turn. Previous messages, searches, and displayed products are retained automatically.

API Reference

Common conventions: all requests require the x-unx-sa-token header, sitekey, and uid. Conversation scoped calls also require conversationid. Keep identifiers in the path or query string, not in request bodies.

Start a Conversation

Purpose: Creates a new conversation and returns its ID. Call this for the shopper's first message or when they choose "New chat."

Endpoint:

POST {BASE_URL}/v1/sites/{sitekey}/conversation?uid={uid}

The request has no body.

Example request:

POST {BASE_URL}/v1/sites/your_site_key/conversation?uid=shopper-123
x-unx-sa-token: {YOUR_API_TOKEN}

Successful response (200 OK):

{ "conversation_id": "6f1c2a8e-3b7d-4f0a-9c55-1e2d3f4a5b6c" }

Use the returned conversation_id for every subsequent message in this chat thread.

Send a Message

Purpose: Sends a shopper message and returns the complete assistant response.

Endpoint:

POST {BASE_URL}/v1/sites/{sitekey}/conversation/{conversationid}/chat?uid={uid}

Example request:

POST {BASE_URL}/v1/sites/your_site_key/conversation/6f1c2a8e-3b7d-4f0a-9c55-1e2d3f4a5b6c/chat?uid=shopper-123
x-unx-sa-token: {YOUR_API_TOKEN}
Content-Type: application/json
 
{ "message": "I need running shoes under $100" }

Image search

Visual search must be enabled for your site. The image field accepts a public image URL, a data URL, or plain base64. Always include a text message.

{
  "message": "Do you have shoes like this?",
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

• Public URLs must be direct image links accessible without authentication.
• Resize images to approximately 1,024 pixels on the longest side.
• Compress images to reduce latency. JPEG quality around 80 is a practical starting point.
• Use a data URL when the image is available only on the shopper's device.
  Shopper selected filters

Copy the exact field and selected option from the latest response. Send only the new selection; earlier filters remain in conversation context.

{
  "message": "Nike",
  "filters": [
    { "field": "brand", "options": ["Nike"] },
    { "field": "color", "options": ["Black"] }
  ]
}

• Use one selected value per field.
• Several fields can be sent together.
• Values are strings, including sizes and price ranges.
• Always include message, even when the shopper only taps a chip.
  Integration metadata

Use metadata for rules applied by your integration, not for shopper selected refinements.

{
  "message": "Show me running shoes",
  "metadata": [
    {
      "name": "fields",
      "value": ["uniqueId", "title", "price", "imageUrl", "productUrl", "rating"]
    },
    {
      "name": "filter",
      "value": ["availability:\"true\"", "price:[10 TO 100]"]
    }
  ]
}

metadata applies only to the current message. Send it again whenever the same rule is required. A supplied filter replaces the site's default search filter, so repeat any default rules you still need.

Response

Example response:

{
  "message": "Here are some lightweight running shoes under $100...",
  "products": [
    {
      "uniqueId": "SKU-1001",
      "title": "Air Glide Runner",
      "price": 89.99,
      "imageUrl": "https://...",
      "productUrl": "https://..."
    }
  ],
  "filters": [
    { "field": "brand", "options": ["Nike", "Adidas", "Asics"] }
  ]
}

• Display message as the assistant chat bubble.
• Render products as product cards.
• Render filters as refinement chips or dropdowns.
• Send the next message to the same endpoint with the same conversation_id.

Send a message with streaming

The streaming endpoint uses Server-Sent Events and provides progress updates before the final answer.

Endpoint:

POST {BASE_URL}/v1/sites/{sitekey}/conversation/{conversationid}/chat/stream?uid={uid}
Accept: text/event-stream

Request parameters and body are identical to the non-streaming chat endpoint.

data: {"message":"Searching for best-selling trail running shoes..."}
data: {"message":"Comparing the top two options..."}
data: {"message":"Here is how the two compare...","products":[...],"filters":[...],"table_info":[...],"show_products":true}
event: complete
data: {}

• Parse each line beginning with data: independently.
• Browser EventSource supports GET only; use fetch() or a POST capable SSE client.
• If the connection ends before complete, treat the turn as failed.
• Once the stream starts, failures arrive as events rather than HTTP status changes.

Conversation starters

Returns suggested questions and, optionally, a welcome message for the page the shopper is viewing.

Endpoint:

POST {BASE_URL}/v1/sites/{sitekey}/conversation/{conversationid}/questions?uid={uid}

{
  "pagetype": "pdp",
  "metadata": { "uniqueId": "SKU-2040" },
  "welcome_message": true
}

Response:

{
  "welcome_message": "Hi! Looking at the Pegasus Trail GTX? I can help with sizing, comparisons or matching gear.",
  "questions": [
    "Is this shoe true to size?",
    "What socks go well with these?",
    "How does it compare to the Terrex Agravic?"
  ]
}

List conversations

GET {BASE_URL}/v1/sites/{sitekey}/conversations?uid={uid}

Returns the shopper's past conversations:

{
  "conversations": [
    {
      "conversation_id": "6f1c2a8e-3b7d-4f0a-9c55-1e2d3f4a5b6c",
      "created_at": "2026-10-14T09:21:07Z"
    }
  ]
}

Get conversation history

GET {BASE_URL}/v1/sites/{sitekey}/conversation/{conversationid}?uid={uid}

Returns messages oldest first. Add products=false when product cards are not required and a smaller response is preferred.

[
  { "role": "user", "message": "I need running shoes under $100" },
  {
    "role": "assistant",
    "message": "Here are some lightweight running shoes under $100...",
    "products": [
      { "uniqueId": "SKU-1001", "title": "Air Glide Runner", "price": 89.99 }
    ],
    "filters": [
      { "field": "brand", "options": ["Nike", "Adidas", "Asics"] }
    ]
  }
]

Data objects

Filter

A refinement returned with assistant replies or sent when a shopper selects a refinement.

{ "field": "color", "options": ["Black", "Navy"] }

Product

Product fields mirror your catalog feed. The exact fields depend on site configuration, so integrations should handle missing fields safely.

Table

Structured information such as product comparisons or size guides.

{
  "title": "Size guide",
  "type": "product_details",
  "data": [
    { "US": "8", "UK": "7", "EU": "41" },
    { "US": "9", "UK": "8", "EU": "42.5" }
  ]
}

Errors and Troubleshooting

Non-streaming errors return JSON:

{
  "Message": "bad request",
  "Code": 400,
  "Error": "uid parameter is required: bad request"
}

Common 400 causes

Frequently Asked Questions

Q. Do I need to send previous messages with each request?
A. No. The assistant stores conversation context server side, so send only the new message on each turn.

Q. How long are conversations kept?
A. Conversations are kept indefinitely for now. This is expected to change to a 3 to 6 month retention window in a future release.

Q. Can shoppers upload photos?
A. Yes, either as a public image URL or as base64 image data in the image field. See Image search above.

Q. Why is the products array empty?
A.products is filled in once the response comes back. It is a list of dictionaries, and each dictionary's fields can vary from client to client, since product fields mirror each site's own catalog configuration.

Q. Which base URL should I use?
A. It depends on your site's region. US sites use gus, APAC sites use aapac, UK sites use auk, and ANZ sites use ganz. See Base URLs by region above.

Q. Can I call the API directly from a browser or mobile app?
A. Yes, you can call it directly from a browser or mobile app.

Q. How do I track clicks, carts, and conversions?
A. This needs a separate analytics integration; it does not come through the chat metadata field documented above. Analytics tracking comes out of the box with the React SDK implementation.