Content

Content object data is expected in the following general JSON format (all fields will be explained in more detail below):

{
  "type": <string>,
  "description": <string>,

  "languages": [<string>, ...],

  "apiUrl": <string>,
  "apiInterval": <number>,
  "updateMode": <update mode>,

  "signature": {
    "<attribute label>": "<attribute type>",
    ...
  },

  "data": [
    {
      "id": <string>,
      "name": <localized string>,
      "labels": {
        <language>: [<string>, ...]
      },
      "attributes": {
        "<attribute label>": <attribute value>,
        ...
      }
    },
    ...
  ]
}

Type

The type of the provided content objects is mandatory; it will serve as a unique identifier for this specific type of content objects throughout the bot. To this end it will be normalized, in particular removing all non-alpha-numeric characters. For example, Plug-in connector will be stored as PlugInConnector, Help desk: article will become HelpDeskArticle, and so on. You don't need to provide the type in normalized form, but you will see the normalized version whenever you have to select a content object type.

Description

The description is optional; it can be provided in order to give more context for everyone working on the project. The bot itself will not use the description.

Languages

The languages field expects an array of ISO 639-1 language codes, for example ["de", "en"], which specifies for which language versions the provided data is to be used. It could, for example, be that your bot either uses one datasource, which provides labels in English and French, or that the English version of your bot uses another datasource than the French version, each with content adapted to the particular market.

If you provide multilingual datasources, names and labels of content objects as well as language-specific data attributes can be provided as localized strings.

API configuration

The fields apiUrl, apiInterval, and updateMode are optional. They allow for specifying an API endpoint from which an updated version of the data will be pulled in regular intervals. Once new data is pulled, it will automatically be loaded in the bot.

  • The apiUrl specifies the URL which provides the updated data. It is expected to respond to a GET request with the above specified JSON format as body.
  • The apiInterval specifies after how many hours an update of the data is pulled. The value is expected to be an integer. We recommend update intervals that are multiples of 24 hours. Updates will then be scheduled so that they don't interfere with possible load peaks in the bot.
  • The updateMode can be either "update" or "replace". Currently only "replace" is supported, which is also the default value if none is provided. It means that the bot's datasource will be replaced by this new content.

Example:

{
  "apiUrl": "https://example.com/exports/bot-data",
  "apiInterval": 24,
  "updateMode": "replace"
}

Signature

The signature defines the attributes of the content objects together with the data type of their values. The signature is mandatory. It is not inferred from the data, and the bot relies on its presence at several points.

Each content object has an id, a name, and labels per default, so there is no need to include them among the attributes. For more details, see the Data section below.

For attributes, the value types are as described on the datatypes page, written as a String.

Example:

{
  "signature": {
    "nicknames": "List_String",
    "terrestrial": "Boolean",
    "moons": "List_Moon",
    "distanceFromSun": "NumberWithUnit"
  }
}

All attribute labels will be normalized in the same way as the content object type.

Data

Each data point specifies a content object, which has:

  • An ID. It is important that IDs are unique within the bot project, i.e. across all content object types. We recommend using UUIDs or other plain alphanumeric strings (including - and _). Please refrain from using special non-alphanumeric characters, especially ,, ., :, and ".
  • A name, which can be given as either a string or a localized string in case the name differs across languages (such as "Munich" vs "München"). If you provide just a simple string (such as "Freddy"), it will be taken as the name in all languages. The name is expected to be a canonical way of calling the object, and will be used for generation.
  • A list of labels per language. Labels are synonyms of the name and they will be used for interpretation. For example, you could have an ingredient with the name "Möhre" and two additional labels "Mohrrübe" and "Karotte".
  • Attributes, which are given as a key-value store, with the key being the attribute label. The values are expected to be of the type specified in the signature. If you find yourself in need of other nested structures as values, it's usually a sign that you should define another content object type.

Example:

{
  "id": "498b1479-0e06-4f31-bcff-0088cbedbc92",
  "name": {
    "de": "Erde",
    "en": "Earth"
  },
  "labels": {
    "de": [ "Blauer Planet" ],
    "en": [ "Blue planet", "Blue dot" ]
  },
  "attributes": {
    "type": "terrestrial",
    "moons": [ "0ae2122d-df14-4158-afcb-024861f5a1ee" ],
    "distanceFromSun": 1,
    "lengthOfDay": "24 hours"
  }
}