Documentation update (November 19th - 2020)
• Added examples on how to use secondary actions for buttons. (Pro Plan required)
---
Documentation update (November 10th - 2020)
• Added more information on "Sending galleries", for "image_aspect_ratio" option
• Added more information on "Buttons", for "webview_height_ratio" option
---
Documentation update (April 27th - 2020)
• Added "Current IP List", to list all the JSON API Endpoint IPs currently in use
---
Documentation update (September 25th - 2019)
• Removed the 'List Plugin' example, as it was deprecated by Facebook API. Read more details here: https://bit.ly/2mGMRRj
---
Documentation update (August 14th - 2019)
• Removed the "type":"element_share", as it was deprecated by Facebook API. Read more details here: https://bit.ly/2Z5rwCW

JSON API v2.1 (July, 17th - 2019)
• Use POST with full JSON profile
• Choose parameters in URLEncoded, instead of full body preview
• 'Test the Request' will now use your own attribute values

---
JSON API v2.0 (June, 18th - 2019)

- UI Changes
• Change URL and Body of the request
• Add custom headers to the request (mostly used for security purposes, read more details here: https://bit.ly/2IY4DqP)
- Internal Changes
• All requests now contains "User-Agent: Chatfuel” header
• Space symbols ' ' will be encoded as '%20' instead of '+' in both body and URL-encoded requests


The JSON API plugin enables your bot to send HTTP GET and POST requests and interpret responses.

It allows you to

  • Generate dynamic content
  • Get and set user attributes
  • Redirect users to another block in the bot
  • Create postbacks

You can use GET and POST requests - the max. timeout is always 10 seconds. There are four options to enter data that will be sent with your request:

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

2. Full JSON profile (POST requests only) — This will send all the user attributes of the user to your backend.

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

4. URL Encoded (POST requests only) — The data will be encoded before sending your request.

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.

Response Reference

Sending text

Use this response to send text messages.

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

Sending images

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.

{
  "messages": [
    {
      "attachment": {
        "type": "image",
        "payload": {
          "url": "https://rockets.chatfuel.com/assets/welcome.png"
        }
      }
    }
  ]
}

You can also directly use Facebook Posts with media instead of uploading it manually:

{
  "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

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 media instead of uploading it 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

Use this response to send audio files. Messenger supports MP3, OGG, WAV audios, which are up to 25MB in size.

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

Sending files

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

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

Sending galleries

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.

{
 "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"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

The image_aspect_ratio can be either square or horizontal. Horizontal is the default.

Sending receipts

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

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"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

If you are under the Pro Plan, you will be able to 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

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

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

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"]
}


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.

JSON API Endpoints - IPs

These are the current IPs we are using for our JSON Endpoints:

34.74.163.161
34.73.213.77
104.196.128.98

Note: The current IPs might change at any time without prior notice.

Did this answer your question?