Params

Depending on the actions prior to execution you can expect a set of various params. For example a user shares a file or the bot detects a named entity.

Extracting params

The AI engine can detect entities within text and those become available within your code. For example if a user asks: I want to book a hotel in Amsterdam and Amsterdam would be a entity named destinationCity.

Note: Params are always lists (arrays).

The AI engine could detect multiple similar entities, for example: I want to book a hotel in Amsterdam and Kopenhagen.

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 not always feasible to do entity extraction. Like in the case you want a user to press 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 shows you an example 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:

(function(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)
})

Manipulating params

With cloud code you’ll receive params but you can also manipulate them using code. This is simply done by returning a params collection.

async payload => {
  return {
    params: {
      ...payload.params,
      destination_city: [{
        value: `ams`,
        match: 'Amsterdam'
      }]
    }
  }
}

Warning

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

The following example clears all params by returning null.

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