Shortcode: ^template()

Add structured message templates for Facebook and Slack.

^template(JSON)

Parameter Sample Value Description
JSON [See examples below] Required. JSON object per platform specifications detailed below and in documentation.

Details

Send structured template messages by passing in a JSON object per the specifications on each platform's respective messaging API documentation pages (see Facebook and Slack.)

Facebook Templates

Facebook templates come in many flavors (with new ones being created each day.) The primary templates used in Messenger Bots are Generic Templates and Button Templates. That being said, the template shortcode is expected to work with all Template types.

The JSON object passed into ^template() is the payload object in the "message" JSON from the Facebook documentation.

A Primer on Buttons

Each template can have multiple button types associated with it -- the most common of which are:

This means, if a postback is "start chatting", it will match the following trigger:

+ start chatting
- Hello there! You just pressed a postback button.

The ^template() shortcode will support all buttons, not just the ones mentioned above.

Generic Template

A Generic Template allows you to send a card with a title, an image attachment (optional), an outbound link (optional), a short description (optional), and buttons (optional). See the full documentation page for latest Facebook requirements.

Another common way to use Generic Templates is to send a carousel of these templates, which users can use to swipe through multiple cards of content. To do this, simply pass in more element objects into the elements key.

Example Usage

+ peters hats
- ^template({"template_type":"generic","elements":[{"title":"Welcome to Peter's Hats!","subtitle":"We've got the right hat for everyone.","item_url":"petersapparel.parseapp.com","image_url":"https://petersfancybrownhats.com/company_image.png","buttons":[{"type":"web_url","title":"View Website","url":"https://petersfancybrownhats.com"},{"type":"postback","title":"Start Chatting","payload":"start chatting"}]}]})
 
+ send a carousel
- ^template({"template_type":"generic","elements":[{"title":"Card One","subtitle":"card one subtitle","image_url":"https://site.com/image1.png","buttons":[{"type":"postback","title":"Start Chatting","payload":"start chatting"}]}, {"title":"Card Two","subtitle":"card two subtitle","image_url":"https://site.com/image2.png","buttons":[{"type":"web_url","title":"View Website","url":"https://sitetwo.com"}]}]})
Platform Notes How It Looks
Facebook
  • Titles are required. They have an 80 character limit.
  • Not all properties are required. See the documentation to figure out which ones are required and any other limits on these properties.
  • Send at most three buttons.
  • Send at most ten elements.

Button Template

A Button Template allows you to send a long text string with a set of 1-3 attached buttons.

Example Usage

+ button template
- ^template({"template_type":"button", "text": "This is some sample button template text.", "buttons":[{"type":"web_url","title":"View Website","url":"https://google.com"},{"type":"postback","title":"Start Chatting","payload":"start chatting"}]})
Platform Notes How It Looks
Facebook
  • Text is required and has a 640 character limit.
  • Send at most three buttons.
Slack Attachments

Slack attachments are more freeform than Facebook templates. Pass in parameters into the attachments object as desired to format your message attachments per your requirements.

Pass an "attachments" object into the ^template() shortcode, like this example:

Example Usage

+ slack attachment
- ^template({"attachments":[{"text":"Choose a game to play","fallback":"You are unable to choose a game","callback_id":"wopr_game","color":"#3AA3E3","attachment_type":"default","actions":[{"name":"game","text":"Chess","type":"button","value":"chess"},{"name":"game","text":"Falken's Maze","type":"button","value":"maze"},{"name":"game","text":"Thermonuclear War","style":"danger","type":"button","value":"war"}]}]})

A Primer on Buttons

In Slack, the payload for a "postback"-style button -- one that will match against a trigger and return a response from the bot is the "value" attribute in a "button" element.

In the above example, the value "war" for "Thermonuclear War" will match the following trigger:

+ war
- You pressed Thermonuclear War! That's nuclear!
Before you are able to press buttons in any attachment and expect a payload to return to your bot, you must follow these Slack configuration steps for Interactive Messages.
Platform Notes How It Looks
Facebook
  • Not all properties are required. See the documentation to figure out which ones are required and any other limits on these properties.
  • For working Slack buttons, you must follow the additional configuration steps for Interactive Messages here.
  • Alternatively, for Slack attachments with a set of buttons, look at ^buttonsSlack().