flowai-js-templates

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

message.addExpirationTime(expirationTime)

A convenience method to add Expiration time to the last response template of a RBM 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
expirationTime	ExpirationTime	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

oauth2.addScope(scope)

Add a scope to the list of scopes

Param	Type	Description
scope	string	scope

Apple.CustomInteractiveData

Provide a unique user experience with custom interactive messages

Properties

Name	Type	Description
appIcon	string	Required. URL to an image representing the app icon of the iMessage extension
appId	string	Required. The App Store identifier of the iMessage extension.
appName	string	Required. The name of the iMessage extension
url	string	Required. A URL string containing data that the Messages app sends to the iMessage extension
useLiveLayout	bool	Required. Determines whether the Messages app should use Live Layout
receivedMessage	InteractiveMessage	Required. Message bubble that is shown to the customer to open the CustomInteractiveData 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.

new CustomInteractiveData(opts)

Example

const custom = new Apple.CustomInteractiveData({
  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"
  }),
  appId: "app-store-id",
  appName: "Name of the App",
  appIcon: "https://source.unsplash.com/random",
  useLiveLayout: false,
  url: "?data=passed-to-app&data2=more-data-passed-to-app"
})

Param	Type	Description
opts	object	Collection of options
opts.appIcon	string	Required. URL to an image representing the app icon of the iMessage extension
opts.appId	string	Required. The App Store identifier of the iMessage extension.
opts.appName	string	Required. The name of the iMessage extension
opts.url	string	Required. A URL string containing data that the Messages app sends to the iMessage extension
opts.useLiveLayout	bool	Required. Determines whether the Messages app should use Live Layout
opts.receivedMessage	InteractiveMessage	Required. Message bubble that is shown to the customer to open the CustomInteractiveData window
opts.replyMessage	InteractiveMessage	Required. Message bubble that is shown when the customer made a choice

---

Apple.InteractiveMessage

Message that renders in a bubble either shown as the received message that allows a customer to open for example a ListPicker, TimePicker or PayRequest. Or as a reply message that is shown after a customer makes a selection,

Properties

Name	Type	Description
title	string	The main title shown in the header of the message bubble
subtitle	string	The subtitle that appears under the main title in the received message bubble
secondarySubtitle	string	A right-aligned title. Limited to 512 characters. Only custom interactive messages support this.
tertiarySubtitle	string	A right-aligned subtitle. Limited to 512 characters. Only custom interactive messages support this.
image	string	Optional URL to a 30x30 image
imageTitle	string	The attached image's title. Limited to 512 characters. Only custom interactive messages support this.
imageSubtitle	string	The attached image's subtitle. Limited to 512 characters. Only custom interactive messages support this.
style	string	A style that controls the size of the view rendered by Live Layout can be icon, small, large. The default is icon.

new InteractiveMessage(opts)

Param	Type	Description
opts	object	Collection of options
opts.title	string	Required title
opts.subtitle	string	Optional subtitle
opts.secondarySubtitle	string	A right-aligned title
opts.tertiarySubtitle	string	A right-aligned subtitle
opts.image	string	Optional URL to a 30x30 image
opts.imageTitle	string	The image's title
opts.imageSubtitle	string	The image's subtitle
opts.style	string	A style that controls the size of the view

---

Google Business Messages (Preview)

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

GBM.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
containsRichText	boolean	True by default, indicates that the message contains rich text. If the message contains invalid formatting, returns an error.

new Text(opts)

Example

const text = new GBM.Text('Want a free soda?')
text.addSuggestion(new GBM.Suggestion({
  label: 'Yes',
  data: 'yes'
}))
text.addSuggestion(new GBM.Suggestion({
  label: 'No',
  data: 'no'
}))

Example

const text = new GBM.Text('Hello, here is some **bold text**, *italicized text*, and a [link](https://www.google.com).')

Param	Type	Description
opts	object | string	Collection of options or the text
opts.text	string	Required
opts.containsRichText	boolean	Optional

GBM.Card

Send a related information, Media or Suggestion components

Properties

Name	Type	Description
title	string	Main title of the card
description	string	Optional description
media	Media	Optional Media
suggestions	Array.<Suggestion>	Optional set of Suggestion components

new Card(opts)

Example

const suggestion1 = new GBM.Suggestion({
  label: "Label",
  type: "url",
  url: "https://..."
})

const suggestion2 = new GBM.Suggestion({
  label: "Label",
  type: "url",
  url: "https://..."
 })

const card = new GBM.Card({
  title: "Awesome title",
  description: "Some description",
  media: new GBM.Media({
   url: "https://...",
   type: "image"
  })
})
card.addSuggestion(suggestion1)
card.addSuggestion(suggestion2)

Param	Type	Description
opts	object	Collection of options
opts.title	string	Optional
opts.description	string	Optional
opts.media	Media	Optional Media

card.addSuggestion(suggestion)

Add a suggestion to the card

Param	Type	Description
suggestion	Suggestion	suggestion

GBM.Carousel

Template that displays a set of Card templates

Properties

Name	Type	Description
cardWidth	string	The width of the cards in the carousel, SMALL, MEDIUM or CARD_WIDTH_UNSPECIFIED
cards	Array.<Card>	Set of Card templates

new Carousel(opts)

Example

const card1 = new GBM.Card({
  title: "Awesome title 1",
  description: "Some description 1",
  media: new GBM.Media({
   fileUrl: "https://..."
  })
})

const card2 = new GBM.Card({
  title: "Awesome title 2",
  description: "Some description 2",
  media: new GBM.Media({
   fileUrl: "https://...",
  })
})

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

Example

// Short hand

const carousel = new GBM.Carousel([
  new GBM.Card({
    title: "Awesome title 1",
    description: "Some description 1",
    media: new GBM.Media({
     fileUrl: "https://..."
    })
  }),
  new GBM.Card({
    title: "Awesome title 2",
    description: "Some description 2",
    media: new GBM.Media({
     fileUrl: "https://..."
    })
  })
])

Param	Type	Description
opts	object | Array.<Card>	Collection of options or shorthand for a collection of Card templates
opts.cardWidth	string	Optional. Width of the cards in the carousel
opts.cards	Array.<Card>	Optional list of Card templates

carousel.addCard(card)

Add a Card to the list of cards

Param	Type	Description
card	Card	Card to add to the carousel

GBM.Suggestion

A suggestion for the user to reply with a predefined text, trigger an event or initiate a native action like dialing a phone number

Properties

Name	Type	Description
type	string	Type of suggestion, default is text (text, url, phone, live_agent, auth)
text	string	Text that is shown in the suggested action. Maximum 25 characters.
data	string	Value that is being send as the suggestion, empty if type is location
url	string	URL to open in case it's a url type
phoneNumber	string	phone number to dial in case of a phone type
auth	Auth	phone number to dial in case of a phone type
params	Array.<Param>	Optional parameters associated with the suggestion

new Suggestion()

Example

// Text suggestion
const textSuggestion = new GBM.Suggestion({ 
  type: "text",
  text: "Say hi",
  data: "Hello"
})

// With param
const textSuggestion = new GBM.Suggestion({ 
  type: "text",
  text: "Buy product",
  params: new Param('itemId', '332223323')
})

// With params
const textSuggestion = new GBM.Suggestion({ 
  type: "text",
  text: "Buy products",
  params: [
    new Param('itemId', '332223323'),
    new Param('itemId', '113432143')
  ]
})

// Short hand syntax
const textSuggestion = new GBM.Suggestion("yes")

// Event suggestion
const textSuggestion = new GBM.Suggestion({ 
  type: "event",
  text: "Main menu",
  data: "MAIN_MENU"
})

// Open URL suggestion
const urlSuggestion = new GBM.Suggestion({ 
  type: "url",
  text: "Open link",
  url: "https://foo.bar"
})

// Dial action
const dialSuggestion = new GBM.Suggestion({ 
  type: "phone",
  text: "Dial",
  phoneNumber: "[phone]"
})

// Auth suggestion
const authSuggestion = new GBM.Suggestion({ 
  type: "auth",
  auth: new GBM.Auth({
    clientId: 'CLIENT_ID',
    codeChallenge: 'CODE_CHALLENGE',
    scopes: ['SCOPE']
  })
})

// Live agent suggestion
const liveAgentSuggestion = new GBM.Suggestion({ 
  type: "live_agent"
})

const text new GBM.Text("Make a suggestion")
text.addSuggestion(textSuggestion)
text.addSuggestion(urlSuggestion)
text.addSuggestion(authSuggestion)
text.addSuggestion(liveAgentSuggestion)

Param	Type	Description
opts.type	string	Required type, default is text (text, url, phone, live_agent, auth)
opts.text	string	Required unless of type auth or live_agent
opts.data	string	Optional data, required if type is text
opts.url	string	Required if type is url
opts.phoneNumber	string	Required if type is phone
opts.auth	Auth	Required if type is auth
opts.params	Param | Array.<Param>	Optional Param or array or Array of Params related to this Suggestion

GBM.Auth

The Authentication request suggestion prompts users to sign in to an OAuth 2.0-compliant application, passing authentication codes to confirm account data and enabling customized user experiences and detailed conversation flows.

Properties

Name	Type	Description
clientId	string	Required. The ID of the application that asks for authorization.
codeChallenge	string	Required. Required. The code challenge used to exchange access tokens.
scopes	Array.<string>	Required. An array that specifies the scopes of the request.

new Auth(opts)

Example

const suggestion = new GBM.Suggestion({
  type: 'auth',
  auth: new GBM.Auth({
    clientId: 'CLIENT_ID',
    codeChallenge: 'CODE_CHALLENGE',
    scopes: ['SCOPE']
  })
})

Param	Type	Description
opts	object	Collection of options
opts.clientId	string	Required. The ID of the application that asks for authorization.
opts.codeChallenge	string	Required. Required. The code challenge used to exchange access tokens.
opts.scopes	Array.<string>	Required. An array that specifies the scopes of the request.

auth.addScope(scopes)

Add a scopes to the list of scopes

Param	Type	Description
scopes	string	scopes

GBM.Media

A media file within a rich Card

Properties

Name	Type	Description
height	string	Optional. The height of the media within a rich card. SHORT = 112 DP. MEDIUM = 168 DP. TALL = 264 DP. Not available for rich card carousels when the card width is set to SMALL.
fileUrl	string	Required. Publicly reachable URL of the file. The platform determines the MIME type of the file from the content-type field in the HTTP headers when the platform fetches the file. The content-type field must be present and accurate in the HTTP response from the URL. Maximum 5 MB. Supported content types: image/jpeg, image/jpg, image/png
thumbnailUrl	string	Optional. Publicly reachable URL of the thumbnail. If you don't provide a thumbnail URL, the platform displays a blank placeholder thumbnail until the user's device downloads the file. Maximum 25 KB. Supported content types: image/jpeg, image/jpg, image/png
forceRefresh	string	Optional. If set, the platform fetches the file and thumbnail from the specified URLs, even if the platform has cached copies of the file (and/or of the thumbnail).
altText	string	Optional. Text describing the details about the media for accessibility purposes.

new Media()

Param	Type	Description
opts.height	string	Optional
opts.fileUrl	string	Required
opts.thumbnailUrl	string	Optional
opts.forceRefresh	bool	Optional
opts.forceRefresh	bool	Optional

---

WhatsApp (Preview)

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

WhatsApp.Text

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

Properties

Name	Type	Description
text	string	Text to show
previewUrl	boolean	True by default, will render a preview if a URL is inside the text message

new Text(opts)

Example

const text = new WhatsApp.Text('Want a free soda?')

Example

const text = new WhatsApp.Text('Hello, here is some **bold text**, *italicized text*, and a https://www.google.com')

Param	Type	Description
opts	object | string	Collection of options or the text
opts.text	string	Required
opts.previewUrl	boolean	Optional

WhatsApp.Audio

Deliver an audio to a user.

Properties

Name	Type	Description
title	string	Describes the audio
url	string	URL to the audio

new Audio(opts)

Example

const audio = new WhatsApp.Audio("https://...")

Param	Type	Description
opts	object | string	Options or shorthand a URL
opts.url	string	Required

WhatsApp.Document

Deliver a document to a user.

Properties

Name	Type	Description
title	string	Describes the document
filename	string	Filename of the document
url	string	URL to the document

new Document(opts)

Example

const document = new WhatsApp.Document({
  title: "Awesome title",
  url: "https://..."
})

Example

const document = new WhatsApp.Document("https://...")

Param	Type	Description
opts	object | string	Options or shorthand a URL
opts.title	string	Optional
opts.filename	string	Optional
opts.url	string	Required

WhatsApp.Image

Deliver an image to a user.

Properties

Name	Type	Description
title	string	Describes the image
url	string	URL to the image

new Image(opts)

Example

const image = new WhatsApp.Image({
  title: "Awesome title",
  url: "https://..."
})

Example

const image = new WhatsApp.Image("https://...")

Param	Type	Description
opts	object | string	Options or shorthand a URL
opts.title	string	Required
opts.url	string	Required

WhatsApp.Video

Deliver a video to a user.

Properties

Name	Type	Description
title	string	Describes the video
url	string	URL to the video

new Video(opts)

Example

const video = new WhatsApp.Video({
  title: "Awesome title",
  url: "https://..."
})

Example

const image = new WhatsApp.Video("https://...")

Param	Type	Description
opts	object | string	Options or shorthand a URL
opts.title	string	Optional
opts.url	string	Required

WhatsApp.Sticker

Deliver a sticker to a user

Properties

Name	Type	Description
title	string	Describes the sticker
stickerId	string	ID to the sticker

new Sticker(opts)

Example

const sticker = new WhatsApp.Sticker("121233212321")

Param	Type	Description
opts	object | string	Options or shorthand a ID
opts.stickerId	string	Required

WhatsApp.Location

Send or display a location on a map to a user

Properties

Name	Type	Description
lat	string	Latitude
long	string	Longitude
name	string	Name of the location
address	string	Address of the location. Only displayed if name is present.

new Location()

Example

const location = new WhatsApp.Location({
  lat: "37.331860",
  long: "-122.030248",
  name: "HQ",
  address: "Infinite Loop 1"
})

Param	Type	Description
opts.lat	string	Required
opts.long	string	Required
opts.name	string	Optional
opts.address	string	Optional

WhatsApp.Contacts

Send one ore more Contact to a user.

Properties

Name	Type	Description
contacts	Array.<Contact>	One ore more contacts

new Contacts(contacts)

Example

const contacts = new WhatsApp.Contacts([
  new WhatsApp.Contact({
    name: new WhatsApp.Name({
      formattedName: "Jane Doo",
      firstName: "Jane",
      lastName: "Doo",
      middleName: "Van"
    }),
    birthday: "2000-08-18",
    organization: new WhatsApp.Organization({
      company: "WhatsApp",
      department: "Design",
      title: "Manager"
    }),
    addresses: [
      new WhatsApp.Address({
        type: 'HOME',
        street: "1 Hacker Way",
        city: "Menlo Park",
        zip: "94025",
        state: "CA",
        country: "United States",
        countryCode: "US"
      })
    ],
    emails: [
      new WhatsApp.EmailAddress({
        type: 'WORK',
        email: "[e-mail]"
      })
    ],
    phones: [
      new WhatsApp.PhoneNumber({
        type: 'WORK',
        phone: "[phone]"
      })
    ],
    urls: [
      new WhatsApp.WebsiteAddress({
        type: 'WORK',
        url: "https://www.some.fake.org"
      })
    ]
  })
])

Param	Type	Description
contacts	Array.<Contact>	Required

components

WhatsApp.Contact

Component used in a Contacts template

Properties

Name	Type	Description
name	Name	Optional, full contact name
organization	Organization	Optional, contact organization information
addresses	Array.<Address>	Optional, or more contact addresses
birthday	string	Optional, contact date or birth in ISO format
emails	Array.<EmailAddress>	Optional, or more contact email addresses
phones	Array.<PhoneNumber>	Optional, or more contact phone numbers
urls	Array.<WebsiteAddress>	Optional, or more URLs

new Contact(opts)

A WhatsApp contact to share

Example

const contact = new WhatsApp.Contact({
  name: new WhatsApp.Name({
    formattedName: "Jane Doo",
    firstName: "Jane",
    lastName: "Doo",
    middleName: "Van"
  }),
  birthday: "2000-08-18",
  organization: new WhatsApp.Organization({
    company: "WhatsApp",
    department: "Design",
    title: "Manager"
  }),
  addresses: [
    new WhatsApp.Address({
      type: 'HOME',
      street: "1 Hacker Way",
      city: "Menlo Park",
      zip: "94025",
      state: "CA",
      country: "United States",
      countryCode: "US"
    })
  ],
  emails: [
    new WhatsApp.EmailAddress({
      type: 'WORK',
      email: "[e-mail]"
    })
  ],
  phones: [
    new WhatsApp.PhoneNumber({
      type: 'WORK',
      phone: "[phone]"
    })
  ],
  urls: [
    new WhatsApp.WebsiteAddress({
      type: 'WORK',
      url: "https://www.some.fake.org"
    })
  ]
})

Param	Type	Description
opts	object	Optional properties
opts.name	Name	Optional, full contact name
opts.organization	Organization	Optional, contact organization information
opts.addresses	Array.<Address>	Optional, or more contact addresses
opts.birthday	string	Optional, contact date or birth in ISO format
opts.emails	Array.<EmailAddress>	Optional, or more contact email addresses
opts.phones	Array.<PhoneNumber>	Optional, or more contact phone numbers
opts.urls	Array.<WebsiteAddress>	Optional, or more URLs

WhatsApp.Address

Component used in a Contact component

Properties

Name	Type	Description
type	string	Optional, type of address, must be HOME or WORK
street	string	Optional, the street address
city	string	Optional, the city name of the address.
zip	string	Optional, the ZIP code of the address.
state	string	Optional, the state abbreviation for U.S. addresses, or the region/province for non-U.S. addresses.
country	string	Optional, full country name
countryCode	string	Optional, the two-letter country abbreviation of the address.

new Address(opts)

The address of a contact

Example

const address = new WhatsApp.Address({
  street: "1 Hacker Way",
  city: "Menlo Park",
  zip: "94025",
  state: "CA",
  country: "United States",
  countryCode: "US"
})

Param	Type	Description
opts	object	Optional properties
opts.type	string	Optional, type of address, must be HOME or WORK
opts.street	string	Optional, the street address
opts.city	string	Optional, the city name of the address
opts.zip	string	Optional, the ZIP code of the address
opts.state	string	Optional, the state abbreviation for U.S. addresses, or the region/province for non-U.S. addresses
opts.country	string	Optional, full name of the country
opts.countryCode	string	Optional, the two-letter country abbreviation of the address

WhatsApp.EmailAddress

Component used in a Contact component

Properties

Name	Type	Description
type	string	Optional, type of email address, must be HOME or WORK
email	string	Required, valid email address

new EmailAddress(opts)

The email address of as contact

Example

const email = new WhatsApp.EmailAddress({
  email: "[e-mail]"
})

Example

// Shorthand
const email = new WhatsApp.EmailAddress("[e-mail]")

Param	Type	Description
opts	object	Optional properties
opts.type	string	Optional, type of email address, must be HOME or WORK
opts.email	string	Required, valid email address

WhatsApp.Name

Component used in a Contact component

Properties

Name	Type	Description
formattedName	string	Required, valid full name of a contact
firstName	string	Optional, first name of a contact
lastName	string	Optional, last name of a contact
middleName	string	Optional, middle name of a contact
suffix	string	Optional, name suffix of a contact
prefix	string	Optional, name prefix of a contact

new Name(opts)

The full name of a contact

Example

const name = new WhatsApp.Name({
  formattedName: "Jane Doo",
  firstName: "Jane",
  lastName: "Doo",
  middleName: "Van"
})

Example

// Shorthand
const name = new WhatsApp.Name("Jane Doo")

Param	Type	Description
opts	object | string	Optional properties, or name for shorthand
opts.formattedName	string	Required, valid name contact
opts.firstName	string	Optional, first name of a contact
opts.lastName	string	Optional, last name of a contact
opts.middleName	string	Optional, middle name of a contact
opts.suffix	string	Optional, name suffix of a contact
opts.prefix	string	Optional, name prefix of a contact

WhatsApp.Organization

Component used in a Contact component

Properties

Name	Type	Description
company	string	Optional, name of the contact's company
department	string	Optional, department name of a contact
title	string	Optional, contact's business title

new Organization(opts)

Contact organization information

Example

const organization = new WhatsApp.Organization({
  company: "WhatsApp",
  department: "Design",
  title: "Manager"
})

Example

// Shorthand
const organization = new WhatsApp.Organization("WhatsApp")

Param	Type	Description
opts	object | string	Optional properties, or company name for shorthand
opts.company	string	Optional, name of the contact's company
opts.department	string	Optional, department name of a contact
opts.title	string	Optional, contact's business title

WhatsApp.PhoneNumber

Component used in a Contact component

Properties

Name	Type	Description
type	string	Optional, type of phone number, must be HOME or WORK
phone	string	Required, valid phone number

new PhoneNumber(opts)

The phone number of a contact

Example

const phone = new WhatsApp.PhoneNumber({
  phone: "[phone]"
})

Example

// Shorthand
const phone = new WhatsApp.PhoneNumber("[phone]")

Param	Type	Description
opts	object	Optional properties
opts.type	string	Optional, type of phone number, must be HOME or WORK
opts.phone	string	Required, valid phone number

WhatsApp.WebsiteAddress

Component used in a Contact component

Properties

Name	Type	Description
type	string	Optional, type of website, must be HOME or WORK
url	string	Required, valid URL

new WebsiteAddress(opts)

The website URL of a contact

Example

const url = new WhatsApp.WebsiteAddress({
  url: "https://www.fake.org"
})

Example

// Shorthand
const url = new WhatsApp.WebsiteAddress("https://www.fake.org")

Param	Type	Description
opts	object	Optional properties
opts.type	string	Optional, type of website, must be HOME or WORK
opts.url	string	Required, valid URL

---

Base classes

For reference, these are some core classes the generic and specific templates inherit from.

Base.Param

Data related to a generic Button, QuickReply or specific components like Suggestion

Properties

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

new Param()

Example

// Render a generic 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 generic 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

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

Example

// Generate an RBM suggestion that includes a param
const textSuggestion = new GBM.Suggestion({ 
  type: "text",
  text: "Buy product",
  params: new Param('itemId', '332223323')
})

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

Base.Template

Base class for all response templates

template.fallback

Optional fallback speech

Param	Type	Description
fallback	string	Required

Base.Text

Base template for text

Properties

Name	Type	Description
text	string	Text to show

new Text()

Example

const text = new Text('Want a free soda?')

Param	Type	Description
opts.text	string	Required