Config

{
  "name": <string>,
  "description": <string>,
  "type": "Generic"
  "gameSpecificConfiguration": {
    "contextParameters": [
      {
        "label": <string>,
        "description": <string>,
        "initialValue": <string>,
        "type": <Type>
      },
      ...
    ],
    "userIntents": [
      {
        "label": <string>,
        "utterances": <MultilangVariationString>,
        "slots": [
          {
            "label": <string>,
            "type": <string>
          },
          ...
        ],
        "reactions": [
          {
            "parameter": <string>,
            "operator": <string>,
            "value": <string>,
            "botIntent": <string>,
            "contextUpdates": [         # legacy
              <ContextUpdate>, ...
            ]
          },
          ...
        ]
      },
      ...
    ],
    "botIntents": [
      {
        "label": <string>,
        "nlg": <NLG>,
        "apiCall": <ApiDefinition>,  # optional
        "contextUpdates": [
          <ContextUpdate>, ...
        ]
      },
      ...
    ]
  }
}

Intent-wise update

Instead of uploading a complete game configuration, you can also update generic games by adding or deleting single intents.

Adding a user intent

POST <base>/projects/<projectId>/configurations/<configuration id>/games/<game id>/intents/user

cURL:

curl -X POST -d @user_intent.json --header "Authorization:Bearer <integration token>" https://api.mercury.ai/v1/projects/<projectId>/configurations/<configuration id>/games/<game id>/intents/user/

Example body:

[{
  "group": "Small Talk",
  "label": "Greeting",
  "reactions": [
    {
      "botIntent": "Hi"
    }
  ],
  "utterances": {
    "de": [
      "Hallo",
      "Hi",
      "Was geht?"
    ],
    "en": [
      "Hi",
      "Whats up?"
    ]
  }
}]

• The label is the intent's unique identifier.
• The group can be used for organizational purposes but plays no role in the bot.
• The reactions list should only contain one element. (It is a list because there can be different bot reactions depending on specific context conditions, but the definition of context parameters is not yet available via the API.)

The body can also be a list of user intents.

Response:

{"success":true}

Adding a bot intent

POST <base>/projects/<projectId>/configurations/<configuration id>/games/<game id>/intents/bot

cURL:

curl -X POST -d @bot_intent.json --header "Authorization:Bearer <integration token>" https://api.mercury.ai/v1/projects/<projectId>/configurations/<configuration id>/games/<game id>/intents/bot

Example body:

[{
  "group": "",
  "label": "Hi",
  "contextUpdates": [],
  "nlg": {
    "de": {
      "richtext": [
        {
          "messages": [
            {
              "type": "Bubble",
              "delay": 0,
              "template": "text",
              "attachments": [
                {
                  "role": "NONE",
                  "text": "Hey! :)",
                  "type": "Text",
                  "format": "PLAIN"
                }
              ]
            }
          ],
          "callbacks": []
        }
      ],
      "text": [
        {
          "messages": [],
          "callbacks": []
        }
      ],
      "voice": [
        {
          "messages": [],
          "callbacks": []
        }
      ]
    }
  }
}]

• Again, the label is the intent's unique identifier and the group plays no role in the bot.
• The contextUpdates list is empty, as context updates can not yet be defined via the API.
• The nlg field contains a list of variants per language and modality. The languages are expected in ISO 639-1 codes, and the available modalities are richtext for messengers (like Facebook messenger or WhatsApp), text for text-only channels (like SMS), and voice for voice channels (like Alexa or Google Home).
• The messages field is a list of variants (of which the bot picks one randomly), where each variant is a list of one or more messages. The message format is detailed in the section Bot Message Format below.
• The callbacks field refers to what is called global intents in the Web App. Reach out if you think you need this and are not sure how to use it. Otherwise you can safely keep it empty.

The body can also be a list of bot intents.

Response:

{"success":true}

Listing all intents

GET <base URL>/projects/<projectId>/configurations/<configuration id>/games/<game id>/intents

cURL:

curl --header "Authorization:Bearer <integration token>" https://api.mercury.ai/v1/projects/<projectId>/configurations/<configuration id>/games/<game id>/intents

Response:

{
  "success": true,
  "data": {
    "userIntents": [
      ...
    ],
    "botIntents": [
      ...
    ]
  }
}    

Deleting all user and bot intents

DELETE <base>/projects/<projectId>/configurations/<configuration id>/games/<game id>/intents

cURL:

curl -X DELETE --header "Authorization:Bearer <integration token>" https://api.mercury.ai/v1/projects/<projectId>/configurations/<configuration id>/games/<game id>/intents

Response:

{"success":true}