Getting started

The Mercury.ai platform offers services to create, manage, improve and analyze complex AI assistants. These services are accessible through our web application as well as a set of REST API endpoints.

The API follows a REST API architecture with JSON data formats using:

  • GET to access resources and perform queries. This method does not allow modifications.
  • POST to create or update resources. Creation is mostly performed by POSTing to a collections resource endpoint, e.g. https://api.mercury.ai/v1/library/
  • DELETE to delete resources.

Important: API requests must be made over HTTPS. Plain HTTP requests are unsupported and will fail as well as requests without a valid authentication key.

Setup

Before you can start using the Mercury.ai API, you must perform some preliminary steps to setup your account and create an API access token.

  1. Create your account on the Mercury.ai platform.
  2. Set up a bot project within your account.
  3. Create an API access token for your project on the Integrations page of your project's configuration settings.

Base URL

The current version of the API endpoints are accessible through a common base URL:

https://api.mercury.ai/v1

Authentication

The Mercury.ai API uses bearer tokens to authenticate requests. An API key can be created on the Integrations page of your project's configuration settings. The API key is bound to the user who created it and carries a subset of the permissions of that user.

Add an Authorization header to authenticate your request with the API key as bearer token:

Authorization: Bearer <API key>

Important: The key should be treated as a secret and should not be shared in publicly accessible areas.

Responses

If a request was successful, the response indicates this by means of a HTTP status 200 and a field "success": true in the response body. In addition, the response may contain a data field with the requested data.

In case of API errors, we use the corresponding HTTP response codes (e.g. 404 NOT FOUND) to indicate the error class and additionally provide a developerInfo field (indicating what the problem with the request was) and a messages field (a non-technical error message that can be handed to the user).

The general structure of the response body thus is as follows:

{
    "success": true,
    "data": {
        <JSON_RESPONSE>
    },
    "message": "A message that can be presented to a user",
    "developerInfo": "A message added in case of errors with technical details for debugging"
}

Common data types

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

DatatypeDescriptionExample
TimestampTimestamps are in UTC times in ISO 8601 format2007-12-24T18:21Z
LanguageLanguages are in ISO 639-1 formaten, 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>
  }
}
Next
Bot Anlegen