Text feed is used to add additional content to the search or shopping assistant. It can be blog articles, web page content, or any arbitrary text-based content.

You can effectively build and maintain knowledge that is used by the Shopping Assistant and Search.

Currently, we support ingesting data by providing a publicly available JSON lines file. Each line of the file should be a valid JSON with the following content (note that the example is split into multiple lines for readability, but each record should get its own line):

{
  "id": "_product_withdrawal_information",
  "content_string": "Return option for certain children's hoodies\n\nDear customers, if you purchased these children's hoodies at one of our stores or at eshop.com, you have the option to return them.\nThe hoodies previously had drawstrings in the hood, which could be potentially dangerous for small children and do not meet safety standards. We apologize.\nThis notice is based on a safety test protocol. The mentioned products did not comply with the requirements of children's clothing safety standards related to cords and drawstrings.",
  "title": "Return options",
  "tags": [
    "assistant",
    "search"
  ],
  "advertised_url": "https://www.eshop.com/product-withdrawal-information/",
  "image_urls": [
    "https://www.eshop.com/img/blog/product-withdrawal-information.jpg"
  ],
  "properties": {
    "custom_property": "custom_value"
  }
}

Field Descriptions

id (mandatory)

Unique identifier of the text entry. This field should contain only characters (any case), numbers, dashes, or underscores.

content_string (mandatory)

The supplied searchable text. Ingestion processes this text, and search indexes and searches the content present in content_string.

Choose the scope and level of detail based on what you want users to find:

Supply the complete article when the whole article should be searchable and shortening it would omit information needed for that coverage. Avoid truncating text in a way that loses the intended search coverage.
A summary or abstract is also appropriate when it retains the necessary information and relevant keywords for the intended searches. Full article text is not required for every entry.

Balance search coverage against payload size: larger text payloads can affect search performance and feed download and synchronization performance.

Content that exists only on the page linked by advertised_url is not searchable. The linked page does not supply additional text for ingestion.

title (optional, recommended)

Title of the text or article. This will be used for search purposes and also will be used in the autocomplete to show the text to the user.

Filling this field is strongly recommended. Without this field, the text will not be properly shown to the user.

tags (optional)

List of strings that allow for more granular control over which use-cases this text will be used for. By filling this field, the ingested text will be taken into account only for use-cases specified here and will be ignored by other use cases.

We currently support the following values:

assistant which will enable the tags to be used by assistant use cases (assistant or similar)
search which will enable the tags to be used for the search use-case (e.g. search autocomplete feature)

Leaving this empty will allow the text to be used by all use-cases without limitation.

advertised_url (mandatory)

The destination link to the article or other source page. This field is link metadata, not a content source for ingestion. Depending on the nature of the text, it may lead to an FAQ page, an article, an item category listing, or similar.

The system does not download, crawl, or scrape the page at advertised_url. Supply the text you want searchable in content_string.

Our assistant may provide this URL to the user in case the conversation references some particular content (e.g., FAQ page). Similarly, this URL can be used as a clickable link for the user that will lead them to the blog article from the auto-complete search widget.

image_urls (optional)

List of absolute URLs of images belonging to this text, e.g. the cover image of a blog article. The first URL of the list is used as the preview image shown next to the text in the search results and in the search autocomplete.

The URLs must be publicly accessible (no login, no hotlink protection) and must point to the image of this particular text. Do not fall back to a site-wide banner or logo — a generic image repeated across all texts is worse than no image at all.

Images are currently used by the search use-case only, the shopping assistant does not display them.

Note that unlike properties, this field is replaced as a whole with every ingest, i.e., sending an empty list (or omitting the field) removes all images of the given text.

properties (optional)

Optional nested object with custom properties related to this text. These may be necessary to allow usage of special use-cases for particular business domains or providing additional information about the nature of the text that cannot be represented in the core fields.

Generally speaking, keep this empty, unless you are instructed to fill this by our integration team.

Note that we ingest properties in an incremental manner, i.e., in order to unset the field (set the value of an already ingested property to null) you are required to include the field in the update with a null value. Just omitting the field will NOT lead to its deletion in our systems.

Usage and examples

Complete article text

Supply the complete text when searches should cover the whole article. In this short article example, content_string includes both repotting instructions and aftercare; advertised_url is the destination for readers.

{
  "id": "repotting_houseplants",
  "title": "How to repot a houseplant",
  "content_string": "How to repot a houseplant\n\nRepot when roots grow through the drainage holes. Choose a pot with drainage holes that is 2 cm wider than the current pot.\n\nGently remove the plant, loosen crowded roots, and place it in fresh potting mix at the same depth as before. Water until excess water drains out.\n\nAfter repotting, keep the plant out of direct sunlight for a few days and wait four weeks before adding fertilizer.",
  "advertised_url": "https://www.example.com/articles/repotting-houseplants",
  "tags": ["search"]
}

Summary or abstract

A useful summary is valid when it covers the intended searches. This alternative retains information and keywords about when to repot, pot size, drainage, and potting mix. It omits aftercare, so those details will not be searchable even if they appear on the linked page. Choose one version for the feed based on the coverage you need.

{
  "id": "repotting_houseplants",
  "title": "How to repot a houseplant",
  "content_string": "Repot a houseplant when roots grow through the drainage holes. Choose a pot with drainage holes that is 2 cm wider, loosen crowded roots, and replant in fresh potting mix at the same depth.",
  "advertised_url": "https://www.example.com/articles/repotting-houseplants",
  "tags": ["search"]
}

Question and answer

If the assistant's answer is not precise, you can define the question and answer format and enrich the knowledge base.

{
  "id": "_payment_invoice",
  "content_string": "QUESTION: Can I pay by invoice? ANSWER: Yes, it is possible if your company is registered.",
  "advertised_url": "https://www.eshop.com/payments-information/",
  "tags": [
    "assistant"
  ]
}