Flowai-js-templates NPM

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

async payload=> {

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

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

  return message
}

Sending a single message with multiple responses

async payload=> {

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

  // Create a Google Business Messages specific card
  const card = new GBM.Card({
    title: "Cookie factory",
    description: "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

async payload=> {

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

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

Channel specific

We support a number of generic components that render on most channels. For example a Card element works for both Facebook Messenger and the Flow.ai Web Widget.

However, there are specific components as well for channels like Apple Business Chat or an IVR Bot.

You can create and send these as well. The following example shows how to create and send a Time Picker for Apple Business chat.

async payload=> {
  const timePicker = new Apple.TimePicker({
    receivedMessage: new Apple.InteractiveMessage({
      title: "Schedule an Appointment",
      subtitle: "We'll see you there!",
      style: "icon"
    }),
    replyMessage: new Apple.InteractiveMessage({
      title: "Your Appointment",
      style: "icon"
    }),
    event: new Apple.EventItem({
      title: "Some event",
      location: new Apple.LocationItem({
        latitude: 37.7725,
        longitude: -122.4311,
        radius: 100,
        title: "Some venue"
      }),
      timeslots: [
        new Apple.TimeItem({
          duration: 60,
          startTime: "2020-05-26T08:27:55+00:00"
        }),
        new Apple.TimeItem({
          duration: 60,
          startTime: "2020-05-26T09:27:55+00:00"
        }),
        new Apple.TimeItem({
          duration: 60,
          startTime: "2020-05-26T10:27:55+00:00"
        })
      ],
      timezoneOffset: 2
    })
  })

  return new Message('Time picker').addResponse(timePicker)
}

For a complete overview of all reply actions see the Flow.ai documentation site.

Reply Templates Reference

Each reply being sent is part of a message.

Base.Message

The base representation of a message to a user. Contains a pronounceable fallback message and optional rich Template responses.

Properties

Name	Type	Description
fallback	string	Pronounceable and represents the responses as a whole
responses	Array.<Template>	List of rich Template responses

new Message(fallback, meta)

Example

// Create a message without responses
// this will create a response
// when converted to JSON
const message = new Message('Hi there')

// This also works for multiple text responses by adding an array of strings
const message = new Message(['Hi there', 'How can I help?'])

Param	Type	Description
fallback	string	Required
meta	Object	Optional property list with data

message.addResponse(response)

Add a response

Param	Type	Description
response	Template	response

Generic

We provide a collection of generic message templates that can be sent to any messaging channel. These generic templates are transformed into specific channel counter parts. They provide a convenient way to reply with a single message to multiple channels.

Message

Inherits from Message.

message.addQuickReply(quickReply)

A convenience method to add a quick reply to the last response template of a Message

Example

const message = new Message("Want a cold beverage?")
 .addQuickReply(new QuickReply({
   label: 'Yes'
 }))
 .addQuickReply(new QuickReply({
   label: 'No'
 }))

Param	Type	Description
quickReply	QuickReply	Required

message.addSuggestedAction(suggestedAction)

A convenience method to add a Suggested Action to the last response template of a Message

Example

const message = new Message("Put on some music please!")
 .addSuggestedAction(new SuggestedAction({
   "label": "test with code action",
   "type": "calendar_action",
   "title": "Party at Imran's",
   "description": "party tonight",
   "startTime": "2023-04-27T23:30",
   "endTime": "2023-04-28T04:30",
   "timezone": "(UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi"
 }))

Param	Type	Description
suggestedAction	SuggestedAction	Required

Text

The simplest messages are made of text. Text messages are best suited to communicate information without the need for visuals, complex interaction, or response.

Properties

Name	Type	Description
text	string	Text to show

new Text()

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

Param	Type	Description
opts.text	string	Required

Image

Deliver an image to a user. Optionally you can specify an Action to perform when a user interacts with the image. Note: This is not supported on all channels.

Properties

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

new Image()

Example

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

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

File

Deliver a file to a user. Optionally you can specify an Action to perform when a user interacts with the file. Note: This is not supported on all channels.

Properties

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

new File()

Example

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

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

Video

Deliver a video to a user or show a video player. Optionally you can specify an Action to perform when a user interacts with the video. Note: This is not supported on all channels.

Properties

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

new Video(opts)

Example

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

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

Audio

Send an audio file or show an audio player to a user. Optionally you can specify an Action to perform when a user interacts with the audio. Note: This is not supported on all channels.

Properties

Name	Type	Description
title	string	Describes the audio
url	string	URL to the audio file
action	Action	Optional Action
duration	duration	required for channels like 'LINE' otherwise optional

new Audio()

Example

// Generic audio
const audio = new Audio({
  title: "Name of the song",
  url: "https://..."
})

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

Location

Send or display a location on a map to a user. Optionally add an Action to perform when the user interacts with the location. Note: only supported on some channels.

Properties

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

new Location()

Example

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

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

Buttons

Generic template with an optional short description and list of Button components to request input from a user

Properties

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

new Buttons()

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"
}))

Param	Type	Description
opts.title	string	Required

new Buttons(body, footer, header, buttons)

Example

const ButtonWA = new Templates.WhatsApp.Button({
             title: "Example title",
           })
const HeaderWA = new Templates.WhatsApp.Header({
             type: 'text',
             value: 'Example value'
           })

const buttonsWA = new Templates.WhatsApp.List({body: 'Example body',
            header: HeaderWA,
            buttons: [ButtonWA]
          })

Param	Type	Description
body	string	Required
footer	string	Optional
header	Header	Optional Header
buttons	Array	Required

buttons.addButton(button)

Add a button to the buttons

Param	Type	Description
button	Button	button

buttons.addButton(button)

Add a button to the buttons

Param	Type	Description
button	Button	button

Card

A generic template that can be a combination of a Media attachment, short description or Button components to request input from a user.

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 Button components
action	Action	Optional Action that is triggered when a user interacts with the card

new Card()

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)

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

new Card()

Example

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

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

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

const rbm_card_hr = new Card({
  title: "Awesome title",
  subtitle: "Some subtitle",
  cardOrientation: "HORIZONTAL",
  thumbnailImageAlignment: "LEFT", 
  media: new Media({
   url: "https://...",
   type: "image",
   height: "TALL"
  })
})
card.addButton(button1)
card.addButton(button2)

Param	Type	Description
opts.title	string	Required
opts.subtitle	string	Optional
opts.media	Media	Optional Media
opts.cardOrientation	string	Required
opts.thumbnailImageAlignment	string	Required for horizontal orientation
opts.action	Action	Optional Action

card.addButton(button)

Add a button to the card

Param	Type	Description
button	Button	button

card.addButton(button)

Add a button to the card

Param	Type	Description
button	Button	button

card.addRBMButton(button)

Add a RBM type button to the card

Param	Type	Description
button	RBMButton	button

Carousel

Template that renders a set of generic Card templates

Properties

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

new Carousel(cards)

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

Param	Type	Description
cards	Array	Optional list of Card templates

new Carousel(cardWidth, cards)

Example

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

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

const carousel = new Carousel()
carousel.addCard(card1)
carousel.addCard(card2)
carousel.cardWidth = 'MEDIUM'

Param	Type	Description
cardWidth	string	required
cards	Array	Optional list of Card templates

carousel.addCard(card)

Add a Card to the list of cards

Param	Type	Description
card	Card	card

carousel.addCard(card)

Add a Card to the list of cards

Param	Type	Description
card	Card	card

List

Template that displays a set of ListItem components

Properties

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

list.addItem(item)

Add a ListItem to the list of items

Param	Type	Description
item	ListItem	ListItem

list.addButton(button)

Add a Button to the list of buttons

Param	Type	Description
button	Button	button

list.addItem(item)

Add a ListItemSection to the list of items

Param	Type	Description
item	ListItemSection	ListItemSection

ListItem

Item within a List template

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

new ListItem()

Param	Type	Description
opts.title	string	Required
opts.description	string	Required
opts.id	string	Optional, id of the button. If not passed will be automatically generated

listItem.addButton(button)

Add a button to the list item

Param	Type	Description
button	Button	button

Action

Attach an action that is performed when a user interacts with a generic Card, List or Buttons templates

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

Example

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

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

Render a button inside Card or Buttons templates. Unlike QuickReply templates, by default a button will remain on the screen even after a user presses them.

Properties

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

new Button(opts)

Example

new Button({
 type: 'webview',
 label: 'More info'
 value: 'https://...',
 trigger: new ButtonTrigger({
   type: 'event',
   value: 'Event to Trigger'
 })
})

Param	Type	Description
opts	object	Required properties
opts.type	string	Required, type of button (url, phone, postback, share, login, webview, event, flow, step)
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.id	string	Optional, id of the button. If not passed will be automatically generated
opts.param	Param \| Array.<Param>	Optional Param or array or Array of Params related to this button

new Button(opts)

Example

new Button({
 type: 'webview',
 label: 'More info'
 value: 'https://...',
 trigger: new ButtonTrigger({
   type: 'event',
   value: 'event-to-trigger'
 })
})

Param	Type	Description
opts	object	Required properties
opts.type	string	Required, type of button (url, phone, postback, share, login, webview, event, flow, step)
opts.value	string	Required, value of the button (can be a URL or other string value) (not for calendar action)
opts.label	string	Required, label of the button
opts.id	string	Optional, id of the button. If not passed will be automatically generated
opts.title	string	Required
opts.description	string	Optional
opts.startTime	string	Required
opts.endTime	string	Required
opts.timezone	string	Required
opts.trigger	ButtonTrigger	Optional
opts.param	Param \| Array.<Param>	Optional Param or array or Array of Params related to this button

new Button(opts)

Example

new Button({
 title: 'Select',
 type: 'event',
 value: 'NICE_EVENT'
})

Param	Type	Description
opts	object
opts.title	string	Required, title of the button
opts.type	string	Required, type of the button (text, event, flow or step)
opts.value	string	Required, value of payload to be sent back to the server when customer clicks the buttons
opts.id	string	Optional, id of the button. If not passed will be automatically generated
opts.param	Param	Optional, parameter to pass to the button
opts.params	Array.<Param>	Optional, parameters to pass to the button

ButtonTrigger

Attach an optional trigger that can be applied to a Button if the type of the button is either 'url' or 'phone'.

Properties

Name	Type	Description
type	string	Type of button trigger (event, flow)
value	string	Value of the event/flow to be triggered

new ButtonTrigger(opts)

Example

new ButtonTrigger({
 type: 'event',
 value: 'event-to-trigger'
})

Param	Type	Description
opts	object	Required properties
opts.type	string	Required, type of additional trigger (event, flow)
opts.value	string	Required, name of the event/flow to be triggered

Media

Component that represents a URL to an image, video or audio file. Used within generic templates like Card and Image.

Properties

Name	Type	Description
url	string	URL to the media file

new Media()

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

new Media()

Param	Type	Description
opts.url	string	Required
opts.type	string	Required
opts.height	string	Required for Vertical layout

new Media()

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

QuickReply

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

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, flow, step)
quickReplyId	string	Type of quick reply, default is text (text, location, user_email, user_phone_number, event, flow, step)
params	Array.<Param>	Optional parameters associated with the quick reply
tags	Array.<Param>	Optional tags associated with the quick reply

new 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'
}))

Param	Type	Description
opts.label	string	Required
opts.type	string	Optional type, default is text (text, location, user_email, user_phone_number, event, flow, step)
opts.value	string	Required, ignored if type is location
opts.quickReplyId	string	Required
opts.auto	boolean	Optional, flag for auto reply
opts.stepId	string	Optional, step link for auto reply
opts.param	Param \| Array.<Param>	Optional Param or array or Array of Params related to this QuickReply
opts.tags	Param \| Array.<Param>	Optional Tags or array or Array of Tags related to this QuickReply

Messenger

These reply templates are specific to the Messenger integration. They are not supported by other channels.

Messenger.Products

Products Template

Properties

Name	Type	Description
productIds	Array.<string>	list of product IDs

new Products(productIds)

The product template can be used to render products that have been uploaded to Facebook catalog. Product details (image, title, price) will automatically be pulled from the product catalog.

Example

// Single product card
const product = new Messenger.Products('11232112332')

// Carousel of products
const product = new Messenger.Products(['11232112332', '23422224343])

Param	Type	Description
productIds	Array.<string>	Required

Messenger.OTN

One-Time Notification Request Template

Properties

Name	Type	Description
title	string	title of the OTN
tag	string	tag that will be assigned to actor when this OTN is called

new OTN(title, tag)

The One-Time Notification request template template will be rendered and once the user clicks the Notify Me button, a special OTNR trigger is called. The specific user can now be reached for a follow up message after the 24hr period.

Example

const otn = new Messenger.OTN('When keyboards are available', 'keyboard')

Param	Type	Description
title	string	Required title for the request
tag	string	Optional tag name to apply when a user accepts the OTNR

Messenger.Receipt

Receipt Template

Properties

Name	Type	Description
sharable	boolean	Optional, set to true to enable the native share button in Messenger for the template message. Defaults to false.
recipientName	string	Required, the recipient's name.
merchantName	string	Optional, the merchant's name. If present this is shown as logo text.
orderNumber	string	Required, the order number. Must be unique.
currency	string	Required, currency of the payment.
paymentMethod	string	Required, the payment method used. Providing enough information for the customer to decipher which payment method and account they used is recommended. This can be a custom string, such as, "Visa 1234".
timestamp	string	Optional, timestamp of the order in seconds.
elements	Array.<ReceiptElement>	Optional, array of a maximum of 100 element objects that describe items in the order. Sort order of the elements is not guaranteed.
address	ReceiptAddress	Optional, the shipping address of the order.
summary	ReceiptSummary	Optional, the payment summary. See summary.
adjustments	Array.<ReceiptAdjustment>	Optional, an array of payment objects that describe payment adjustments, such as discounts.

new Receipt()

The receipt template allows you to send an order confirmation. The template may include an order summary, payment details, and shipping information.

Example

// Create a receipt
const receipt = new Messenger.Receipt({
  recipientName: "Stephane Crozatier",
  orderNumber: "12345678902",
  currency: "USD",
  paymentMethod: "Visa 2345",
  orderUrl: "http://petersapparel.parseapp.com/order?order_id=123456",
  timestamp: "1428444852",
  address: new Messenger.ReceiptAddress({
    street1: "1 Hacker Way",
    street2: "2nd floor",
    city: "Menlo Park",
    postalCode: "94025",
    state: "CA",
    country: "US"
  }),
  summary: new Messenger.ReceiptSummary({
    subtotal: 75.00,
    shippingCost: 4.95,
    totalTax: 6.19,
    totalCost: 56.14
  }),
  adjustments: [
    new Messenger.ReceiptAdjustment({
      name: "New Customer Discount",
      amount: 20
    }),
    new Messenger.ReceiptAdjustment({
      name: "$10 Off Coupon",
      amount: 10
    })
  ],
  elements: [
    new Messenger.ReceiptElement({
      title: "Classic White T-Shirt",
      subtitle: "100% Soft and Luxurious Cotton",
      quantity: 2,
      price: 29.95,
      currency: "USD",
      imageUrl: "http://petersapparel.parseapp.com/img/whiteshirt.png"
    }),
    new Messenger.ReceiptElement({
      title: "Classic Gray T-Shirt",
      subtitle: "100% Soft and Luxurious Cotton",
      quantity: 2,
      price: 49.95,
      currency: "USD",
      imageUrl: "http://petersapparel.parseapp.com/img/grayshirt.png"
    })
  ]
})

Messenger.ReceiptElement

Component used in Receipt templates

Properties

Name	Type	Description
title	string	Required, the name to display for the item.
subtitle	string	Optional, a brief item description
quantity	number	Optional, the quantity of the item purchased.
price	number	Required, the price of the item. For free items, '0' is allowed.
currency	string	Optional, the currency of the item price.
imageUrl	string	Optional, the URL of an image to be displayed with the item.

new ReceiptElement(opts)

The shipping element of an order

Example

const element = new Messenger.ReceiptElement({
})

Param	Type	Description
opts	object	Required properties
opts.title	string	Required, the name to display for the item.
opts.subtitle	string	Optional, a brief item description
opts.quantity	number	Optional, the quantity of the item purchased.
opts.price	number	Required, the price of the item. For free items, '0' is allowed.
opts.currency	string	Optional, the currency of the item price.
opts.imageUrl	string	Optional, the URL of an image to be displayed with the item.

Messenger.ReceiptAddress

Component used in Receipt templates

Properties

Name	Type	Description
street1	string	Required, the street address, line 1.
street2	string	Optional, the street address, line 2.
city	string	Required, the city name of the address.
postalCode	string	Required, the postal code of the address.
state	string	Required, the state abbreviation for U.S. addresses, or the region/province for non-U.S. addresses.
country	string	Required, the two-letter country abbreviation of the address.

new ReceiptAddress(opts)

The shipping address of an order

Example

const address = new Messenger.ReceiptAddress({
  street1: "1 Hacker Way",
  street2: "2nd floor",
  city: "Menlo Park",
  postalCode: "94025",
  state: "CA",
  country: "US"
})

Param	Type	Description
opts	object	Required properties
opts.street1	string	Required, the street address, line 1.
opts.street2	string	Optional, the street address, line 2.
opts.city	string	Required, the city name of the address.
opts.postalCode	string	Required, the postal code of the address.
opts.state	string	Required, the state abbreviation for U.S. addresses, or the region/province for non-U.S. addresses.
opts.country	string	Required, the two-letter country abbreviation of the address.

Messenger.ReceiptSummary

Component used in Receipt templates

Properties

Name	Type	Description
subtotal	number	Optional, the sub-total of the order.
shippingCost	number	Optional, the shipping cost of the order.
totalTax	number	Optional, the tax of the order.
totalCost	number	Required, the total cost of the order, including sub-total, shipping, and tax.

new ReceiptSummary(opts)

The shipping summary of an order

Example

const summary = new Messenger.ReceiptSummary({
  subtotal: 75.00,
  shippingCost: 4.95,
  totalTax: 6.19,
  totalCost: 56.14
})

Param	Type	Description
opts	object	Required properties
opts.subtotal	number	Optional, the sub-total of the order.
opts.shippingCost	number	Optional, the shipping cost of the order.
opts.totalTax	number	Optional, the tax of the order.
opts.totalCost	number	Required, the total cost of the order, including sub-total, shipping, and tax.

Messenger.ReceiptAdjustment

Component used in Receipt templates

Properties

Name	Type	Description
name	string	Required, name of the adjustment.
amount	number	Required, the amount of the adjustment.

new ReceiptAdjustment(opts)

Describes a payment adjustments, such as discounts

Example

const adjustment = new Messenger.ReceiptAdjustment({
  name: "10% discount",
  amount: 4.95
})

Param	Type	Description
opts	object	Required properties
opts.name	string	Required, name of the adjustment.
opts.amount	number	Required, the amount of the adjustment.

Phone

These reply templates are specific to the Twilio voice integration. They are not supported by other channels.

Phone.Ask

Send a message to a user asking for input

Properties

Name	Type	Description
speech	string	Text to speech
url	string	URL to an audio file
expected	string	Optional, what kind of input to expect. Valid are speech or digits (default is speech)
hints	string	Optional, expected words or sentences, comma separated (max 500 words)
language	string	Optional language for text to speech
voice	string	Optional voice for text to speech
timeout	number	Optional, number of seconds to wait for user input (default ) and send a repeat message
repeat	number	Optional, number of times to ask again after user has not provided input (default 1, 0 is unlimited loop)
finishOnKey	string	Optional, only when expecting digits, set a value that your caller can press to submit their digits.
numDigits	number	Optional, only when expecting digits, set the number of digits you expect from your caller
speechTimeout	string	Optional, only when expecting speech, sets the limit (in seconds) to wait before it stopping speech recognition

new Ask()

Ask a user for input

Example

const ask = new Phone.Ask({
  speech: 'Do you speak English?',
  language: 'en-GB',
  expected: 'speech',
  hints: 'yes,yeah,yup,yes I do,no,no not really,nope'
})

Phone.Say

Play an audio file or send a text message to a user that is transformed to speech

Properties

Name	Type	Description
speech	string	The text transformed to speech Send a message to a user
speech	string	Text to speech
url	string	URL to an audio file
language	string	Optional language for text to speech
voice	string	Optional voice for text to speech

new Say(opts)

Example

const say = new Phone.Say({
  speech: 'The weather is nice today!',
  language: 'en-GB'
})

Param	Type	Description
opts	Object	Configuration
opts.speech	string	Text to speech
opts.url	string	URL to audio File
opts.language	string	Optional language for text to speech
opts.voice	string	Optional voice for text to speech

Phone.Pause

Pause a moment during the call

Properties

Name	Type	Description
seconds	float	The number of seconds to delay

new Pause()

Example

const pause = new Phone.Pause(0.2)

Param	Type	Description
opts.seconds	number	Required

Phone.Dial

Dial a number and forward the call

Properties

Name	Type	Description
phoneNumber	string	The number of phoneNumber to delay

new Dial()

Example

const pause = new Dial(0.2)

Param	Type	Description
opts.phoneNumber	string	Required

Phone.Hangup

Disconnect

new Hangup()

Disconnect a phone call

Example

const hangup = new Phone.Hangup()

Apple Business Chat (Preview)

These reply templates are specific to the Apple Business Chat integration. They are not supported by other channels.

Apple.RichLink

Enhance the customer's experience by allowing them to preview inline content.

Properties

Name	Type	Description
title	string	Required title
url	string	Required. URL to the linked web page
assets	array	Required. List of assets like ImageAsset or VideoAsset

new RichLink(opts)

Example

const richLink = new Apple.RichLink({
  title: "Some news website",
  url: "https://www.mynewswebsite.corp",
  assets: [
    new Apple.ImageAsset({
      url: "https://source.unsplash.com/random",
      mimeType: "image/png"
    }),
    new Apple.VideoAsset({
      url: "https://somevideo",
      mimeType: "video/mp4"
    })
  ]
})

Param	Type	Description
opts	object	Collection of options
opts.title	string	Required title
opts.url	string	Required. URL to the linked web page
opts.assets	array	Required. List of assets like ImageAsset or VideoAsset

richLink.addAsset(asset)

Add an asset to the list of media assets

Param	Type	Description
asset	Asset	asset

Apple.ImageAsset

Component that represents an image asset used with a RichLink template

Properties

Name	Type	Description
url	string	Required. URL to the image
mimeType	string	Required. A string representing the format/type of the image; for example, image/jpeg, image/png

new ImageAsset(opts)

Param	Type	Description
opts	object	Collection of options
opts.url	string	Required. URL to the image
opts.mimeType	string	Required. The format/type of the image

Apple.VideoAsset

Component that represents a video asset used with a RichLink template

Properties

Name	Type	Description
url	string	Required. URL to the video
mimeType	string	Required. A string representing the format/type of the video; for example, video/mp4, video/mpeg

new VideoAsset(opts)

Param	Type	Description
opts	object	Collection of options
opts.url	string	Required. URL to the video
opts.mimeType	string	Required. The format/type of the video

Apple.ListPicker

Allow the customer to choose from a list of items

Properties

Name	Type	Description
sections	array	Required 1 or more ListPickerSection objects
multipleSelection	boolean	Indicates whether the customer can make multiple selections across sections. Defaults to false
receivedMessage	InteractiveMessage	Required. Message bubble that is shown to the customer to open the ListPicker window
replyMessage	InteractiveMessage	Required. When the customer’s device receives a picker, the Messages app uses the replyMessage to set the style, content, and images for the reply message bubble that the Messages app displays after the customer makes their selection and returns a reply to the business.
opts.triggerAction	object	Required. Trigger Action when items are selected from the list

new ListPicker(opts)

Example

const listPicker = new Apple.ListPicker({
  receivedMessage: new Apple.InteractiveMessage({
    title: "Select products",
    subtitle: "Fresh and straight from the farm",
    style: "small"
  }),
  replyMessage: new Apple.InteractiveMessage({
    title: "Selected products",
    style: "small"
  }),
  sections: [
    new Apple.ListPickerSection({
      title: "Fruit",
      items: [
        new Apple.ListPickerItem({
          title: "Apple",
          subtitle: "Red and delicious"
        }),
        new Apple.ListPickerItem({
          title: "Orange",
          subtitle: "Vitamin C boost"
        })
      ]
    }),
    new Apple.ListPickerSection({
      title: "Veggies",
      items: [
        new Apple.ListPickerItem({
          title: "Lettuce",
          subtitle: "Crispy greens"
        }),
        new Apple.ListPickerItem({
          title: "Cucumber",
          subtitle: "Organic"
        })
      ]
    })
  ]
})

Param	Type	Description
opts	object	Collection of options
opts.sections	array	An array of ListPickerSection objects
opts.multipleSelection	boolean	Indicates whether the customer can make multiple selections across sections. Defaults to false
opts.receivedMessage	InteractiveMessage	Required. Message bubble that is shown to the customer to open the ListPicker window
opts.replyMessage	InteractiveMessage	Required. Message bubble that is shown when the customer made a choice
opts.triggerAction	object	Required. Trigger Action when items are selected from the list

listPicker.addSection(section)

Add a section to the sections

Param	Type	Description
section	ListPickerSection	section

Apple.ListPickerSection

Component that groups a list of ListPickerItem objects and is part of a ListPicker

Properties

Name	Type	Description
items	Array.<ListPickerItem>	A list of ListPickerItem objects
multipleSelection	boolean	Indicates whether the customer can make multiple selections within the section. Defaults to false
order	Number	An integer containing the ordinal position for the section
title	string	Required title

new ListPickerSection(opts)

Param	Type	Description
opts	object	Collection of options
opts.items	Array.<ListPickerItem>	An array of ListPickerItem objects
opts.multipleSelection	boolean	Indicates whether the customer can make multiple selections within the section. Defaults to false
opts.order	Number	An integer containing the ordinal position for the section
opts.title	string	Required title

listPickerSection.addItem(item)

Add a list item to the section

Example

const section = new Apple.ListPickerSection({
  title: "Fruit"
})
section.addItem(new Apple.ListPickerItem({
  title: "Apples"
}))
section.addItem(new Apple.ListPickerItem({
  title: "Oranges"
}))

Param	Type	Description
item	ListPickerItem	item

Apple.ListPickerItem

Component that represents a selectable item inside a ListPickerSection

Properties

Name	Type	Description
identifier	string	Field identifying the item
image	string	Optional URL to a 30x30 image
order	number	Optional integer representing the ordinal position for the item
style	string	Optional item style. Defaults to default
title	string	Required title
subtitle	string	Optional subtitle,
params	string	Optional params,

new ListPickerItem(opts)

Param	Type	Description
opts	object	Collection of options
opts.identifier	string	Optional Unique identifier
opts.image	string	Optional URL to a 30x30 image
opts.order	Number	Optional integer representing the ordinal position for the item
opts.style	string	Optional item style. Defaults to default
opts.title	string	Required title
opts.subtitle	string	Optional subtitle
opts.params	string	Optional subtitle

Apple.AuthRequest

Authenticate a customer using the OAuth protocol

Properties

Name	Type	Description
oauth2	Oauth2	Required. Oauth2 collection of keys
receivedMessage	InteractiveMessage	Required. Message bubble that is shown to the customer to start the authentication
replyMessage	InteractiveMessage	Required. When the customer’s device receives a authentication request, the Messages app uses the replyMessage to set the style, content, and images for the reply message bubble that the Messages app displays after the customer authenticates and returns a reply to the business.

new AuthRequest(opts)

Example

const authRequest = new Apple.AuthRequest({
  oauth2: new Apple.Oauth2({
    responseType: "code",
    scope: ["email", "profile"],
    state: "security_token",
    responseEncryptionKey: "BFz948MTG3OQ0Q69 <truncated>",
    clientSecret: "client_secret"
  }),  
  receivedMessage: new Apple.InteractiveMessage({
    title: "Sign In to Business Chat Sandbox"
  }),
  replyMessage: new Apple.InteractiveMessage({
    title: "You are signed in!"
  })
})

Param	Type	Description
opts	object	Collection of options
opts.oauth2	Oauth2	Required. Oauth2 collection of keys
opts.receivedMessage	InteractiveMessage	Required. Message bubble that is shown to the customer to open the authentication request window
opts.replyMessage	InteractiveMessage	Required. Message bubble that is shown when the customer authenticated

Apple.Oauth2

Keys for the OAuth2 authentication request used with a AuthRequest

Properties

Name	Type	Description
clientSecret	string	Required. The secret provisioned by the authorization server
responseEncryptionKey	string	Required. The Base64-encoded public key that encrypts the access token returned in the response
responseType	string	Required. Indicates the type of authentication request
scope	Array.<string>	Required. Array of scopes that describe the granted access for read and write
state	string	Required. Indicates the state of the authentication request

new Oauth2(opts)

Example

const authRequest = new Apple.AuthRequest({
  oauth2: new Apple.Oauth2({
    responseType: "code",
    scope: ["email", "profile"],
    state: "security_token",
    responseEncryptionKey: "BFz948MTG3OQ0Q69 <truncated>",
    clientSecret: "client_secret"
  }),  
  receivedMessage: new Apple.InteractiveMessage({
    title: "Sign In to Business Chat Sandbox"
  }),
  replyMessage: new Apple.InteractiveMessage({
    title: "You are signed in!"
  })
})

Param	Type	Description
opts	object	Collection of options
opts.clientSecret	string	Required. The secret provisioned by the authorization server
opts.responseEncryptionKey	string	Required. The Base64-encoded public key that encrypts the access token returned in the response
opts.responseType	string	Required. Indicates the type of authentication request
opts.scope	Array.<string>	Required. Array of scopes that describe the granted access for read and write
opts.state	string	Required. Indicates the state of the authentication request