Chatfuel Chatbot JSON Guide - Guia

CHATFUEL CHATBOT
JSON GUIDE
MARC LITTLEMORE
WANT TO ADD JSON SUPER
POWERS TO YOUR CHATBOT?
You've built that amazing chatbot and you want to add a
gallery populated by your database. You reach for the
JSON API plugin and then you stop. How does it work?
What is JSON? What do GET and POST mean? Why are
there all of these curly and square brackets?
Don't worry!
JSON isn't that hard to learn and that's what I want to

show you. Read on and learn the basics of JSON and
how to use it with your Chatfuel chatbot.
WHAT THIS GUIDE WILL TEACH YOU

What JSON is and how we can use it
JSON basics and JSON data types
How to use Chatfuel's JSON API plugin
Chatfuel's JSON message responses
WWW.MARCLITTLEMORE.COM
WHO WROTE THIS GUIDE?
Hello! I’m Marc Littlemore.
I’m an experienced software engineer
with over 25 years of professional
experience. I’ve become an expert in
creating complex chatbots and
conversational commerce using
Chatfuel and my development skills.
I’ve helped thousands of people to add profitable integrations to their

chatbots with my YouTube videos and advice in the Chatfuel
communities on Facebook.
And I want to help you!
This Chatfuel Chatbot JSON Guide was written to help marketers and

non-developers to learn about JSON and to easily expand the
capabilities of their chatbots. JSON can seem pretty confusing, but it's
really simple once you know the basics... and that's what I'm going to
teach you!
Read on and learn how to harness the power of JSON!
WHAT IS JSON?
You’ll hear people talking about JSON a lot in the Chatfuel community and if
you’re new to software development, you probably have no idea what it
means.
JSON is an acronym which stands for JavaScript Object Notation. It’s an

easy way to store data and it's based on the JavaScript programming
language. The great thing is that it can be read and written by either a
human or a computer, and is really easy to generate from most programming
languages. We often use JSON to send data to or from a web server and, for
chatbots, we use it to send data to or from the user. Chatfuel can send JSON
to a server so you can request information and return it to the user. This is
done using the JSON API plugin.
Let's look at a basic JSON example so you can start to understand it:
As you can see in the example above, JSON consists of text enclosed by
quotation marks, separated by colons and commas, and wrapped in curly
brackets. JSON has many different data types which allow it to handle
strings ("text"), numbers, arrays ("lists"), objects ("containers"), booleans
("true or false") and a special type called null (which we'll talk about later!)
Let's explore what each of these data types look like in a JSON file.
JSON DATA TYPES
OBJECT
An object is a container which contains key and value pairs. This means we
need a string which is a key and a corresponding value, which can be any
JSON data type.
In our basic example above, we have 2 key and value pairs. The keys have to
be a string and are surrounded in quotation marks. A colon separates the
key (e.g. "firstName") from the value (e.g. "Marc") and in the example above,
the values are also strings. Notice that you can have multiple key and value
pairs and they are separated by a comma. The whole object must be
wrapped in curly brackets.
STRING
A string is a sequence of characters which can include punctuation or
numbers. As we saw above, the text is wrapped in quotation marks.
The example above shows that we have another object with a set of keys
(e.g. "name", "address", "city" and "postcode"). Each corresponding value is
a string and is some text within two quotation marks.
JSON DATA TYPES
NUMBER
A number can be a positive or negative integer (whole number) or floating
point number (which contains decimal places).
In the example above, we're setting keys with whole or floating point
numbers which represent our example beer information.
BOOLEAN
A boolean is a special datatype which only has two values. It can be either
true or false.
In the example above, the object contains two keys which have boolean
values. Notice that although the boolean value is true or false, this isn't a
string and it isn't wrapped in quotation marks. This is important to
remember as a boolean value is not a string.
JSON DATA TYPES
ARRAY
An array is a list of any JSON data values. You can use a single, or any
combination, of the supported JSON data types. The values of an array have
to be wrapped in square brackets.
In the example above, the "numbersArray" has a list of integers. Here we

only have a single data type. However in the "mixedArray", we have an
integer (100), a string ("Marc") and a boolean (true). You could also include
an object or even another array as a value.
NULL
This is a special data type which represents a missing value. If you're
passing JSON data to a server, you may not need this very often. Pro-tip: it
can be used with Chatfuel to remove a user attribute which has been set.
Watch my videos to find out how.
In the example above, the object contains a key with a single null value.
Notice that although it may look like a string, it isn't and should not be
wrapped in quotation marks. This is important to remember!
SO WHAT NOW?
You now understand the basics of JSON as a way to store and send data, and
that it has many data types. But how can we use it in our Chatfuel chatbots?
Chatfuel sends messages to and from Facebook's Messenger platform using

JSON. These JSON messages represent your bot's text, images, buttons,
galleries and so on. Chatfuel simplifies the creation of these messages with
its wonderful user interface, but behind the scenes, these messages are
being sent to Facebook as JSON and then shown to your bot users.
You can create some pretty complex chatbot experiences, but what if you
want to interact with services outside of Chatfuel? How can you add users
to your Mailchimp, ConvertKit or other email marketing tool? How can you
gather data from Google Sheets, Airtable or your database and show it to
your chatbot users? What if you want to add potential leads to your
Customer Relationship Managment (CRM) system, like Hubspot or Zoho?
This is where Chatfuel shows its super power.
Say hello to the JSON API plugin!
The JSON API plugin will allows you to make requests from your bot to
external services using an HTTP request. This is a standard internet
protocol and is used to send data from your chatbot to another server, wait
for a response, and retrieve any data it sends back. This opens up a world of
opportunities to make your chatbot really powerful.
Let's learn more about the Chatfuel JSON API!
CHATFUEL JSON API
The Chatfuel JSON API plugin allows your chatbot to send a request to a
remote server and to receive a response back. The request is either an HTTP
GET or HTTP POST request. There are other types of HTTP request but
Chatfuel doesn't use them in their JSON API. The response can contain
JSON data which Chatfuel could use to update your chatbot.
GET REQUEST
You should use a GET request when you're asking for data which won't
change. A GET request uses a URL to retrieve information from a server. If
more specific data is required, you will need to attach a "query string"
(sometimes known as "query parameters") to the end of the URL. This can be
useful if you want to send user attributes from Chatfuel. If you are adding
query parameters, the URL is separated by a question mark (?) before the
first parameter, and ampersands (&) between each new parameter. Here is
an example URL with two query parameters:
https://example-server.com/api/data?param1=1234567&param2=Marc
POST REQUEST
You should use a POST request when you plan to send data in order to
create or update information on a server. Like a GET request, a POST
request uses a URL, however it also has a request body attached. This body
can take many forms, but for Chatfuel it is either JSON data, or a set of key
and value pairs known as "URL encoded" data (more on this later).
I'll show you some examples of how to use the Chatfuel JSON API and how
you send data with it.
IMPORTANT: Your server must respond to the request within 10

seconds or Chatfuel will assume the request has timed out and it
won't do anything.
CHATFUEL JSON API
To add the JSON API plugin to your Chatfuel block, click on the "+ More"
icon:
Next click on JSON API and it will appear in your block flow:
Now you need to choose what type of request to make - either GET or POST.
CHATFUEL JSON API
GET REQUEST
Choose the type GET in the dropdown menu.
In the URL box, add the URL you're making the GET request to.
Add any query parameters to the request (if needed).
These are key and value pairs in the form of "key=value".
The first one must be prefixed with a question mark (?) after the URL.
Example: https://your-server.com?firstname=Marc
Add an ampersand (&) between multiple query parameters.
Example: https://your-server.com?firstname=Marc&zipcode=12345
You can add in Chatfuel attributes using double curly brackets and it
will autocomplete your entry.
You can set the query parameters for the request using plain text or using
one of your Chatfuel user attributes. In the example below, we'll set a query
parameter called "firstname" using the Chatfuel "first name" user attribute:
Using Chatfuel's user attributes is a great way to send data from your
chatbot to your server for retrieving specific information.
POST REQUEST
Choose the type POST in the dropdown menu.
In the URL box, add the URL you're making the POST request to.
Choose the type of POST request to make in the "send" panel. The options
are "Full JSON profile", "JSON", or "URL encoded".
POST: FULL JSON PROFILE

This sends JSON data with the request to your server. It includes all of
the Chatfuel system attributes (e.g. Facebook first name, last name,
Messenger identifier) AND all of the user-specific attributes which have
been set when someone uses your chatbot.
Your server should expect a request containing JSON data in its body.
POST: JSON
This sends a JSON data to your server but it's up to you to enter the data
in a valid JSON format.
Enter your data as a JSON object using key and value pairs and the
Chatfuel editor will validate your JSON as you type.
You can use Chatfuel attributes by typing double curly brackets as you
would in other Chatfuel blocks.
Your server should expect a request containing JSON data in its body.
POST: URL ENCODED
This sends URL-encoded data to your server. URL encoding represents
the data sent by a form on a web page. It sends the data in the request as
key and value pairs but this time it isn't JSON data.
Click the "+ Add parameter" button and enter your data as key and value
pairs into the text boxes Chatfuel provides. For example, type "firstName"
as your key (called "title") and "Marc" as your value.
Values can be Chatfuel attributes. Type double curly brackets as you
would in other Chatfuel blocks.
Your server should expect a request containing URL-encoded data in its
body.
CHATFUEL JSON RESPONSES
Chatfuel expects any HTTP request made with the JSON API plugin to
respond with a HTTP 200 status code within 10 seconds. If the request
doesn't do this, Chatfuel will consider this to be an error and it will break
your chatbot flow.
PRO-TIP: If you tick the "Report errors in the bot" checkbox, you
will be able to see the error from your server if there is a problem
with the response. Only use this whilst debugging your chatbot.
Don't leave it ticked when you go live with your chatbot or your
users will see this.
Chatfuel uses a combination of Facebook Messenger standard messages,

such as text messages, images, files, and other templates like galleries. It
also allows some Chatfuel-specific responses such as setting user attributes
and redirecting a user to specified blocks in your chatbot. All of the
responses should be delivered as JSON data when you use the JSON API
blocks.
Multiple messages can be returned in a JSON response. As you'll see in the

examples, this is a JSON object with a key of "messages" and an array of
objects representing each message. However, it's not possible to set the
Messenger typing indicator, as shown below, in your responses.
To do this you will need to use the JSON API block multiple times, once for
each message, and add the typing indicator block between each one. This
will display the typing indicator to your user each time.
Let's look at the different JSON responses you can use to power up your
chatbot. Make sure that you update each response with your own data.
TEXT MESSAGE
This JSON response will send a simple text message back to the user. You
can send multiple messages in one response if you want to.
IMAGE MESSAGE
Use an attachment response with an "image" type to send an image. The
URL should point to a valid image file. This must be either a JPEG, GIF or
PNG file format. The maximum size allowed is 25MB.
VIDEO MESSAGE
Use an attachment response with a "video" type to send a video. The URL
should point to a valid video file. This must be an MP4 file format and the
maximum size allowed is 25MB.
AUDIO MESSAGE
Use an attachment response with a "audio" type to send an audio file. The
URL should point to a valid audio file. This must be an MP3, OGG or WAV file
format and the maximum size allowed is 25MB.
FILE MESSAGE
Use an attachment response with a "file" type to send any file type for
download. The maximum size allowed is 25MB.
PRO-TIP: You can host your files in any place that allows the files
to be publicly accessible from the web. Many people host their
files on their own web server, but you can easily allow file
downloads from Google Drive or Dropbox too.
Let me show you how...
GOOGLE DRIVE FILE DOWNLOAD
1. Upload your file to Google Drive.
2. Create a shareable link to the file in the Google Drive interface. This
link is a viewable version of your file, but this isn’t a link to the
downloadable version of the file.
3. The shareable URL will be in the following format:
https://drive.google.com/open?id=YOUR-FILE-ID
Change the file URL above to be a downloadable link, making sure you
replace YOUR-FILE-ID with your own file identifier from your link, as
shown below:
https://drive.google.com/uc?export=download&id=YOUR-FILE-ID
4. Add the file URL above as the "url" in the following JSON example, and
the file can then be downloaded by your users.
DROPBOX FILE DOWNLOAD
1. Upload your file to Dropbox.
2. Create a shareable link to the file in the Dropbox interface. This link is a
viewable version of your file, but this isn’t a link to the downloadable
version of the file.
3. The shareable link will be in the following format:
https://www.dropbox.com/s/some-code/FILE-NAME.PDF?dl=0
Change the file URL above to be a downloadable link, making sure you
replace FILE-NAME with your own file name from your link, by changing
"dl=0" to "dl=1", as shown below:
https://www.dropbox.com/s/some-code/FILE-NAME.PDF?dl=1
4. Add the file URL above as the "url" in the following JSON example, and
the file can then be downloaded by your users.
GALLERY MESSAGE
Use a template response with the template type "generic" to display a gallery.
A gallery is really useful to display multiple visual items that the user can
scroll through. You can display a maximum of 10 gallery elements and each
element has a number of user defined properties (see next page for more
details). The gallery can have one of two aspect ratios for the images used in
each element - either "horizontal" or "square". The horizontal gallery has to
have images with an aspect ratio of 1.91:1 (width to height) and square
images have a 1:1 aspect ratio (i.e. their width is the same as their height).
An example gallery template
GALLERY MESSAGE ELEMENT

Each gallery element consists of 5 properties. The only property that is
required is the title.
title - The title to display with a maximum of 80 characters.

subtitle - [OPTIONAL] The subtitle with a maximum of 80 characters.
image_url - [OPTIONAL] The URL of the image to display.
buttons - [OPTIONAL] An array of up to 3 buttons which allow a user to
take specific actions.
default_action - [OPTIONAL] The action taken when the element is
tapped. This acts in the same way as a button, but cannot have a title.
Note: These elements have be added to the gallery template and can't be
used on their own.
BUTTONS
Most of the message templates allow you to add up to 3 buttons for each
element. These are defined as objects in an array named "buttons" in each
element. These allow a user to take actions such as displaying a webview,
making a request to your server, or show a specific Chatfuel block to your
user.
WEBVIEW BUTTON
Use this button to display a webview. Set the value of the "url" key to your
webview URL. Ensure that your URL has been whitelisted in your Facebook
Messenger page settings as well as in your Chatfuel bot settings, or it will
open in the browser rather than a webview. If your webview uses Messenger
extensions, then set the value of the "messenger_extensions" key to true.
SHOW BLOCK BUTTON

Use this button to take your user to one or more Chatfuel blocks. Set the
value of the "block_names" key to an array. This contains the names of the
Chatfuel blocks that you want to send your user to.
JSON PLUGIN BUTTON

Use this button to make a GET request to your server. Set the value of the
"url" key to the URL of the server you are making the request to. As it is a
GET request, it only supports query parameters, so add them to the end of
your URL as necessary.
QUICK REPLIES
Quick replies allow you to add up to 13 buttons underneath a message, in
order to receive an easy response from your users. You can use them to take
the user to other Chatfuel blocks, to set user attributes, or to make a request
to your server. Each quick reply has a "title" key and value, and then some
additional data, depending on the type of response required.
QUICK REPLY: CHATFUEL BLOCK
Use this quick reply if you want to take the user to another Chatfuel Block.
Use the block names from your Chatfuel bot.
QUICK REPLY: SERVER REQUEST

Use this quick reply if you want to make a GET request to your own server. As
it is a GET request, it only supports query parameters, so add them to the end
of your URL as necessary.
QUICK REPLY: USER ATTRIBUTES

Use this quick reply to set a Chatfuel user attribute if the user clicks on the
button. You can either set the same user attribute with multiple buttons, or
each button can set a different user attribute.
In the example below, if the user presses the "Rice" button, then a "sideOrder"
attribute will be set to a value of "rice". If the user presses the "Noodles"
button, then a "sideOrder" attribute will be set to a value of "noodles".
QUICK REPLY: USER INPUT
Often a user will not tap one of the quick reply buttons and will instead type
in some text. You may want to save this text to a user attribute, and stop
Chatfuel's AI from giving a default answer to the unknown user message. To
do this, add the "quick_reply_options" object in your JSON data, and set the
value of the "process_text_by_ai" key to false. This will allow Chatfuel to save
the user message as an attribute called by the value of the
"text_attribute_name" key. In the example below, Chatfuel would create a user
attribute with the name "userMessage" which contains the text that the user
typed.
SET USER ATTRIBUTES

You can set any user attributes by using a JSON response with the
"set_attributes" object. Each key and value pair represents a Chatfuel
attribute and its new value. Be careful, as this will overwrite any existing
attribute with the same name. If you want to delete a user attribute, set its
value to the null data type and Chatfuel will remove it. You don't need to
send any additional messages back to the user with this response, but you can
if required.
REDIRECT TO BLOCKS
You can take your user to one or more Chatfuel blocks by returning a
"redirect_to_blocks" key in your JSON data. Set the value of this to be
an array containing one or more block names. Chatfuel will send your user to
these in the order given.
In the example below, your user will be taken to "My First Block" followed by
"My Second Block".
WANT TO LEARN MORE?
This guide has given you a simple introduction to the JSON data
format and how to use these responses with the Chatfuel JSON
API plugin. There's a lot to learn, but I'm always happy to
answer questions if you've got them. Come and find me in the
Chatfuel Facebook community, on Twitter, or email me. You'll
find all of my contact details below.
Want to learn even more about creating integrations with Chatfuel?
I'm happy to work with you as a consultant, teaching you additional tips
and tricks which will really make your business fly. The complex
interactions I can help you build into your chatbot will help both your
business and your bank balance grow. Get in touch if you’d like to work
with me.
Still struggling? Let me know what you'd most like help with.
http://bit.ly/bot-struggles
@marclittlemore
https://www.facebook.com/groups/chatfuel/
https://www.youtube.com/c/marclittlemore
marc@marclittlemore.com
Not on my chatbot mailing list yet? Sign up for more tips here:
http://bit.ly/botsignup

Chatfuel Chatbot JSON Guide - Guia

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Chatfuel Chatbot JSON Guide - Guia

Uploaded by

Copyright:

Available Formats

CHATFUEL CHATBOT

JSON isn't that hard to learn and that's what I want to

WHAT THIS GUIDE WILL TEACH YOU

I’ve helped thousands of people to add profitable integrations to their

And I want to help you!

This Chatfuel Chatbot JSON Guide was written to help marketers and

Read on and learn how to harness the power of JSON!

JSON is an acronym which stands for JavaScript Object Notation. It’s an

In the example above, the "numbersArray" has a list of integers. Here we

Chatfuel sends messages to and from Facebook's Messenger platform using

This is where Chatfuel shows its super power.

Say hello to the JSON API plugin!

Let's learn more about the Chatfuel JSON API!

IMPORTANT: Your server must respond to the request within 10

POST: FULL JSON PROFILE

Chatfuel uses a combination of Facebook Messenger standard messages,

Multiple messages can be returned in a JSON response. As you'll see in the

Let me show you how...

3. The shareable URL will be in the following format:

3. The shareable link will be in the following format:

An example gallery template

GALLERY MESSAGE ELEMENT

title - The title to display with a maximum of 80 characters.

SHOW BLOCK BUTTON

JSON PLUGIN BUTTON

QUICK REPLY: SERVER REQUEST

QUICK REPLY: USER ATTRIBUTES

SET USER ATTRIBUTES

Want to learn even more about creating integrations with Chatfuel?

You might also like