Shopping Assistant

Overview

The Shopping Assistant API enables integration of Netcore Unbxd's conversational AI into websites, mobile applications, and other customer-facing channels. It allows shoppers to discover products using natural language queries, refine search results, compare products, and retrieve relevant product recommendations through conversational interactions.

The API supports conversation management, message exchange, streaming responses, contextual conversation starters, and conversation history retrieval.

Key Capabilities

Conversation Management: Create conversations and maintain context across multiple messages.
Conversational Product Discovery: Process natural language queries and return relevant products from the product catalog.
Product Refinement: Apply filters such as brand, color, size, and price to narrow product results.
Visual Search: Accept product images through public URLs or Base64-encoded image data, when visual search is enabled for the site.
Product Comparison: Return structured comparison tables and product details where applicable.
Streaming Responses: Stream assistant responses and progress updates to improve the shopping experience.
Contextual Conversation Starters: Retrieve suggested questions based on the shopper's current page, including home, search, category, product detail, and cart pages.
Conversation History: Retrieve previous conversations and their messages to support continued interactions.

Available Endpoints

The Shopping Assistant API provides the following endpoints.

Endpoint	Method	Description
Start a Conversation	`POST`	Creates a new conversation and returns its conversation ID.
Send a Message	`POST`	Sends a shopper message and returns the assistant's complete response, including products and filters.
Send a Message (Streaming)	`POST`	Streams progress updates and the final assistant response.
Conversation Starters	`POST`	Returns suggested questions and an optional welcome message based on the current page context.
List Conversations	`GET`	Retrieves a shopper's previous conversations.
Get Conversation History	`GET`	Retrieves messages and associated product information from a conversation.

Prerequisites

Before using the Shopping Assistant API, ensure the following requirements are met:

The Shopping Assistant feature is enabled for the site by the Netcore Unbxd Business Team.
A valid Site Key is available.
An API token is obtained from the Netcore Unbxd AI team.
The correct regional base URL is configured for the site.

Base URLs

Use the base URL corresponding to the region in which the site is provisioned.

Region	Base URL
United States	`https://gus.assistant.unbxd.io`
United States (Alternate)	`https://aus.assistant.unbxd.io`
United Kingdom	`https://auk.assistant.unbxd.io`
Asia Pacific (APAC)	`https://aapac.assistant.unbxd.io`
Australia and New Zealand (ANZ)	`https://ganz.assistant.unbxd.io`

The site key is associated with a specific region. Requests must be sent to the corresponding regional base URL.

Authentication

All API requests require the x-unx-sa-token header containing a valid API token.

x-unx-sa-token: {YOUR_API_TOKEN}

The API token must be stored securely on the backend and must not be exposed in browser-side JavaScript, mobile application bundles, or public repositories.

Important: An invalid or missing token returns HTTP 200 with a text/plain response containing No soup for you!. Validate the response Content-Type before parsing the response body.

Common Request Parameters

Parameter	Location	Description
`sitekey`	Path	Identifies the site associated with the request.
`uid`	Query	Identifies the shopper and associates conversations with the same user.
`conversationid`	Path	Identifies the conversation thread for conversation-specific operations.

The sitekey and uid parameters are required for all endpoints. The conversationid parameter is required for conversation-scoped endpoints.