Let shoppers search, compare, and discover products by chatting in natural language on your storefront.
Beta ReleaseThis API is currently in beta and is subject to change. Endpoints, request and response formats, and behavior may change without prior notice as the API evolves. We recommend against relying on it for production-critical workloads until it reaches general availability.
To join the beta, reach out to your Customer Success Manager.
Conversational Assistant Overview
The Conversational Assistant API powers a chat experience on your storefront. Within a single chat session, shoppers can ask questions in natural language, search for products, compare products, find similar items, get inspiration, and search by image.
How to Use This API
Follow the steps below in order to interact with the assistant correctly.
Step 1: Check Status
Status API: GET /v1/chat/status
Before starting a session, verify the assistant is available for your site. Pass siteId as a query parameter.
Only start a session when chatbot.status.enabled is true. A 200 response can still return enabled: false, with the reason in chatbot.status.disableReason:
disableReason.code | Meaning |
|---|---|
CS_001 | The site configuration could not be loaded |
CS_004 | The chatbot is disabled for the site. The Init API returns HTTP 403 |
CS_005 | The chatbot is not published on the storefront |
The response also includes features.imageSearch.enabled (see Step 3), plus an optional chatbot.welcomeMessage and chatbot.suggestedQuestions for your chat UI.
If the site has used up its monthly session quota, the Status API returns HTTP 429 with error code CS_002 (see Session Limits).
Step 2: Initialize a Session
Init API: POST /v1/chat/init
Create a new chat session by calling /v1/chat/init with the siteId and an InitChatRequest body. The body's userId is required; use the Beacon userId. The response contains a chatSessionId and sessionEndTime.
The chatSessionId must be passed to all subsequent calls.
The sessionEndTime indicates when the session expires. Chat sessions remain valid for 24 hours from the time they are created.
Step 3 (Optional): Upload an Image
Upload Image API: POST /v1/chat/upload-image
To perform a visual/image search, upload an image via /v1/chat/upload-image with siteId and a multipart image file. The response returns an imageId to include in the subsequent imageSearch send request.
The image must be JPEG, PNG, WebP, HEIC or HEIF, from 10 KB to 10 MB, and at least 224×224 pixels.
Only offer image search when features.imageSearch.enabled is true in the Status API response.
Step 4: Send Messages
Send API: POST /v1/chat/send
Send chat messages by calling /v1/chat/send with these query parameters:
- Required:
chatSessionId,siteId, and the Beacon tracking parameterspageUrl,sessionIdandpageLoadId. A request missing any of them is rejected with HTTP400, and theerrorMessagenames the missing parameter. - Always send:
userId, using the BeaconuserId. The API doesn't reject requests without it, but it's used for Beacon events. - Optional:
shopperIdandcurrency.
The tracking parameters should match the values in your Beacon context object. See the Tracking Overview.
The requestType field in the request body determines the type of interaction:
requestType | Description |
|---|---|
general | General conversational message |
productQuery | Ask questions about a specific product |
productSimilar | Find products similar to a given product |
productComparison | Compare two or more products |
productSearch | Search for products by query or filters |
inspiration | Get curated inspiration or style recommendations |
imageSearch | Search by image (requires imageId from Step 3) |
content | Retrieve content-based answers |
Each response contains a data array of messages. Messages are polymorphic, discriminated by the messageType field:
messageType | Contents |
|---|---|
text | A conversational text reply |
productAnswer | An answer about a specific product |
productRecommendation | Recommended products for a source product |
productComparison | A comparison of two or more products |
productSearchResult | Search results with filters, sorting and products |
inspirationResult | Curated inspiration sections with products |
content | A content-based answer |
topicDrift | The conversation has drifted off-topic, with a recommended action |
errorResponse | The assistant couldn't complete the request (see Error Handling) |
Ignore any messageType you don't recognize, as new types may be added.
Intended Usage
This API is intended for frontend (client-side) integration only. Requests should be sent directly from the shopper's browser or app, not proxied through a backend server.
To protect against abuse, rate limits are enforced per client IP address. Server-to-server integrations route all shopper traffic through a single IP address and will quickly exceed these limits, resulting in HTTP 429 responses.
Rate Limits
POST /v1/chat/send is rate-limited to:
- 40 requests/minute per client IP address (burst 5)
- 100 requests/minute per
siteId(burst 20)
Requests exceeding either limit receive HTTP 429 Too Many Requests.
Session Limits
Each site has a configured monthly session quota. Once it is exceeded, the Status and Init APIs return HTTP 429 with error code CS_002, and no new sessions can be started until the quota resets. The Send API never returns CS_002, so sessions that already exist keep working.
A single user session can contain a maximum of 20 messages. The next message after that returns HTTP 200 with error code CS_003, and a new session must be started with the Init API.
Error Handling
Errors return an ErrorResponse body containing an errorCode and errorMessage.
Some errors from the Send API, such as
CS_003, are returned with an HTTP 200 status. Always check the response body for anerrorCode, not just the HTTP status.
| Error code | Returned by | Meaning | What to do |
|---|---|---|---|
CS_002 | Status and Init APIs, HTTP 429 | The site has exceeded its monthly session quota | Don't retry; the quota will not clear within a retry window. Hide or disable the assistant and try again later. |
CS_003 | Send API, HTTP 200 | The session has reached its 20-message limit | Start a new session with the Init API. |
CS_004 | Init API, HTTP 403 | The chatbot is disabled for the site | Don't retry. Hide the assistant, and start a session only when the Status API returns chatbot.status.enabled: true. |
CS_006 | Send API, HTTP 200 | The message was blocked by content policy restrictions | Show the errorMessage and ask the shopper to rephrase. The session continues. |
An HTTP 429 without an errorCode means a rate limit was exceeded. Wait a few seconds before sending the request again.
Errors in a successful Send API response
A 200 from the Send API comes back in one of two shapes. Check for errorCode to tell them apart:
ErrorResponsebody (errorCodeanderrorMessage, nodata): the message was not processed. HandleCS_003andCS_006as described above.ChatResponsebody (hasdata): the message was processed. If the assistant couldn't complete the request (for example, a search failure or an unsupported request such as checkout),datacontains anerrorResponsemessage. Show itserrorMessageto the shopper as an assistant reply. The session continues.
An empty data array isn't expected. If you get one, show a generic "please try again" message.
Analytics Tracking
Shopper interactions with products shown in the chat must be reported to Athos analytics using Beacon. Like the rest of this API, these events are in beta and may change before general availability.
See the Conversational Assistant Tracking Overview for setup, the IDs to collect, and when to send each event.
Next Steps
- Status API - Check that the assistant is available for your site
- Init API - Start a chat session
- Upload Image API - Upload an image for visual search
- Send API - Send chat messages
- Tracking - Report chat interactions with Beacon