Catalogue, basket and shop connection

The catalogue is the list of products your assistant knows about: anything not listed there, it will not mention. You maintain it by hand, import it as a JSON list or have it synchronised from a connected shop. The Search the catalogue tool pulls products from it and shows them as cards in the conversation, and the Hand over basket tool puts together a basket that your shop collects with a pickup token. This page covers the catalogue, the shop connection, both tools and the pickup, with their fields, limits and messages.

Where to find it

In the app, the catalogue sits in the Triggers group under Tools (app.xicbot.de/werkzeuge), on the Catalogue tab. At the top it reads “What the assistant may name. What is not listed here, it does not know.”, followed by the Shop connection box, the Products list, the Add product form and the Import box. You also create the Search the catalogue and Hand over basket tools under Tools, as described in Tools. Handed-over baskets appear under Cases on the Baskets tab, see Appointments and cases.

Roles and plan

With the Read role the product form is locked and the page says: “With the Read role this area is view-only. Changes need at least the Edit role.” Each product shows View instead of Edit, and the Import box is missing. If no shop is connected yet, users below Administration see “Administrators of this account can connect a shop.” Which role may do what is explained in Team and roles.

Product fields

You create a product with Add product and open an existing one with Edit. Edit scrolls the form into view and moves the focus to its heading “Edit: …” with the title. Save stores it (“Saving …”); the form is then empty, “Saved: …” with the title appears next to the button, and the focus is on the product’s Edit button in the list. Cancel discards your input and returns the focus there.

Viewing, changing and deleting products

• The Products list is sorted by title and shows the title, identifier and price of each product, or a dash without a price. An unavailable product carries the suffix “· not available”.
• A product from the connected shop also carries “from the shop · synced …” with the date and time of its last sync.
• Above it, the total appears as “in the catalogue: …”, during a search “… matches of … in the catalogue”, together with the range shown, for example “1–50 shown”. Each page holds 50 products; with more, Back and Next turn the pages, with “Page 1 / 10”.
• The search field takes up to 120 characters and finds products whose title or identifier starts with the text you enter; the hint below the field says the same. A new search starts on page 1.
• While loading it says “Loading …”. If the request fails, “The list could not be loaded.” appears with a Load again button; an empty catalogue shows “The catalogue is empty.”, a search without matches “No product whose title or identifier starts with “…”.”
• Delete asks “Delete this product from the catalogue?” with Delete and Cancel; afterwards “The product has been deleted.” appears below the list heading, and the page reloads so that the next product moves up.
• If a product has been deleted in the meantime, for example in another window, the page reports “This entry no longer exists. Reload the page to see the current state.” when saving or deleting.
• The form rejects an identifier that is already taken with “This identifier already exists in the catalogue.”

Import

The Import box takes a list in JSON format: “A list in JSON format, at most 500 rows per run. Existing identifiers are updated, not duplicated. If an entry carries the identifier of a product from the shop, the next sync overwrites its synchronised details.” Paste the list into the text field and click Start import. Each entry is one product with the field names from the table below.

[
  {
    "external_id": "MUG-01",
    "title": "Stoneware coffee mug",
    "price_cents": 1490,
    "list_price_cents": 1890,
    "currency": "EUR",
    "image_url": "https://shop.example.com/images/mug-01.jpg",
    "product_url": "https://shop.example.com/mug-01",
    "is_available": true,
    "rating_tenths": 45,
    "rating_count": 12,
    "delivery_days": 2,
    "features": ["dishwasher safe", "300 ml"],
    "accessories": ["COASTER-01"],
    "action": "product"
  }
]

• One run takes at least one and at most 500 entries. Split larger catalogues across several runs.
• All or nothing: if a single entry is invalid, the run writes none.
• An existing identifier is updated and a new one is created. Afterwards the box reports next to the button, for example, “new: 3, updated: 12, in the catalogue: 240”.
• If the input is not JSON or not a list, “The input is not valid JSON.” appears and nothing is sent.
• Importing, creating and changing products as well as saving, checking and syncing the shop connection share a limit of 20 requests per minute per signed-in user.

Shop connection

Instead of maintaining the catalogue yourself, you can connect a shop whose sales channel offers a Store API with an access key. The catalogue is then synchronised every hour, and on every product search the assistant re-reads price and availability from the shop. The connection only reads: nothing is written to the shop. Nothing needs to be installed in the shop for this; the address and access key of the sales channel are enough. The widget goes into the shop with the embed code, as on any other website, see Embed the widget.

Setting up the connection

1. 1

   Step 1

   Get the key

   You will find the access key in your shop administration under the sales channel the assistant should read.

2. 2

   Step 2

   Enter and save

   Enter the Shop address and Access key and click Save. The key field stays empty afterwards; only “…” followed by the last four characters is shown.

3. 3

   Step 3

   Check the connection

   Check connection (“Checking”) reads the currency and one product, with a deadline of 5 seconds. Success reports “The connection works. The shop prices in …”, an empty sales channel “The connection works (…), but the sales channel shows no products.” The server rejects more than three checks per minute per account.

4. 4

   Step 4

   Start the first sync

   Sync now queues a sync: “The sync has been queued.” or, if one is already waiting, “A sync is already waiting.” The display then checks every 3 seconds, up to 100 times, and reloads the product list.

Connection status

With the Administration role, below are the buttons Sync now (disabled while a sync is running or the connection is paused), Check connection, Edit and Disconnect. If the state could not be loaded, “The current state could not be loaded.” appears with Load again; without a connection it says “No shop is connected yet.”

What the sync does

• Every hour at minute 41 a sync is queued for each switched-on connection of an active account whose plan includes the shop connection. A waiting or running sync is not duplicated, and a manual sync takes precedence.
• Manual syncs are possible at most every 15 minutes; the regular sync continues independently.
• Products are read in pages of 100, at most 100 pages, so up to 10000 products. If the shop has more, the run counts as incomplete: what was read is taken over, missing products are not withdrawn.
• Each request to the shop has 20 seconds, the whole sync 300 seconds. The sync does not follow redirects.
• Products with variants count as containers and are skipped; each variant comes in as its own product, with the variant options in brackets after the title.
• Matching uses the shop's product ID. A product without a shop link whose Identifier equals the article number of a shop product is taken over and belongs to the sync from then on, so the first sync does not duplicate an imported catalogue.
• Products without a shop link whose number the shop does not list are left untouched.
• Only after a run that has read all pages of the shop are shop products that no longer came back set to unavailable as withdrawn. Nothing is deleted.
• If the sync fails, the existing catalogue stays unchanged. If the shop returns no products although it had some before, the catalogue also stays unchanged.

Connection messages

Prices and availability from the shop

If a shop is connected and switched on and your plan includes the shop connection, the assistant re-reads the price and availability of the products that come from the shop on every product search and every basket change; for the cards of the product search it also re-reads the list price and delivery time. The shop has 3 seconds for this, establishing the connection 2 seconds. Nothing is written in the process, neither to the shop nor to the catalogue.

Product search in the conversation

You create the Search the catalogue tool under Tools. It only reads; it runs without confirmation if its Approval is set to without asking. For a new tool the form suggests with confirmation. The assistant passes a search term, identifiers from an earlier search or both, plus one of four forms and the number of hits. The preview reads “Search catalog for: …” in an English conversation and “Im Katalog suchen nach: …” in a German one.

• Named identifiers come first; hits for the search term then fill up to the requested number. Without a term and without an identifier there is no search; the assistant is told that it cannot search without a search term.
• The search looks in the title and the description.
• Only products set to Available are found. An identifier that is not in the catalogue does not appear in any form, not even as an accessory.
• If nothing is found, the widget shows no card, and the assistant is told that the catalogue has nothing on it and that it must not invent a product or price.
• A separate tool reads the stock level of a product: Read stock level from the tool kit; it also only reads and runs without confirmation if its Approval is set to without asking.

Product cards

Basket in the conversation

The Hand over basket tool puts together a basket during the conversation. Every call changes something and therefore needs the visitor's confirmation: the widget shows the proposal with Confirm and Reject. A proposal that stays unconfirmed for 60 minutes expires; after that it reads “This suggestion was not confirmed in time, so nothing was carried out. Just ask again.” How confirmations work in the conversation is explained in Chat in the widget.

• An item holds 1 to 99 units; more is capped at 99.
• Every item needs an Identifier from the catalogue. Every change recalculates the whole basket against the catalogue, and with a connected shop against the prices the shop currently states.
• A product the shop currently does not list as available is not added to the basket; the assistant is told which one it was.
• Every change after set writes to the same basket, and the pickup token stays the same.
• If the same confirmed call runs a second time, the basket does not change again.
• After every change the widget shows the items, Subtotal (only if it differs from the total), Coupon (only with a discount), Shipping (“free” at 0), Total, the amount left until free shipping and, with a handover address starting with http:// or https://, the Continue button.

Handover to the shop

1. 1

   Step 1

   Set the address

   On the Hand over basket tool, enter the Address for the basket handover: the address of a page in your shop, such as https://shop.example.com/basket, at most 500 characters.

2. 2

   Step 2

   Visitor clicks Continue

   The Continue button opens this address in a new tab and appends token= with the pickup token, using ? or, if the address already has a query, &. The token consists of 40 random letters and digits. Without an address, or with an address that does not start with http:// or https://, the widget shows no button.

3. 3

   Step 3

   The shop collects the basket

   Your page calls GET /api/v1/cart/pickup/{token} with the token and puts the items into its own basket. The pickup only reads; your page can repeat it within the deadline.

More on endpoints without sign-in is in Public API endpoints.

Shipping and coupons

In the Hand over basket tool, the Shipping and coupons section sets what the assistant uses when calculating the basket: “The assistant calculates the basket with these. Whether a shop honours a discount later is up to the shop.”

• At most 20 coupon codes per tool; you maintain the list with Add coupon and Remove coupon. A new entry starts with Percent, value 10, minimum value 0 and Active switched on. Without an entry, “No coupon code stored yet.” is shown.
• A basket carries at most one coupon. If a coupon no longer applies after a change, for example because the minimum value is no longer reached, it is dropped and the assistant receives the reason from the table below.
• The widget shows amounts in the currency of the basket, currently EUR; the messages to the assistant write them in German notation, with a comma before the cents, a dot as thousands separator and the euro sign after the amount.

API

Every endpoint under /api/v1/catalog needs a sign-in with a confirmed email address and a plan with the shop connection. The writing endpoints except the two delete endpoints share a limit of 20 requests per minute per signed-in user. Sign-in and keys are covered in API integration, the limits in API limits.

Frequent questions