JSON Formats

BotStar requires JSON formats when using Scripting and JSON API. You can refer to the following JSON formats to render messages or execute an action.

Message & Content

To render one or more returned messages, you can use the message field as an array containing the message objects as the following forms.

Simple Text Block

Using the text with the string value you want to display in the message.

{
  "text": "Hello World"
}

Buttons List Block

You can add the buttons parameter to create a Buttons List Block. The maximum of buttons that you can create in this block is 3.

Buttons is an array containing button objects with the following structure:

title: Required - The text will be displayed
value: Optional - The value of the block after the button is selected. If the value does not exist, using a title
payload: Optional - Navigate the conversation. Learn more here
phone_number: Optional - Optional - Direct to the phone app and display the phone number to make a call.
web_url: Required - The URL will be open when users click this button

In case you want to open the webview with the special URL. Please include these properties

display_mode: Optional - Defined how the url showed. Must be internal (webview) or external new tab in browser. Default is external
webview_size: Optional - Incase display_mode is internal, this property defines the size of displaying webview. Must be one of these values: compact, tall, full. Default is full

Note: Each button should have only one action: payload, phone_number or web_url

The sample Buttons List Block follows below structure:

{
  "text": "Our positions are open. Please choose one of the options below to find out more.",
  "buttons": [
    {
      "title": "Open positions",
      "payload": {
        "goToBlock": "sede84199-f04a-4058-8b8c-fbb4364bb85"
      }
    },
    {
      "title": "About us",
      "web_url": "http://botstar.com",
      "webview_size": "tall",
      "display_mode": "internal"
    }
  ]
}

Horizontal List Block

Using the cards parameter to create a message which is a list of items horizontally, and the maximum items you can have is 10 items.

cards: the array contains the items to display. Learn about the structure of the items here.
image_size: Optional - the aspect ratio is used to render images. Must be horizontal (1.91:1) or square (1:1). The default aspect ratio is horizontal.

A sample Horizontal List Block will have the following structure:

{
  "cards": [
    {
      "title": "Product 1",
      "subtitle": "Product 1 subtitle",
      "image": "https://d1fmnevnt6737i.cloudfront.net/default-images/1.png",
      "buttons": [
        {
          "title": "Button 1"
        },
        {
          "title": "Button 2"
        }
      ]
    },
    {
      "title": "Product 2",
      "subtitle": "Product 2 subtitle",
      "image": "https://d1fmnevnt6737i.cloudfront.net/default-images/2.png",
      "buttons": [
        {
          "title": "Button 1"
        },
        {
          "title": "Button 2"
        }
      ]
    }
  ],
  "image_size": "square"
}

Receipt Block

Using items and receipt parameters to create an order confirmation message, including:

items is an array of items in the order. Learn more about the structure of the item here.
receipt is an object that contains order information, including:

recipient_name: Name of the buyer
merchant_name: Name of sales unit
order_number: Order code, currency: currency,
payment_method: Payment method,
order_url: Address Url where to buy,
timestamp: Buy time,
address: Buyer's address, including:
- street_1: Street name,
- city: "city",
- postal_code: "Postcode", state: "State code",
- country: "Country"
summary: Payment details
- subtotal: Total payment,
- shipping_cost: Shipping cost,
- total_tax: Taxes,
- total_cost: Total cost of the order
adjustments: The array containing the discount code used (if any)
- name: Code name,
- amount: Value

A sample Block Receipt will have the following structure:

{
  "items": [
    {
      "title": "Product 1",
      "subtitle": "Product 1 subtitle",
      "quantity": 2,
      "price": 50,
      "currency": "USD",
      "image": "https://d1fmnevnt6737i.cloudfront.net/default-images/1.png"
    },
    {
      "title": "Product 2",
      "subtitle": "Product 2 subtitle",
      "quantity": 1,
      "price": 25,
      "currency": "USD",
      "image": "https://d1fmnevnt6737i.cloudfront.net/default-images/2.png"
    }
  ],
  "receipt": {
    "recipient_name": "John Doe",
    "merchant_name": "BotStar",
    "order_number": "12345678902",
    "currency": "USD",
    "payment_method": "Visa 2345",
    "order_url": "https://store.botstar.com/order?order_id=123456",
    "timestamp": "1428444852",
    "address": {
      "street_1": "1 Hacker Way",
      "street_2": "",
      "city": "Menlo Park",
      "postal_code": "94025",
      "state": "CA",
      "country": "US"
    },
    "summary": {
      "subtotal": 75,
      "shipping_cost": 4.95,
      "total_tax": 6.19,
      "total_cost": 56.14
    },
    "adjustments": [
      {
        "name": "New Customer Discount",
        "amount": 20
      },
      {
        "name": "$10 Off Coupon",
        "amount": 10
      }
    ]
  }
}

Image Block

Using an image parameter with the value to display an image.

{
  "image": "https://d1fmnevnt6737i.cloudfront.net/default-images/1.png"
}

Audio Block

Using an audio parameter with the value is the audio file to send an audio message. The maximum file size is 5Mb

{
  "audio": "http://audio/link.mp3"
}

Attachment Block

Using a file parameter with the value (the file) to send an Attachment Message.

{
  "file": "http://attachment/url.pdf"
}

Video Block

Using a video parameter with the value (a video) to send out a Video Message.

{
  "video": "http://video/link.mp4"
}

Video

Execute an action

To require the system to execute an action, you can use the actions field as an array of action objects in the following form.

Change variable

You can use the following form to initialize or change the value of the previously saved variable.

type is the string "set_variable" (compulsory).
data is an object containing variables that need to be initialized or changed.

{
  "actions": [{
    "type": "set_variable",
    "data": {
      "userName": "BotStar Demo",
      "userPhone": "+123456789"
    }
  }]
}

At the next block you can use {userName} or {userPhone} with the value you assigned.

Custom message

Item

The item parameter will have the following structure:

title: Title of the item,
subtitle: Additional information,
image: Additional image,
button: The navigation button corresponding to each item and have the following structure:
- title: Required - The text will be displayed
- value: Optional - The value of the block after the button is selected. If the value does not exist, using a title
- payload: Optional - Navigate the conversation. Learn more here.

Also, in the Receipt Block, you can use these following attributes:

quantity: Product quantity
price: Price
currency: Calculation Unit

Quick Replies

You can define Quick replies for returned messages by using the quick_replies field, as in the following example. Quick replies are limited to 13 items. The quick_replies will have the following structure:

title: Required - The text will be displayed
value: Optional - The value of the block after the user clicks the quick reply button. If not, using the title value
payload: Optional - Navigate the conversation. Learn more here.

{
  "text": "Hello World",
  "quick_replies": [
    {
      "title": "Red",
      "value": "red value",
      "payload": {
        "goToBlock": "sede84199-f04a-4058-8b8c-fbb4364bb8"
      }
    },
    {
      "title": "Green",
      "value": "green value",
      "payload": {
        "goToBlock": "sede84199-f04a-4058-8b8c-fbb4364bb8"
      }
    },
    {
      "title": "Blue",
      "value": "blue value",
      "payload": {
        "goToBlock": "sede84199-f04a-4058-8b8c-fbb4364bb8"
      }
    },
  ]
}

quick replies

Block Navigation

Navigation elements such as buttons in JSON format can be set up to trigger a target block by using the payload field with the target block's ID as the value of goToBlock.

{
  "text": "Hello World",
  "buttons": [
    {
      "title": "Button 1",
      "value": "100",
      "payload": {
        "goToBlock": "sede84199-f04a-4058-8b8c-fbb4364bb85f"
      }
    },
    {
      "title": "Button 2",
      "value": "200",
      "payload": {
        "goToBlock": "s8ea82895-13a0-4b25-bb10-c18c7a3f4db7"
      }
    }
  ]
}

You can find block id in the Properties Panel in the Flow Editor.

For more information, please read our documentations at Scripting Block and JSON API.

If you have any concerns, please feel free to leave a comment below or contact us through support@botstar.com. For more details on how we have helped our customers grow their business, you can view our use cases, blogs or join our BotStar community to learn and share new things 😊

#Message & Content

#Simple Text Block

#Buttons List Block

#Horizontal List Block

#Receipt Block

#Image Block

#Audio Block

#Attachment Block

#Video Block

#Execute an action

#Change variable

#Custom message

#Item

#Quick Replies

#Block Navigation