JSON API

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

Sending text

Use this response to send text messages. Example: http://www.mocky.io/v2/5c1772412f00004d00b086c4

{
"messages": [
{"text": "Welcome to AhaChat!"},
{"text": "Sorry, can I help you?"}
]
}

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. Example: http://www.mocky.io/v2/5c18d25d2f00000f00af11c3

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

Sending video

Use this response to send video files. Messenger supports MP4 videos, which are up to 25MB in size. Example: http://www.mocky.io/v2/5c18d29a2f00006400af11c5

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

Sending audio

Use this response to send audio files. Messenger supports MP3, OGG, WAV audios, which are up to 25MB in size. Example: http://www.mocky.io/v2/5c18d2ac2f00007500af11c6

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

Sending files

Use this response to send any other files, which are no larger than 25 MB. Example: http://www.mocky.io/v2/5c18d2c52f00006100af11c7

{
"messages": [
{
"attachment": {
"type": "file",
"payload": {
"url": "https://ahachat.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. Note: messenger_extensions should only be added if you are using Messenger Extensions. Example: http://www.mocky.io/v2/5c18d35e2f00006400af11c8

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

Sending receipts

Use this response to send an order confirmation. It may include an order summary, payment details, and shipping information. Example: http://www.mocky.io/v2/5c18d51f2f00005700af11d1

{
"messages": [
{
"attachment": {
"type": "template",
"payload": {
"template_type": "receipt",
"recipient_name": "Mark Zuckerberg",
"order_number": "12345678901",
"currency": "USD",
"payment_method": "Visa 2345",
"order_url": "https://ahachat.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://ahachat.com/assets/shirt.jpg"
},
{
"title": "Chatfuel Rockets Jersey",
"subtitle": "Size: L",
"quantity": 1,
"price": 65,
"currency": "USD",
"image_url": "http://ahachat.com/assets/shirt.jpg"
}
]
}
}
}
]
}

Buttons

Use this JSON function 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. Example: http://www.mocky.io/v2/5c18d9f12f00006200af11fb

{
"messages": [
{
"attachment": {
"type": "template",
"payload": {
"template_type": "button",
"text": "Hello!",
"buttons": [
{
"type": "show_block",
"block_name": "name of block",
"title": "Show Block"
},
{
"type": "web_url",
"url": "https://ahachat.com",
"title": "Visit Website"
},
{
"type": "web_url",
"url": "https://fb.com/groups/ahachat",
"title": "Visit Group"
}
]
}
}
}
]
}

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

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

You can also save attributes and tags from the user's options. For example, if the user clicks on Show Block, he will save 1 to the attribute number, and if the user clicks on Visit Website, he will save 2 to the attribute number. Example: http://www.mocky.io/v2/5c19b5453200000e0064ad03

{
"messages": [
{
"attachment": {
"type": "template",
"payload": {
"template_type": "button",
"text": "Hello!",
"buttons": [
{
"type": "show_block",
"block_name": "name of block",
"title": "Show Block",
"set_attributes": {
"number": 1
},
"set_tags": ["tag1"]
},
{
"type": "web_url",
"url": "https://ahachat.com",
"title": "Visit Website",
"set_attributes": {
"number": 2
},
"set_tags": ["tag2"]
}
]
}
}
}
]
}

Quick replies

Use this JSON function to add quick replies to your responses. Quick replies are limited to 11 items per message. Example: http://www.mocky.io/v2/5c18daf52f00000f00af1207

{
"messages": [
{
"text": "AhaChat is useful for your business?",
"quick_replies": [
{
"title":"Yes, sure!",
"block_name": "Block 1"
},
{
"title":"I don't know",
"block_name": "Block 2"
}
]
}
]
}

You can also save attributes and tags from the user's options. For example, if the user clicks on Show Block, he will save 1 to the attribute number, and if the user clicks on Visit Website, he will save 2 to the attribute number. Example: http://www.mocky.io/v2/5c18dbee2f00004e00af1216

{
"messages": [
{
"text": "What's your number?",
"quick_replies": [
{
"title": "Number 1",
"set_attributes": {
"number": 1
},
"set_tags": ["tag1"]
},
{
"title": "Number 2",
"set_attributes": {
"number": 2
},
"set_tags": ["tag2"]
}
]
}
]
}

Setting user attributes

Use this JSON function to set user attributes without the user having to click any buttons. (Note that if the number type does not have a "" symbols, for example: "number": 1) Example: http://www.mocky.io/v2/5c19ce9c320000550064ad4e

{
"set_attributes":
{
"text 1": "some value",
"text 2": "another value",
"number 1": 1,
"number 2": 2
}
}

Or set user attributes with messages (text, images ...etc) Example: http://www.mocky.io/v2/5c19cf8b320000540064ad50

{
"set_attributes":
{
"text 1": "some value",
"text 2": "another value",
"number 1": 1,
"number 2": 2
},
"messages":[
. . .
]
}

Setting user tags

Use this JSON function to set user tags without the user having to click any buttons. Example: http://www.mocky.io/v2/5c19cc9b320000570064ad3c

{
"set_tags": ["tag1", "tag2"]
}

Or set user tags with messages (text, images ...etc) Example: http://www.mocky.io/v2/5c19cd993200006d0064ad46

{
"set_tags": ["tag1", "tag2"],
"messages":[
. . .
]
}

Redirect to blocks

You can redirect a user to a block or to a sequence of blocks — no user action is needed. Example: http://www.mocky.io/v2/5c19b5453200000e0064ad03

{
"redirect_to_block": "Block 1"
}

Send 3rd party messages to the bot using Broadcast API

Allow sending block to any subscriber. You can add attributes to them when using this API.

All Broadcast API must be provided via POST, with the following code:

https://ahachat.com/api/bots/<BOT_ID>/users/<USER_ID>/send?ahachat_token=<TOKEN>&ahachat_message_tag=<AHACHAT_MESSAGE_TAG>&ahachat_block_name=<BLOCK_NAME>&<USER_ATTRIBUTE_1>=<VALUE_1>&<USER_ATTRIBUTE_2>=<VALUE_2>

  • <TOKEN> — The unique secret token for each bot. You can find and reset this token in the Settings menu at any time.

  • <USER_ID> — {{messenger_user_id}} of the subscriber you want to send the broadcast to.

  • <BOT_ID> — ID of the bot you want to send messages from.

  • <AHACHAT_MESSAGE_TAG> — The facebook message tag gives you the ability to send messages outside 24h, so the default is NON_PROMOTIONAL_SUBSCRIPTION. See the full list of message tags here.

  • <BLOCK_NAME> — The block name you want to send to the subscriber.

  • <USER_ATTRIBUTE>=<VALUE> — The name and value of the user attribute you want to save when sending the message.