Note: Params lifetime is 24h.
Using params
The NLP engine can for example detect entities within 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 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 3 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
}
}
