ChatFuel JSON API NodeJS library (TESTING)

This library enables you to create the right JSON format for the Chatfuel JSON API. It is lightweight (4.7k, 1.6k Gzipped) and is fully compatible with ES5 Node versions.

Chatfuel is an easy to use Messenger Bot creation platform.

Chatfuel JSON API

The Chatfuel JSON API is well documented on the Chatfuel.com website. It can be found inside Chatfuel's API doc and Facebook Developer Plateform.

Install

npm install --save chatfuel-jsonify

Library usage

This library helps you only to create the right JSON format. The result must then be read by Chatfuel API.

Getting started

var Chatfuel = require("chatfuel-jsonify");

Create an object

var chatfuelled = new Chatfuel();

Now you can start creating your final JSON result using the methods described below.

Create JSON format to send to Chatfuel

When you're ready to send all data to Chatfuel, start by getting the JSON format:

var result = chatfuelled.toJson();

You can send it using, for example, Express:

res.json(chatfuelled.toJson());

Methods (simple blocks)

.addMessage (message)

Use this response to send one text message.

Attribute	Type	Required	Description
message	string	yes	The message that will be shown to the user

Example

chatfuelled.addMessage("Test message 1");

#### .addImage (url)

Use this response to send image files. Messenger supports JPG, PNG and GIF images. If you are having issues with GIF rendering, please try to reduce the file size.

Attribute	Type	Required	Description
url	string	yes	The image url

Example

chatfuelled.addImage("https://media.giphy.com/media/3oz8xPKZN7EwfcD0ys/giphy.gif");

.addFile (url)

Use this response to send any other files, which are no larger than 25 MB.

Attribute	Type	Required	Description
url	string	yes	The file url

.addUserAttributes (name, value)

Set user attributes without having the user to tap any button.

Attribute	Type	Required	Description
name	string	yes	Attribute's name
value	string	yes	Attribute's value

Example

chatfuelled.addUserAttributes("age","30");

Galleries

.newGallery()

Create a new empty horizontal scrollable gallery. You need to add one element minimum using .addElementToGallery (described below)

Attribute	Type	Required	Description
galleryAspectRatio	string	no	Choose the gallery's image aspect ratio. Can be either "square" or "horizontal"

Return Gallery's ID

Example

var newGallery = chatfuelled.newGallery();

.sanitizeToButton (request_type, target, title)

Created a JSONified buttons for Chatfuel. Must be used with .addElementToGallery or .addButtons. You can set buttons to link to a block in the dashboard, open a website, or send another request to your backend.

Messenger also supports specialised buttons:

The Call button dials a phone number when tapped.
The Share button opens a share dialog in Messenger enabling people to share the bot message with their friends. (Gallery template only)

Attribute	Type	Required	Description
request_type	string	yes	Must be one of these: - web_url: URL - show_block: redirect to block - json_plugin_url: send another request to your backend - phone_number: call a phone number - [ONLY ON GALLERY] element_share: To share the current element
target	string	yes	Must be: - _if request_type = show_block: a list of block names (["block 1", "block 2"]) or - if request_type = web_url OR json_plugin_url: a web link or - if request_type = phone_number: a phone number (format: +19268881413).
title	string	yes	Button's title. Will be shown over the button.

Example

chatfuelled.sanitizeToButton("web_url", "https://www.google.ch/", "Go to Goole")

.addElementToGallery (galleryID, title, img_url, description, buttons...)

Add a new element to galleryID. An element is by a title, an image, a description and buttons to request input from the user. Each element can have up to 3 buttons.

Attribute	Type	Required	Description
galleryID	int	yes	The gallery ID. Use .newGallery() to get a new id
title	string	yes	The title of the gallery
img_url	string	yes	The image url
description	string	yes	Some description for the subtitle tag
button1	JSON	yes	1 to 5 buttons added as parameters. Use .sanitizeToButton() for each button to generate the needed code. See the example below
...		no
button3	JSON	no

Return Element's ID (necessary for addDefaultActionToElement)

Example

var elementID = chatfuelled.addElementToGallery(
  newGallery,
  "My first gallery",
  "https://www.jqueryscript.net/images/jQuery-Plugin-For-Stacked-Polaroid-Image-Gallery-Photopile.jpg",
  "My amazing description",
  chatfuelled.sanitizeToButton("web_url", "https://www.jqueryscript.net/gallery/jQuery-Plugin-For-Stacked-Polaroid-Image-Gallery-Photopile.html", "jQuery Gallery plugin"),
  chatfuelled.sanitizeToButton("show_block", ["Bye 1", "Bye 2"], "bye")
);

.addDefaultActionToElement (galleryID, elementID, type, url)

Optional The default action executed when the template is tapped.

Attribute	Type	Required	Description
galleryID	int	yes	The gallery ID. Use .newGallery() to get a new id
elementID	int	yes	The element's ID. Use .addElementToGallery() to get one
type	string	yes	The default action type. Set to "web_view" by default.
url	string	yes	The URL to which the user will be redirected when he/she tap over the gallery's element.
messenger_extensions	bool	no	messenger_extensions
webview_height_ratio	string	no	webview_height_ratio
fallback_url	string	no	fallback_url

Example

chatfuelled.addDefaultActionToElement(
  newGallery,
  elementID,
  "web_url",
  "https://www.google.com/");

Other methods

.addButtons (message, buttons...)

Use this function to add buttons to your responses. Buttons are limited to 3 items per message.

Attribute	Type	Required	Description
message	string	yes	The message that will be shown to the user over the button
button1	JSON	yes	The JSON representation of the button. Use .sanitizeToButton() for each button to generate the needed code. See the example below
button2	JSON	no	Same.
button3	JSON	no	Same.

Example

chatfuelled.addButtons(
  "my amazing buttons",
  chatfuelled.sanitizeToButton("web_url", "https://www.google.ch/", "Go to Goole"),
  chatfuelled.sanitizeToButton("web_url", "https://www.google.ch/maps", "Go to Maps"),
  chatfuelled.sanitizeToButton("show_block", ["Bye 1", "Bye 2"], "BYE 3")
);

TODO

Add exceptions support
Add logs (warn, error, info)

chatfuel-jsonify

ChatFuel JSON API NodeJS library (TESTING)