Parameters are variables that the bot has extracted for use in actions. These can include values detected by the NLP engine, user metadata, and more.

📘

Note

The parameters expire after 24 hours.

Using parameters

The NLP (Natural Language Processing) can detect entities within the text, and the detected values can be used for cloud actions.

For example, if a user says, “I want to book a hotel in Amsterdam,” the NLP engine detects the city as a destinationCity. You can use the destinationCity entity in your cloud action to call an API.

📘

Note

Parameters usually work as lists (arrays). The NLP engine also detects multiple similar entities. For example, if I want to book a hotel in Amsterdam or Copenhagen, the NLP engine detects both cities.

Below is the code snippet for the city.

if(Array.isArray(payload.params.destinationCity)) {
    payload.params.destinationCity.forEach(city => {
        // Do something with the city
        // city.value (keyword of the entity)
        // city.match (matched word, could have misspellings etc)
    })
}

Location

When a user sends a location to the bot, the code action receives a collection of locations.

Below is the code snippet for the collection of locations.

if(Array.isArray(payload.params.location)) {
    payload.params.location.forEach(location => {
        // Do something with the location
        const { lat, long } = location.value
        // ..
    })
}

Multimedia Files

When a user sends an image, video, audio, or file to the bot, the code action receives a collection of media files.

Below is the code snippet for the collection of media elements.

// User shares an image
if(Array.isArray(payload.params.image)) {
    payload.params.image.forEach(image => {
        // Do something with the image
        const url = image.value
        // ..
    })
}

Sending Parameters

It is possible to explicitly define parameters, particularly when a user selects a button that triggers an event related to a specific product. To retrieve the details of that product, you may need to use a product ID to identify it.

For these scenarios, we offer a method to attach a parameter to UI elements such as Buttons, Quick Replies, and Actions.

Below is an example of how to create and attach a parameter to a UI element.

// Render a Button that triggers an event with a Param
const param = new Param('itemId', '332223323')

// Attach the param to the button
const button = new Button({
 label: 'More info',
 type: 'event',
 value: 'MORE_INFO',
 param
})

You can also attach multiple parameters:

// Render a QuickReply that triggers an event with Params
const shopId = new Param('shopId', '33211233')
const productId = new Param('productId', '123443211')

// Attach both params to the QuickReply
const quickReply = new QuickReply({
 label: 'Product details',
 type: 'event',
 value: 'PRODUCT_DETAILS',
 param: [shopId, productId]
})

You can also add the same parameters (category IDs) with multiple values:

// Render a QuickReply that triggers an event with Params
const categoryId1 = new Param('categoryId', '123')
const categoryId2 = new Param('categoryId', '456')

// Attach both params to the QuickReply
const quickReply = new QuickReply({
 label: 'Search more',
 type: 'event',
 value: 'PRODUCT_CATEGORY_SEARCH',
 param: [categoryId1, categoryId2]
})

The code below is an example of sending a button widget with parameters:

async payload => {

  // Send a message with a buttons template
  const buttons = new Buttons("Vintage bikes and more Ltd.")

  // Add a button
  .addButton(new Button({
    label: "View location",
    type: "event",
    value: "COMPANY_INFO",
    param: new Param('companyId', '122')
  }))

  // Add another button
  .addButton(new Button({
    label: "Special offers",
    type: "postback",
    value: "Show me special offers",
    param: new Param('companyId', '122')
  }))

  return new Message('Vintage bikes and more Ltd')
    .addResponse(buttons)
}

Changing Parameters

With code actions, you can manipulate the parameters that the bot receives. This can be performed by returning the params object.

Modifying a Parameter

The below example shows how you can modify an existing parameter by changing the value inside the returned object.

async payload => {
  return {
    params: {
      // Using a spread operator, we add all provided params in the result
      ...payload.params,
      // Now we override the destination_city param
      destination_city: [{
        value: `ams`,
        match: 'Amsterdam'
      }]
    }
  }
}

📘

Note

As per the above example, make sure to always return other parameters as per your preference.

Methods to Clear Parameters

There are three ways to clear parameters.

1. Using a reset within a design tool
2. Resetting parameters using a webhook
3. Resetting parameters using a code action

Clearing a single Parameter

The below example removes a single parameter:

async payload => {
  return {
    params: {
      ...payload.params,
      // Only remove the arrival_city param
      arrival_city: null
    }
  }
}

Clearing all parameters

It's also possible to clear all parameters from context using a code action.

Simply return a null as the value for params.

Use a code action to clear all parameters from context. This returns a null as a parameter value.

async payload => {
  return {
    params: null
  }
}