Common datatypes

There are some common datatypes that are used throughout the API. The following table describes those types and gives examples.

Datatype Description Example
Timestamp Timestamps are in UTC times in ISO 8601 format 2007-12-24T18:21Z
Language Languages are in ISO 639-1 format en, de

More complex types, used in game and content configurations, are described in the following sections.

Value types

The following value types are supported:

  • String is either a simple string or a localized string. Localized strings specify a string version per language, following the general form { languageCode: string }, for example { "de": "Erde", "en": "Earth" }.
  • Boolean comprises the two values true and false.
  • Number comprises all numeric values, usually either integers or doubles.
  • NumberWithUnit can be used for all numeric values with a unit. This is represented as a string, such as "23.5 degrees" or "9.81 km/s".
  • Date is a date in the format yyyy-mm-dd (or a Mercury data expression, which allows for dynamic dates such as today or next(sunday); for details please contact the support).
  • Time is a time in the format hh:mm:ss (or a Mercury time expression, which allows for dynamic times such as now plus 2 hours; for details please contact the support).
  • GeoLocation specifies coordinates by means of latitude and longitude. They are represented as strings such as (45.965, 63.305), with the first element being latitude and the second being longitude.
  • Intervals specify a range of values. They are specified in the format lowerBound...upperBound and include the upper bound. Intervals can comprise numbers, dates and times; the corresponding types are:

    • NumberInterval, for example "1...10" or "2.17...3.14"
    • DateInterval, for example "2019-01-01...2019-12-31"
    • TimeInterval, for example "01:00...09:30"
  • Any user-defined content object type, e.g. Movie, Car, Planet or Food.
  • Any quantified content object type. Quantified objects comprise a number or amount together with a content object ID. The type is specified as Quantified_xxx, for example Quantified_Ingredient. Values follow the format of Number and NumberWithUnit with an additional ID, for example "20 1f69d634-2a6e-40eb-b6b7-5d9bf516f767" or "1 kg 1f69d634-2a6e-40eb-b6b7-5d9bf516f767", where 1f69d634-2a6e-40eb-b6b7-5d9bf516f767 is the ID of a content object of the specified type.
  • Lists of the above types. When written as strings, list types are simply prefixed by List_, for example List_Number or List_Movie.

Types in game definitions always use a format that separates the value type from the information whether a single value is expected or a list of values:

{
  "type": <string>,
  "list": <boolean>
}

Intents

{
  "game": <string>,
  "intent": <string>,
  "slots": [
    {
      "label": <string>,
      "value": <string>
    }
  ]
}

Context updates

{
  "parameter": <string>,
  "operator": <string>,
  "value": <string>
}

Callbacks

{
  "trigger": <Intent>,
  "target": <Intent>
}

Data destinations

HTTP endpoints

{
  "type": "HTTP",
  "url": <string>,
  "method": "GET" | "POST",
  "headers": [
    {
      "key": <string>,
      "value": <string>
    },
    ...
  ],
  "data": <string>,
  "dataFormat": "application/json" | "application/x-www-form-urlencoded"
}

The url and data field are interpolated and can use placeholders.

Email

{
  "type": "EMAIL",
  "recipient": <string>,
  "subject": <string>,
  "body": <string>
}

The body field is interpolated and can use placeholders.

Bot messages

Bot messages can be specified in three ways. The NLG object is the canonical, most specific one:

{
  <ISO 639-1 language code>: {
    <channel>: [
      {
        "messages": [<Message>, ...],
        "callbacks": [<Callback>, ...]
      }
    ],
    ...
  },
  ...
}

Where channel is one of the following, according to the channels to which the bot is connected: "web", "app", "facebook", "whatsapp", "alexa".

The Message object follows the Mercury message format, but differs in the following aspects:

  • It has an additional attribute "delay", that specifies the number of milliseconds that the bot will wait before sending the message. Adding a delay to messages often makes them feel more natural.
  • There is an additional message type: SelectionTemplate. It works like a Selection, but specifies only two bubbles: The first one is the resultBubble, which is used as a template in order to generate the actual result bubbles based on the search results in a conversation. It thus should contain text that uses placeholders instead of specific content object information. The SelectionTemplate contains an additional attribute numberOfSlides, that specifies how many result bubbles will be generated. The second bubble is an optional moreBubble, which will be displayed if there are more results than contained in the selection. It should contain a button with a payload of the form { "game": "MySearchGame", "intent": "More" }, triggering the presentation of more search results.
  • Search games can use the additional button type QuickReplyAutogenerate. These buttons will be auto-generated dynamically, so they don't specify a text or payload. Instead they have an attribute maxCount for the maximal number of buttons to be generated. (It can be less if, for example, in the context of a search conversation, there are less options that still yield results.)

In addition to NLG objects, game configurations sometimes use abbreviated forms whenever we're dealing with simple text messages that are rendered in the same way in all channels. A MultilangString specifies one string per language:

{
  <ISO 639-1 language code>: <string>,
  ...
}

For example { "en": "Hi!", "de": "Hallo!", "fr": "Salut!" }.

A MultilangVariationString specifies several strings per language:

{
  <ISO 639-1 language code>: [
    <string>, ...
  ],
  ...
}

For example { "en": ["Hi!", "Hello!"], "de": ["Hallo!", "Hi!"], "fr": ["Salut!"] }.

When sending such a message, the bot picks one of the variants randomly.

User utterances are also often modeled as MultilangVariationStrings. They can have an additional field "canonical" for canonical utterances (used by the Active Learning game):

{
  <ISO 639-1 language code>: [
    <string>, ...
  ],
  "canonical": {
    <ISO 639-1 language code>: <string>
  }
}