Params are variables the bot has extracted that can be used in actions. These can be values detected by the NLP engine, metadata about users etcetera.

📘

Note

Params lifetime is 24h.

Using params

The NLP engine can for example detect entities within the text and the values of those can be used within actions. If a user says: I want to book a hotel in Amsterdam and the NLP engine detects Amsterdam as a destinationCity, you can use destinationCity in your action to call for example an API with this value.

📘

Note

Params are always lists (arrays).

The NLP engine can detect multiple similar entities, for example: I want to book a hotel in Amsterdam and Copenhagen.

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 shares a location, the action will receive a 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 shares an image, video, audio or file the action will receive a 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 Params

It’s also possible to explicitly define params, for example when a user presses a button that triggers an event specific to a product. In order to fetch the details, you might need to use a productId identifying it.

For those use cases we provide a way to attach a Param to UI elements; Button, QuickReply, and Action.

Below you can view an example of how to create and attach a param 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
})

It's also possible to attach multiple params:

// 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]
})

Or even add the same param 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 following is a complete working example of sending a buttons widget with params:

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 Params

With code actions you receive params but you can also manipulate them. This is simply done by returning a params object.

Modifying a Param

You can modify an existing param by changing the value inside the returned object as the example below illustrates.

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'
      }]
    }
  }
}

🚧

Warning

Make sure to always return other params you'd like to return like in the above example.

Clear a Single Param

There are three ways of clearing params within context. Either by using a reset within the design tool, or by resetting params using a webhook or code action.

The following example removes a single param:

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

Clear all params

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

Simply return a null as the value for params.

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