The JSON API plugin allows you to integrate your backend into your chatbots in Chatfuel. It enables your bot to send HTTP GET and POST requests and interpret responses with the maximum timeout always being 10 seconds. With JSON API you can:

  • Generate dynamic content;

  • Get and set user attributes;

  • Redirect users to another block in the bot;

  • Create postbacks.

While it is available for both Messenger and Instagram, the types of messages you can send depends on each platform. Go to Flow BuilderContent Blocks to check what types of content are available for Facebook or Instagram Flows.


Do keep in mind that for other functionalities or compiling functions to work altogether is out of Chatfuel's scope of support and we suggest to get help from an expert. Check these guides to find out more about Facebook Messaging API or Instagram Messaging API.

Types of data

There are four options to enter data that will be sent with your request:

  1. URL field supports user attributes, they will be URL-encoded with your request.

  2. Full JSON profile sends all the user attributes of the user to your backend. (POST requests only)

  3. JSON Body is a customizable field and will be validated as JSON. (POST requests only)

  4. URL Encoded encodes data before sending your request. (POST requests only)

In your responses, you can:

  • combine several messages in one answer by sending several dictionaries in the messages array;

  • use any content type header;

  • send an empty response to not show the user any dynamic content.

JSON API Endpoints - IPs

Below are the current IPs we are using for our JSON Endpoints. These IPs might change at any time without prior notice.

34.74.163.161
34.73.213.77
104.196.128.98

📌 Certain elements will no longer work as part of the JSON API if your page or its admins are based in the European Economic Area (EEA), and they won’t work for EEA users either:

  • Video and audio;

  • One-Time Notifications;

  • Typing animations.

Also, galleries and buttons will only be available on mobile. Get more info on Facebook's updated EEA policies.

Pre-set JSON responses

With no attribute mapping enabled you need to use custom commands. This option works well if you want to use JSON with your own service (server). It can also be used with a special API for Chatfuel (e.g. janis.ai). Below are examples of what your requests might look like.

Sending text

✔️Messenger ✔️Instagram

Use this response to send text messages.

{
 "messages": [
   {"text": "Welcome to the Chatfuel Rockets!"},
   {"text": "What are you up to?"}
 ]
}

Sending images

✔️Messenger ✔️Instagram

Use this response to send image files. Supported formats are JPG, PNG and GIF for Facebook and JPG, PNG, ICO, BMP for Instagram. If you are having issues with GIF rendering, please try to reduce the file size.

{
  "messages": [
    {
      "attachment": {
        "type": "image",
        "payload": {
          "url": "https://assets.website-files.com/60afa6a88bd1bb7755dea817/60afa6a88bd1bb78e4deaa28_welcome-message-v8.png"
        }
      }
    }
  ]
}

You can also directly use Facebook posts with photos instead of uploading the photos manually. This example might not work for Instagram posts:

{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_type": "image",
              "url": "https://www.facebook.com/chatfuelrockets/photos/1087668107975064",
              "buttons": [
                {
                  "title": "Go to Chatfuel!",
                  "type": "web_url",
                  "url": "https://chatfuel.com/"
                }
              ]
            }
          ]
        }
      },
      "quick_replies": [
        {
          "title": "That's cool!",
          "set_attributes": {
            "feedback": "Cool!"
          }
        }
      ]
    }
  ]
}

Sending video

✔️Messenger ❌Instagram

Use this response to send video files. Messenger supports MP4 videos, which are up to 25MB in size.

{
  "messages": [
    {
      "attachment": {
        "type": "video",
        "payload": {
          "url": "https://rockets.chatfuel.com/assets/video.mp4"
        }
      }
    }
  ]
}

You can also directly use Facebook posts with videos instead of uploading the videos manually.

{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_type": "video",
              "url": "https://www.facebook.com/chatfuelrockets/videos/252894858962779/",
              "buttons": [
                {
                  "title": "Go to Chatfuel!",
                  "type": "web_url",
                  "url": "https://chatfuel.com/"
                }
              ]
            }
          ]
        }
      },
      "quick_replies": [
        {
          "title": "That's cool!",
          "set_attributes": {
            "feedback": "Cool!"
          }
        }
      ]
    }
  ]
}

Sending audio

✔️Messenger ❌Instagram

Use this response to send audio files. Messenger supports MP3, OGG, WAV audios, which are up to 25MB in size. Instagram doesn't support sending audio messages.

{
  "messages": [
    {
      "attachment": {
        "type": "audio",
        "payload": {
          "url": "https://rockets.chatfuel.com/assets/hello.mp3"
        }
      }
    }
  ]
}

Sending files

✔️Messenger ❌Instagram

Use this response to send any other files, which are no larger than 25 MB. Instagram doesn't support sending files.

{
  "messages": [
    {
      "attachment": {
        "type": "file",
        "payload": {
          "url": "https://rockets.chatfuel.com/assets/ticket.pdf"
        }
      }
    }
  ]
}

Sending galleries

✔️Messenger ✔️Instagram

Use this response to send a horizontal scrollable gallery. Each item is composed of an image attachment, short description and buttons to request input from the user. The image_aspect_ratio can be either square or horizontal. Horizontal is the default.

{
 "messages": [
    {
      "attachment":{
        "type":"template",
        "payload":{
          "template_type":"generic",
          "image_aspect_ratio": "square",
          "elements":[
            {
              "title":"Chatfuel Rockets Jersey",
              "image_url":"https://rockets.chatfuel.com/assets/shirt.jpg",
              "subtitle":"Size: M",
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://rockets.chatfuel.com/store",
                  "title":"View Item"
                }
              ]
            },
            {
              "title":"Chatfuel Rockets Jersey",
              "image_url":"https://rockets.chatfuel.com/assets/shirt.jpg",
              "subtitle":"Size: L",
              "default_action": {
                "type": "web_url",
                "url": "https://rockets.chatfuel.com/store"
              },
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://rockets.chatfuel.com/store",
                  "title":"View Item"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Sending receipts

✔️Messenger ✔️Instagram

Use this response to send an order confirmation. It may include an order summary, payment details, and shipping information.

{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "receipt",
          "recipient_name": "Mark Zuckerberg",
          "order_number": "12345678901",
          "currency": "USD",
          "payment_method": "Visa 2345",
          "order_url": "https://rockets.chatfuel.com/store?order_id=12345678901",
          "timestamp": "1428444666",
          "address": {
            "street_1": "1 Hacker Way",
            "street_2": "",
            "city": "Menlo Park",
            "postal_code": "94025",
            "state": "CA",
            "country": "US"
          },
          "summary": {
            "subtotal": 105,
            "shipping_cost": 4.95,
            "total_tax": 9,
            "total_cost": 118.95
          },
          "adjustments": [
            {
              "name": "CF Rockets Superstar",
              "amount": -25
            }
          ],
          "elements": [
            {
              "title": "Chatfuel Rockets Jersey",
              "subtitle": "Size: M",
              "quantity": 1,
              "price": 65,
              "currency": "USD",
              "image_url":   "http://rockets.chatfuel.com/assets/shirt.jpg"
            },
            {
              "title": "Chatfuel Rockets Jersey",
              "subtitle": "Size: L",
              "quantity": 1,
              "price": 65,
              "currency": "USD",
              "image_url":   "http://rockets.chatfuel.com/assets/shirt.jpg"
            }
          ]
        }
      }
    }
  ]
}

Buttons

✔️Messenger ❌Instagram

Use this JSON to add buttons to your responses. You can set buttons to link to a block in the dashboard, open a website, or send another request to your backend. Buttons are limited to 3 items per message.

{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "button",
          "text": "Hello!",
          "buttons": [
            {
              "type": "show_block",
              "block_names": ["name of block"],
              "title": "Show Block"
            },
            {
              "type": "web_url",
              "url": "https://rockets.chatfuel.com",
"webview_height_ratio": "compact",
              "title": "Visit Website"
            },
            {
              "url": "https://rockets.chatfuel.com/api/welcome",
              "type":"json_plugin_url",
              "title":"Postback"
            }
          ]
        }
      }
    }
  ]
}

The webview_height_ratio value can be compact (40%), tall (70%) or full (100%). This only works for web_url type of button, and default size is full.

You can also use the Call button, this button dials a phone number when tapped.

{
  "messages":[
    {
      "attachment":{
        "type":"template",
        "payload":{
          "template_type":"generic",
          "elements":[
            {
              "title":"Get in touch",
              "image_url":"https://rockets.chatfuel.com/assets/contact.jpg",
              "subtitle":"Feel free to hit us up!",
              "buttons":[
                {
                  "type":"phone_number",
                  "phone_number":"+19268881413",
                  "title":"Call"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

You can also have a secondary action for your button. You could, for example, open a URL and redirect the user to another block, or assign an attribute. Here's the example on how it would work:

{
"messages": [
{
"attachment": {
"type": "template",
"payload": {
"template_type": "button",
"text": "Hello!",
"buttons": [
{
"type": "web_url",
"url": "https://facebook.com/chatfuel",
"webview_height_ratio": "compact",
"block_names": ["name of block"],
"title": "Visit and Redirect"
},
{
"type": "web_url",
"url": "https://facebook.com/chatfuel",
"webview_height_ratio": "compact",
"set_attributes": {"some attribute": "some value"},
"title": "Visit and Set"
}
]
}
}
}
]
}

Quick replies

✔️Messenger ✔️Instagram

Use this JSON to add Quick Replies to your responses. Quick replies are limited to 11 items per message.

{
  "messages": [
    {
      "text":  "Did you enjoy the last game of the CF Rockets?",
      "quick_replies": [
        {
          "title":"Loved it!",
          "block_names": ["Block 1", "Block 2"]
        },
        {
          "title":"Not really...",
          "url": "https://rockets.chatfuel.com/api/sad-match",
          "type":"json_plugin_url"
        }
      ]
    }
  ]
}

You might want to use additional options using quick_reply_options, for example:

  • process_text_by_ai (value true or false) specifies how to handle user input sent after the Quick Reply. If false, user will be sent to the next card, instead of AI recognition.

  • text_attribute_name if specified, user input sent after the Quick Reply will be saved into an user attribute.

{
  "messages": [
    {
      "text": "text",
      "quick_replies": [
        {
          "title": "Number 1",
          "set_attributes": {
            "number": "1"
          }
        },
        {
          "title": "Number 2",
          "set_attributes": {
            "number": "2"
          }
        }
      ],
      "quick_reply_options": {
        "process_text_by_ai": false,
        "text_attribute_name": "user_message"
      }
    }
  ]
}

Setting user attributes

✔️Messenger ✔️Instagram

Use this JSON to set user attributes for a user depending on the button they tap
(show_block  or json_plugin_url  only).

{
  "set_attributes":
    {
      "some attribute": "some value",
      "another attribute": "another value"
    },
  "block_names": ["Block 1"],
  "type": "show_block",
  "title": "Go!"
}

You can also set user attributes without having the user to tap any button.

{
  "set_attributes":
    {
      "some attribute": "some value",
      "another attribute": "another value"
    },
  "messages":[
    . . .
  ]
}

Redirect to blocks

✔️Messenger ❌Instagram

You can redirect a user to a block or to a sequence of blocks — no user action is needed.

{
  "redirect_to_blocks": ["Welcome Message", "Default Answer"]
}

JSON attributes mapping responses

✔️Messenger ✔️Instagram

Another way to use JSON is with attributes mapping. It can be used with any third-party API in JSON format. In this mode you can set attributes to your bot users by using API responses. These attributes will appear in Live Chat and People tab as any other attribute. You need to use a special JSON Path format to get a specific value from API. To turn it on, tick Setup attributes mapping checkbox. Keep in mind, that you are limited to only using attributes with attribute mapping enabled.

How to use JSON Path

Let’s look at the example. Your API returns the following JSON response:

{
"result": "success",
"data": {
"email": "info@example.com",
"avatar": "https://cdn.example.com/img/1213212.png"
"person.address": "3734 Deercove Drive, Texas",
"person.zip": "75212"
}
}

To set ‘success’ value to {{ api result }} from API response you need to provide a key. In this case ‘result’ is your key. If you want to get access to nested JSON you need to separate your keys with a period. For example:

{{ api data email }} → data.email
{{ api data avatar }} → data.avatar

Besides period . you can also use single quotes [' ']. This might be useful when a period is being used in the JSON key.

{{ api data person.address }} → data['person.address']

You can learn more about JSON Path and how to use it here.

Did this answer your question?