JSON API

Chatbot API

JSON API cho phép bạn gửi request dưới dạng POST (thời gian chờ là 5s) để:

• Tạo nội dung động (gửi các tin nhắn từ CMS hay CRM của bạn đến khách hàng)

• Lưu thông tin khách hàng vào google sheet hoặc lấy thông tin từ google sheet ra cho khách hàng

• Chuyển hướng khách hàng đến các kịch bản khác

• Lưu và cài đặt thuộc tính (attribute) cho khách hàng, ví dụ như điểm thưởng, hành trình,...

Cú pháp

• URL: https://api.botbanhang.vn/v1.3/public/json?access_token={{accessToken}}&psid={{clientID}}

• HEADERS:

  Content-Type: application/json

• Giải thích các tham số trong URL:

  {{accessToken}}: là mã xác thực trang trong phần "Thiết lập chung". Nếu chưa có mã xác thực thì chỉ cần nhấn Tạo mã mới.

{{clientID}}: là ID của người dùng trên trang. Dùng $ để gọi clientID người dùng trên trang.

Các mẫu tham khảo

1. Gửi văn bản

Sử dụng mẫu này để gửi tin nhắn văn bản. API ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#e70076be-6514-4448-a5e3-f2d0ae48bba7​

{
 "messages": [
   {"text": "Chào mừng bạn đến với Bot Bán Hàng!"},
   {"text": "Chúng tôi có thể giúp gì cho bạn?"}
 ]
}

Kết quả test từ Postman

2. Gửi hình ảnh

Sử dụng mẫu này để gửi tập tin hình ảnh. Messenger hỗ trợ hình ảnh JPG, PNG và GIF. Nếu bạn gặp sự cố với hình ảnh GIF, vui lòng thử giảm kích thước tệp. API ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#3883d13a-a80b-439c-baf2-4a127d186ebe​

{
  "messages": [
    {
      "attachment": {
        "type": "image",
        "payload": {
          "url": "https://botbanhang.vn/images/logo.png"
        }
      }
    }
  ]
}

3. Gửi video

Sử dụng mẫu này để gửi các tập tin video. Messenger hỗ trợ video MP4, có dung lượng lên tới 25MB. API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#e09c4c5f-bede-4e53-8dad-bb5e45f5a464​

{
  "messages": [
    {
      "attachment": {
        "type": "video",
        "payload": {
          "url": "https://www.sample-videos.com/video123/mp4/720/big_buck_bunny_720p_5mb.mp4"
        }
      }
    }
  ]
}

Bạn cũng có thể trực tiếp sử dụng Bài đăng trên Facebook với phương tiện truyền thông thay vì tải lên thủ công API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#705f2438-f5c2-4c2e-85aa-2827620e621b​

{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "media",
          "elements": [
            {
              "media_type": "video",
              "url": "https://www.facebook.com/unofficial.abio/videos/2593801767328577/",
              "buttons": [
                {
                  "title": "Truy cập Bot Bán Hàng!",
                  "type": "web_url",
                  "url": "https://botbanhang.vn/"
                }
              ]
            }
          ]
        }
      },
      "quick_replies": [
        {
          "title": "Tuyệt!",
          "set_attributes": {
            "feedback": "Cool!"
          }
        },
        {
          "title": "Không hay!",
          "set_attributes": {
            "feedback": "Not good!"
          }
        }
      ]
    }
  ]
}

4. Gửi âm thanh

Sử dụng mẫu này để gửi tập tin âm thanh. Messenger hỗ trợ âm thanh MP3, OGG, WAV, có dung lượng lên tới 25MB. API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#5113c4ea-0638-4fcc-a7f5-e93382c0fd20​

{
  "messages": [
    {
      "attachment": {
        "type": "audio",
        "payload": {
          "url": "https://www.sample-videos.com/audio/mp3/wave.mp3"
        }
      }
    }
  ]
}

5. Gửi tập tin

Sử dụng mẫu này để gửi bất kỳ tệp nào khác, không lớn hơn 25 MB. API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#3491ed70-2cac-46a7-a0f4-d47f41caa855​

{
  "messages": [
    {
      "attachment": {
        "type": "file",
        "payload": {
          "url": "https://www.sample-videos.com/pdf/Sample-pdf-5mb.pdf"
        }
      }
    }
  ]
}

6. Gửi thẻ ảnh ngang

Sử dụng mẫu này để gửi một bộ sưu tập cuộn ngang. Mỗi mục bao gồm một tệp đính kèm hình ảnh, mô tả ngắn và các nút để yêu cầu người dùng bấm vào. API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#51ff7faa-3da6-4c7b-b2cd-cc3d117d74a7​

{
 "messages": [
    {
      "attachment":{
        "type":"template",
        "payload":{
          "template_type":"generic",
          "image_aspect_ratio": "square",
          "elements":[
            {
              "title":"ÁO PHÔNG NAM DÀI TAY",
              "image_url":"https://canifa.s3.amazonaws.com/media/catalog/product/8/t/8tl18w007-sb505-34.jpg",
              "subtitle":"Size: M",
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://botbanhang.vn",
                  "title":"Xem chi tiết"
                }
              ]
            },
            {
              "title":"ÁO PHÔNG NAM DÀI TAY",
              "image_url":"https://canifa.s3.amazonaws.com/media/catalog/product/8/t/8tl18w007-sb505-33-.jpg",
              "subtitle":"Size: L",
              "default_action": {
                "type": "web_url",
                "url": "https://botbanhang.vn",
                "messenger_extensions": true
              },
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://botbanhang.vn",
                  "title":"Xem chi tiết"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

7. Nút bấm

Sử dụng JSON này để thêm các nút vào câu trả lời của bạn. Bạn có thể đặt các nút để liên kết đến một kịch bản khác, mở trang web hoặc gửi yêu cầu api khác. Mỗi tin nhắn được giới hạn 3 nút bấm. API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#98b2e60b-c6df-4229-9eea-314dc3c52738​

{
  "messages": [
    {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "button",
          "text": "Hello!",
          "buttons": [
            {
              "type": "show_block",
              "block_names": ["ID Kịch bản"],
              "title": "Hiện kịch bản"
            },
            {
              "type": "web_url",
              "url": "https://botbanhang.vn",
              "title": "Truy cập Website"
            },
            {
              "url": "https://fb.com/groups/botbanhang",
              "type":"web_url",
              "title":"Tham gia cộng đồng"
            }
          ]
        }
      }
    }
  ]
}

Bạn cũng có thể sử dụng nút Gọi, nút này quay số điện thoại khi nghe. API ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#b0ea8150-d427-494d-9936-248eff489609​

{
  "messages":[
    {
      "attachment":{
        "type":"template",
        "payload":{
          "template_type":"generic",
          "elements":[
            {
              "title":"Thông tin liên lạc",
              "image_url":"https://ayokaflowers.com/wp-content/uploads/2017/08/contact-us.png",
              "subtitle":"Hãy liên hệ chúng tôi để được trợ giúp!",
              "buttons":[
                {
                  "type":"phone_number",
                  "phone_number":"[phone]",
                  "title":"Gọi"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

8. Trả lời nhanh

Sử dụng JSON này để thêm trả lời nhanh cho câu trả lời của bạn. Mỗi tin nhắn được giới hạn 11 mục Trả lời nhanh. API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#9375c7aa-6c7a-47e7-95b4-516e71a4e8e3​

{
  "messages": [
    {
      "text":  "Bạn có muốn tiếp tục sử dụng sản phẩm Bot Bán Hàng?",
      "quick_replies": [
      	{
          "title":"Có!",
          "block_names": ["ID kịch bản 1"]
        },
        {
          "title":"Không!",
          "block_names": ["ID kịch bản 2", "ID kịch bản 3"]
        },
        {
          "title":"Đang xem xét...",
          "url": "http://www.mocky.io/v2/5d761dc33200002d0029789b",
          "type":"json_plugin_url"
        }
      ]
    }
  ]
}

Bạn cũng có thể lưu attribute (thuộc tính) từ tùy chọn của người dùng. Ví dụ nếu người dùng bấm vào Sữa thì sẽ lưu milk vào attribute drink, còn nếu người dùng bấm vào Cà phê thì sẽ lưu coffee vào attribute drink API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#d5befebf-254d-476f-b6b6-388c04f604c3​

{
  "messages": [
    {
      "text": "Bạn muốn gọi sữa hay cà phê?",
      "quick_replies": [
        {
          "title": "Sữa",
          "set_attributes": {
            "drink": "milk"
          }
        },
        {
          "title": "Cà phê",
          "set_attributes": {
            "drink": "coffee"
          }
        }
      ]
    }
  ]
}

9. Cài đặt thuộc tính (attributes) cho người dùng

Sử dụng JSON này để đặt thuộc tính người dùng mà cần người dùng bấm vào bất kỳ nút nào. API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#1ac9d3e5-3f68-4c8c-80a4-a6987a0bedd6​

{
  "set_attributes": 
    {
      "thanhpho": "Hà Nội",
      "email": "[e-mail]",
      "dienthoai": "0763874340"
    },
  "block_names": ["5c6796a21e622d0d48fd5645"],
  "type": "show_block",
  "title": "Go!"
}

Hoặc cài đặt thuộc tính người dùng kèm theo tin nhắn (văn bản, hình ảnh...) API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#2363b425-61b2-4e00-bd6d-57cbdca4a093​

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

Hoặc cài đặt thuộc tính người dùng mà không kèm theo tin nhắn (văn bản, hình ảnh...) API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#270bb171-ae9e-46d9-9436-8d219fe0cad1​

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

10. Chuyển hướng đến các kịch bản khác

Bạn có thể chuyển hướng người dùng đến một kịch bản hoặc đến một chuỗi các kịch bản - không cần hành động của người dùng. API Ví dụ: https://documenter.getpostman.com/view/8752962/SVmqz1BB?version=latest#68b27083-e239-4a11-8224-937f78805417​

{
  "redirect_to_blocks": ["5c6796a21e622d0d48fd5645", "5c9b9a39f60b4f001164aca2"]
}