Message and rich response templates for use with Flow.ai
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dist
docs
lib
src
test
.babelrc
.eslintignore
.eslintrc
.gitignore
.jsdoc
JSON.md
README.md
package-lock.json
package.json
webpack.config.js

README.md

The Flow.ai JavaScript Response Templates

Easy helper classes to create rich flow.ai response templates like cards, buttons and locations.

Reponse templates allow developers to render widgets at channels that support this like Facebook Messenger or the flow.ai Web client.

What can you do?

  • No need to write error prone JSON
  • Full support for all template types

Getting started

All classes are available for usage with Flow.ai Cloud functions. When you want to send rich responses using a webhook, install the library with NPM.

Install

npm install --save flowai-js-templates

Usage

When using Flow.ai cloud code there is no need to require or import anything.

const { Card } = require('flowai-js-templates')

const card = new Card({
  title: "Cookie factory",
  subtitle: "Infinite lane 23"
})

Sending back rich messages

You can send back rich messages in 3 different ways

Cloud code

Within a cloud code function you can directly send back messages by returning them from your function.

Sending a single message with a single response
(function(payload,originator,done) {

  // Create a speech bubble
  const text = new Text("Hi there!")

  // Create a message with fallback text
  const message = new Message("Hi, there")
  message.addResponse(text)

  return message
})
Sending a single message with multiple responses
(function(payload,originator,done) {

  // Create a speech bubble
  const text = new Text("Hi there!")

  // Create a card
  const card = new Card({
    title: "Cookie factory",
    subtitle: "Infinite lane 23"
  })

  return new Message("Hi, the address of the Cookie factory is Infinite lane 23")
          .addResponse(text)
          .addResponse(card)
})
Sending back multiple messages
(function(payload,originator,done) {

  // Create a speech bubble
  const text = new Text("Hi there!")

  // Create a card
  const card = new Card({
    title: "Cookie factory",
    subtitle: "Infinite lane 23"
  })

  return [
    new Message("Hi, there").addResponse(text),
    new Message("the address of the Cookie factory is Infinite lane 23").addResponse(card)
  ]
})

Class Reference

Classes

Action

Default action used in Card, List and Buttons templates

Button

Component used in Card, Buttons templates

ListItem

Item within a List

Media

Component that represents a URL to an image, video or audio file. Used on Templates like Card and Image.

Param

Data related to a Button or Quick Reply

QuickReply

Component placed on any Template. Represents a shortcut for a user to reply with. Ideal for yes / no type of questions.

Audio

Template with audio

Buttons

Template with a short description and buttons to request input from the user.

Card

Template composed of a media attachment, short description and buttons to request input from the user.

Carousel

Template that displays a set of cards

Custom

Template composed with your own data. Use this to create specific UI widgets or components to your app or web ui. Do remember we cannot convert these type of templates to channels like Messenger.

File

Template with a file

Image

Template with a image

List

Template that displays a set of list items

Location

Template with a location

Template

Base class of all response templates

Text

Template with a piece of text

Video

Template with a video

Functions

parseParam()

Helper method to convert a list of params

flattenParams()

Helper method to convert params into the expected format

Action

Default action used in Card, List and Buttons templates

Kind: global class
Properties

Name Type Description
type string Type of action (url, phone, postback, share, login, webview, event)
value string Value of the action
params Array.<Param> Optional parameters associated with the action

new Action()

Param Type Description
opts.type string Required
opts.value string Required
opts.param Param | Array.<Param> Optional Param or array or Array of Params related to this action

Button

Component used in Card, Buttons templates

Kind: global class
Properties

Name Type Description
type string Type of button (url, phone, postback, share, login, webview, event)
label string Label of the button
value string Value of the button
params Array.<Param> Optional parameters associated with the button

new Button()

Param Type Description
opts.type string Required, type of button (url, phone, postback, share, login, webview, event)
opts.label string Required, label of the button
opts.value string Required, value of the button (can be a URL or other string value)
opts.param Param | Array.<Param> Optional Param or array or Array of Params related to this button

Example

new Button({
 type: 'webview',
 label: 'More info'
 value: 'https://...'
})

ListItem

Item within a List

Kind: global class
Properties

Name Type Description
title string Title of the list item
subtitle string Optional subtitle
media Media Optional Media
buttons Array.<Button> Optional set of buttons
action Action Optional Action that is triggered when a user interacts with the list item
featured bool Optional set this element to be featured in the List (default false)

new ListItem()

Param Type Description
opts.title string Required
opts.subtitle string Optional
opts.media Media Optional
opts.action Action Optional
opts.featured bool Optional

listItem.addButton(button) ⇒ ListItem

Add a button to the list item

Kind: instance method of ListItem

Param Type Description
button Button button

Media

Component that represents a URL to an image, video or audio file. Used on Templates like Card and Image.

Kind: global class
Properties

Name Type Description
url string URL to the media file

new Media()

Param Type Description
opts.url string Required
opts.type string Required

Param

Data related to a Button or Quick Reply

Kind: global class
Properties

Name Type Description
label string Name of the parameter
value string Value of the parametet

new Param()

Param Type Description
opts.type string Required
opts.label string Required
opts.value string Required

Example

// Render a Button that triggers an event with a Param
const param = new Param('itemId', '332223323')
const button = new Button({
 label: 'More info',
 type: 'event',
 value: 'MORE_INFO',
 param
})

Example

// Render a QuickReply that triggers an event with Params
const shopId = new Param('shopId', '33211233')
const productId = new Param('productId', '123443211')
const quickReply = new QuickReply({
 label: 'Product details',
 type: 'event',
 value: 'PRODUCT_DETAILS',
 param: [shopId, productId]
})

Example

const image = new Image({
  title: "Awesome title",
  url: "https://...",
  action: new Action({
    type: 'event',
    value: 'ORDER',
    param: new Param('productId', '12e2-22342-aasd2')
  })
})

QuickReply

Component placed on any Template. Represents a shortcut for a user to reply with. Ideal for yes / no type of questions.

Kind: global class
Properties

Name Type Description
label string Label that is shown as a quick reply
value string Value that is being send as the quick reply, empty if type is location
type string Type of quick reply, default is text (text, location, user_email, user_phone_number, event)
params Array.<Param> Optional parameters associated with the quick reply

new QuickReply()

Param Type Description
opts.label string Required
opts.type string Optional type, default is text (text, location, user_email, user_phone_number, event)
opts.value string Required, ignored if type is location
opts.param Param | Array.<Param> Optional Param or array or Array of Params related to this QuickReply

Example

const text = new Text('We have a 40" screen for sale. Want to preorder it?')
text.addQuickReply(new QuickReply({
  label: '👍',
  value: 'Yes'
}))
text.addQuickReply(new QuickReply({
  label: '👎',
  value: 'No'
}))

Audio

Template with audio

Kind: global class
Properties

Name Type Description
title string Describes the audio
url string URL to the audio file
action Action Optional Action

new Audio()

Param Type Description
opts.title string Required
opts.url string Required
opts.action string Optional

Example

const audio = new Audio({
  title: "Awesome title",
  url: "https://...",
  action: new Action({
    type: 'url',
    value: 'https://...'
  })
})

Buttons

Template with a short description and buttons to request input from the user.

Kind: global class
Properties

Name Type Description
title string Main title of the buttons
buttons Array.<Button> Optional set of buttons

new Buttons()

Param Type Description
opts.title string Required

Example

const buttons = new Buttons("Vintage bikes and more")
buttons.addButton(new Button({
 label: "View website",
 type: "url",
 value: "..."
}))
buttons.addButton(new Button({
 label: "Special offers",
 type: "postback",
 value: "Show me special offers"
}))

buttons.addButton(button) ⇒ Button

Add a button to the buttons

Kind: instance method of Buttons

Param Type Description
button Button button

Card

Template composed of a media attachment, short description and buttons to request input from the user.

Kind: global class
Properties

Name Type Description
title string Main title of the card
subtitle string Optional subtitle
media Media Optional Media
action Action Optional Action
buttons Array.<Button> Optional set of buttons
action Action Optional Action that is triggered when a user interacts with the card

new Card()

Param Type Description
opts.title string Required
opts.subtitle string Optional
opts.media Media Optional
opts.action Action Optional

Example

const button1 = new Button({
  label: "Label",
  type: "url",
  value: "https://..."
})

const button2 = new Button({
  label: "Label",
  type: "url",
  value: "https://..."
 })

const card = new Card({
  title: "Awesome title",
  subtitle: "Some subtitle",
  media: new Media({
   url: "https://...",
   type: "image"
  })
})
card.addButton(button1)
card.addButton(button2)

card.addButton(button) ⇒ Card

Add a button to the card

Kind: instance method of Card

Param Type Description
button Button button

Carousel

Template that displays a set of cards

Kind: global class
Properties

Name Type Description
cards Array.<Card> Set of cards

new Carousel(cards)

Param Type Description
cards Array Optional

Example

const card1 = new Card({
  title: "Awesome title 1",
  subtitle: "Some subtitle 1",
  media: new Media({
   url: "https://...",
   type: "image"
  })
})

const card2 = new Card({
  title: "Awesome title 2",
  subtitle: "Some subtitle 2",
  media: new Media({
   url: "https://...",
   type: "image"
  })
})

const carousel = new Carousel()
carousel.addCard(card1)
carousel.addCard(card2)

Example

// Short hand
const card1 = new Card({
  title: "Awesome title 1",
  subtitle: "Some subtitle 1",
  media: new Media({
   url: "https://...",
   type: "image"
  })
})

const card2 = new Card({
  title: "Awesome title 2",
  subtitle: "Some subtitle 2",
  media: new Media({
   url: "https://...",
   type: "image"
  })
})

const carousel = new Carousel([card1, card2])

carousel.addCard(card) ⇒ Carousel

Add a card to the cards

Kind: instance method of Carousel

Param Type Description
card Card card

Custom

Template composed with your own data. Use this to create specific UI widgets or components to your app or web ui. Do remember we cannot convert these type of templates to channels like Messenger.

Kind: global class
Properties

Name Type Description
data object Data tailored to your use case

new Custom(data)

Param Type Description
data object Required

Example

const custom = new Custom({
  title: 'Big screen TV',
  brand: 'Awesome Elec.',
  catId: 35633123322,
  prices: {
    'EURO': 1800,
    'DOLLAR': '2400'
  }
})
// You can still add quick replies
// to these type of componentz
custom.addQuickReply(new QuickReply({
  label: 'Order now',
  value: 'order 35633123322'
}))

File

Template with a file

Kind: global class
Properties

Name Type Description
title string Describes the file
url string URL to the file
action Action Optional Action

new File()

Param Type Description
opts.title string Required
opts.url string Required
opts.action string Optional

Example

const file = new File({
  title: "Awesome title",
  url: "https://...",
  action: new Action({
    type: 'url',
    value: 'https://...'
  })
})

Image

Template with a image

Kind: global class
Properties

Name Type Description
title string Describes the image
url string URL to the image
action Action Optional Action

new Image()

Param Type Description
opts.title string Required
opts.url string Required
opts.action string Optional

Example

const image = new Image({
  title: "Awesome title",
  url: "https://...",
  action: new Action({
    type: 'url',
    value: 'https://...'
  })
})

List

Template that displays a set of list items

Kind: global class
Properties

Name Type Description
items Array.<ListItem> Set of list items

list.addItem(item) ⇒ List

Add a item to the items

Kind: instance method of List

Param Type Description
item ListItem item

list.addButton(button) ⇒ ListItem

Add a button to the list item

Kind: instance method of List

Param Type Description
button Button button

Location

Template with a location

Kind: global class
Properties

Name Type Description
title string Describes the image
lat string Latitude
long string Longitude
action Action Optional Action

new Location()

Param Type Description
opts.title string Required
opts.lat string Required
opts.long string Required
opts.action string Optional

Example

const location = new Location({
  title: "Infinite Loop 1",
  lat: "37.331860",
  long: "-122.030248",
  action: new Action({
    type: 'url',
    value: 'https://...'
  })
})

Template

Base class of all response templates

Kind: global abstract class
Properties

Name Type Description
delay Number Optional delay in miliseconds for sending the response
quickReplies Array.<QuickReply> Optional list of QuickReplies

template.delay

Define a delay for the response in miliseconds

Kind: instance property of Template

Param Type Description
delay Number Required

template.fallback

Optional fallback speech

Kind: instance property of Template

Param Type Description
fallback String Required

template.addQuickReply(quickReply)

Add a quick reply to the template

Kind: instance method of Template

Param Type Description
quickReply QuickReply Required

Text

Template with a piece of text

Kind: global class
Properties

Name Type Description
text string Text to show

new Text()

Param Type Description
opts.text string Required

Example

const text = new Text('Want a free soda?')
text.addQuickReply(new QuickReply({
  label: 'Yes',
  value: 'yes'
}))
text.addQuickReply(new QuickReply({
  label: 'No',
  value: 'no'
}))

Video

Template with a video

Kind: global class
Properties

Name Type Description
title string Describes the video
url string URL to the video
action Action Optional Action

new Video()

Param Type Description
opts.title string Required
opts.url string Required
opts.action string Optional

Example

const video = new Video({
  title: "Awesome title",
  url: "https://...",
  action: new Action({
    type: 'url',
    value: 'https://...'
  })
})

parseParam()

Helper method to convert a list of params

Kind: global function

flattenParams()

Helper method to convert params into the expected format

Kind: global function