Placeholders

Placeholders are values that are not fixed, but vary between users, bots, and across time. They allow bot designers to specify messages that are dynamically instantiated at run time, such as "Hello ${user.firstName}. It is ${time.now} – about time to search for a new bike!".

The general format for placeholders within text is ${...}.

The following placeholders are at your disposal when building bot messages:

  • All context parameters with read permission. For example:

    • ${global.label} with label being the label of any global context parameter you defined in the bot.
    • User information such as ${user.firstName} and ${user.lastName}.
    • ${forms.name.field} with name being the name of the form filling game, and field the label of the form field.

  • ${label} with label being the label of any context parameter you defined in the game you're working on. For example, if you're working on a Generic game that has a context parameter lastMentionedTopic, you can use ${lastMentionedTopic} in any bot message. If you use ${label}, the game context is checked first, and if it has no such parameter, then the global context is used. And ${label} often also has a specific meaning in particular places, e.g. when referring to attributes of a content object in a result selection, or to parts of an API response.

  • ${data.type.count} with type being any available content object type. This allows, for example, for building messages like "I already know ${data.Planet.count}" planets!

  • ${data.id(<id>).<attribute>} and ${data.id(<id>).<attribute>.count}, where <attribute> is the label of an attribute of the target object, and <id> is one of the following:

    • a specific content object ID
    • a context parameter (for example global.myObjectId)
    • a slot label (if the content object ID is provided in a slot of the intent the bot is reacting to)
    • SALIENT:<type>, for example SALIENT:Planet
    • options of the above, written as ...|..., for example ${data.id(id=|SALIENT:Planet).distanceFromSun} will retrieve the value of the attribute distanceFromSun of the object with the ID provided by the id= slot or, if there is no such slot filled, with the ID of the salient object of that type.

  • ${date.expression} and ${time.expression} with expression being any Mercury.ai date or time expression. (For a complete definition of the format, please get in touch with the support.) The probably most useful examples are ${time.now} and ${date.today}, but you can also do things like ${date.shift today - 1 day} for yesterday's date, ${time.shift now + 1 hour} for in one hour, or ${date.next(Monday)} for next week Monday.

In addition, if you specify a result selection in a Content Object Search game, you can refer to attributes of the content objects that will be presented, in particular ${id} and ${name} as well as any attribute you specified in the content section.

When specifying an API request body in a Form Filling game, the form field placeholders are also available in the form ${field} (in addition to the more laborious ${form.name.field}).

Replacement syntax

Especially in the case of placeholders that stand for values of content object attributes, it might happen that the value is not the representation you want to include in a message. In this case, you can use the following replacement syntax: ${placeholder[value 1: replacement 1, value 2: replacement 2]}. You can use quotes around values and replacements (and you have to do so, when your value or replacement contains a colon, comma, or double quotes).

Values for which no replacement is specified will be displayed as they are. Alternatively, you can include an else clause, as well as an is-set clause (that is picked if any value is set) and an is-not-set clause (that is picked if no value is set).

If you want to include the actual value in the else, is-set or is-not-set clauses, you can use <_> as placeholder. See examples below.

Here are some examples:

  • This is ${difficulty[1: a bit, 2: rather, 3: very]} difficult.
  • This recipe is ${vegetarian[true: vegetarian, false: not vegetarian]}.
  • The planet has ${moons[1: one moon, else: several moons]}.
  • The planet has ${moons[1: one moon, else: <_> moons]}.
  • Your score is ${score[is-set: <_> points, is-not-set: nothing]}. (Note that Your score is ${score[is-set: <_> points, else: nothing]}. will not work.)
Next
Bot Anlegen