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

If you select POST user attributes get send in the body of the request. GET adds parameters as a query string. The max. timeout is 10 seconds in both cases.

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.

If you are looking for an easy and fast way to setup your own endpoint for the JSON plugin, check out this short tutorial created by a Chatfuel user.

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/img/welcome.png"
        }
      }
    }
  ]
}

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/img/welcome.png"
        }
      }
    }
  ]
}

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

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/store/tickets.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 T-Shirt",
              "image_url":"https://rockets.chatfuel.com/img/shirt.png",
              "subtitle":"Soft white cotton t-shirt with CF Rockets logo",
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://rockets.chatfuel.com/store/shirt",
                  "title":"View Item"
                }
              ]
            },
            {
              "title":"Chatfuel Rockets Hoodie",
              "image_url":"https://rockets.chatfuel.com/img/hoodie.png",
              "subtitle":"Soft grey cotton hoddie with CF Rockets logo",
              "default_action": {
                "type": "web_url",
                "url": "https://rockets.chatfuel.com/store",
                "messenger_extensions": true
              },
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://rockets.chatfuel.com/store/hoodie",
                  "title":"View Item"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Sending lists

Use this response to send a set of items vertically. Each item is composed of an image attachment, short description and buttons to request input from the user. It can be rendered in two different ways. "top_element_style": "large" renders the first item with a cover image with text overlaid. "top_element_style": "compact" renders each item identically and is useful for presenting a list of items where no item is shown prominently.

{
 "messages": [
    {
      "attachment":{
        "type":"template",
        "payload":{
          "template_type":"list",
          "top_element_style":"large",
          "elements":[
            {
              "title":"Chatfuel Rockets T-Shirt",
              "image_url":"http://rockets.chatfuel.com/img/shirt.png",
              "subtitle":"Soft white cotton t-shirt with CF Rockets logo",
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://rockets.chatfuel.com/store/shirt",
                  "title":"View Item"
                }
              ]
            },
            {
              "title":"Chatfuel Rockets Hoodie",
              "image_url":"http://rockets.chatfuel.com/img/hoodie.png",
              "subtitle":"Soft gray cotton t-shirt with CF Rockets logo",
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://rockets.chatfuel.com/store/hoodie",
                  "title":"View Item"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

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",
              "title": "Visit Website"
            },
            {
              "url": "https://rockets.chatfuel.com/api/postback",
              "type":"json_plugin_url",
              "title":"Postback"
            }
          ]
        }
      }
    }
  ]
}

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)
{
  "messages":[
    {
      "attachment":{
        "type":"template",
        "payload":{
          "template_type":"generic",
          "elements":[
            {
              "title":"Get in touch",
              "image_url":"https://rockets.chatfuel.com/img/contact.png",
              "subtitle":"Feel free to hit us up!",
              "buttons":[
                {
                  "type":"phone_number",
                  "phone_number":"+19268881413",
                  "title":"Call"
                },
                {
                  "type":"element_share"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

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

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

Did this answer your question?