Games

Games are the fundamental components that define the dialog behavior of your bot. Refer to the Games section of the platform documentation to get familiar with what games are and how they work.

Normalization of game names and intent labels

There is one important thing to know before starting: Game names and (both user and bot) intent labels are normalized to camel-case ASCII. For example, My label 1 will be normalized to MyLabel1.

  • Non-alpha-numeric characters are removed, in particular: []{}()<>:\"'«»!?;,.@#$%^*+=~/
  • Diacritics are removed.
  • Umlaute are replaced: ä becomes ae, ö becomes oe, ü becomes ue, and ß becomes ss.

In payloads you always need to use the normalized labels.

Listing all games for a given bot configuration ID

GET <base URL>/projects/<project id>/configurations/<configuration id>/games

Response:

{
  "success": true,
  "data": [
    "ID of one game",
    "ID of another game",
    ...
  ]
}

Creating a new game in a given bot configuration

POST <base>/projects/<project id>/configurations/<configuration id>/games

Example cURL:

curl -X POST -d @body.json --header "Authorization:Bearer <integration token>" --header "Content-Type:application/json" https://api.mercury.ai/v1/projects/<projectId>/configurations/<configuration id>/games/

Example body:

{
  "name": "ExampleGame",
  "description": "Created using the API",
  "type" : "Generic",
  "languages" : ["de", "en"]
}

Response:

{
  "success": true,
  "data": {
    "uuid": "<newly created game id>",
    "bot_uuid": "<configuration id>",
    "config": {
      "name": "ExampleGame",
      "description": "Created using the API",
      "type": "Generic",
      "gameSpecificConfiguration": null
    },
    "languages": [
      "GERMAN",
      "ENGLISH"
    ],
    "configId": "<configuration id>"
}

Editing a game definition

Acquiring a lock

When you want to edit a game, you first have to acquire a lock on the game.

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

cURL:

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

Response:

{"success":true}

Now you're the only party that can edit this game. No requests coming from a different authentication token will be accepted.

Once you acquired a lock, you can add user and bot intents, as well as clear all intents.

Committing the changes

Once you added all user and bot intents, you commit the changes. Note that your changes will not take place until this commit is successfully executed.

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

cURL:

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

Response:

{"success":true}

Deploying the bot

Once you want your changes to take effect in the bot, you need to deploy the bot. You can do so by specifying the stage you want to deploy. (Note that this has to be a Dev stage. You cannot deploy Test or Live stages; they have to be promoted.) If you leave out the stage information, the last deployed stage (either through the API or the Web App) is assumed to be the stage that you mean.

POST <base>/projects/<projectId>/configurations/{configId}/stages/{stageId}/deploy
POST <base>/projects/<projectId>/configurations/{configId}/deploy

Response:

{"success":true,"data":{"stage_uuid":"e59472fe-4fb3-4d6c-aa27-b9b121a5c513","deployed_at":"2019-08-19T14:22:01.000+02:00"}}

A successful response means that the deployment was successfully started. Since deployment can take a while, the API does not wait until the deployment has finished, so the response does not tell you whether the deployment has succeeded. You can see the status of the deployment in the Web App.