Block JSON API

JSON API là cách kết hợp để lấy hoặc lưu dữ liệu giữa bot và hệ thống bên thứ 3 (có thể là của bạn hoặc của đối tác). API này cho phép bạn gửi request dưới dạng GET/POST/PUT/PATCH/DELETE để:

Đấu nối API với bên thứ 3 (lưu thông tin khách hàng về CRM của bạn)
Tạo nội dung động (gửi broadcast từ 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
Chuyển hướng khách hàng đến các block hội thoại theo ý muốn
Thêm mới hoặc cập nhật attribute cho khách hàng (có thể sử dụng công thức toán học)

Có 2 cách sử dụng JSON API:

1. Lấy thông tin hiển thị lên Bot

Bot tạo meme: Xem demo
Bot chèn thông tin khách hàng từ google sheet: Xem demo
Bot tìm kiếm thông tin khách hàng từ google sheet: Xem demo

AhaChat hỗ trợ 5 method để gọi API: GET, POST, PUT, PATCH, DELETE. Truyền tham số header dưới dạng key, value. Truyền tham số body dưới dạng key, value hoặc json. (header và json là dạng nâng cao, các bạn mới bắt đầu nên bỏ qua tùy chọn này)

1.1 Nhập link API

Chú ý đọc trước tài liệu để biết phương thức dùng trong API là gì (thông thường là GET hoặc POST). Có thể test trước kết quả trả về của API bằng cách bấm nút Gửi.

1.2 Nhập các tham số vào API

Thông thường các API sẽ có các tham số nhập vào giống bên dưới. Bạn chú ý phải bấm Gửi trước để kiểm tra xem API chạy đúng không. Những API chạy đúng thường trả về status 200, message successful hay message ok.

Hoặc bạn phải truyền tham số là JSON vào API để lấy được thông tin về.

1.3 Lấy kết quả trả về từ API

Kết quả trả về api có thể hiện thị tại tin nhắn của bot và tin nhắn của khách.

Ví dụ ở trên nếu muốn hiện thị url thì sẽ là {{api.meme.data.memes[0].url}} (theo cấu trúc api.tên_block.key)

2. Gửi tin nhắn từ bên ngoài

Bạn cũng có thể gửi trực tiếp tin nhắn từ bên ngoài vào bot thông qua các mẫu API trả về bên dưới. Có nghĩa rằng bạn chỉ cần nhập đúng link API và các tham số truyền vào thì sẽ nhận được tin nhắn tương ứng.

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

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

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

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

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

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

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

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

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

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

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

Gửi danh sách

Sử dụng mẫu này để gửi danh sách các mặt hàng theo chiều dọc. 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. Nó có thể được hiển thị theo hai cách khác nhau. "top_element_style": "large" hiển thị mục đầu tiên với hình ảnh bìa với văn bản được phủ lên. "top_element_style": "compact" hiển thị từng mục một cách giống hệt nhau và rất hữu ích để trình bày danh sách các mục mà không có mục nào được hiển thị nổi bật. API Ví dụ: https://www.mocky.io/v2/5c18d50e2f00006400af11d0

{
 "messages": [
    {
      "attachment":{
        "type":"template",
        "payload":{
          "template_type":"list",
          "top_element_style":"large",
          "elements":[
            {
              "title":"Chatfuel Rockets Jersey",
              "image_url":"http://ahachat.com/assets/shirt.jpg",
              "subtitle":"Size: M",
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://ahachat.com/store",
                  "title":"View Item"
                }
              ]
            },
            {
              "title":"Chatfuel Rockets Jersey",
              "image_url":"http://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"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Gửi biên lai

Sử dụng mẫu này để gửi xác nhận đơn hàng. Nó có thể bao gồm một bản tóm tắt đơn hàng, chi tiết thanh toán và thông tin vận chuyển. API Ví dụ: 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"
            }
          ]
        }
      }
    }
  ]
}

Gửi 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 block hội thoại, 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://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"
            }
          ]
        }
      }
    }
  ]
}

Messenger cũng hỗ trợ các nút chuyên dụng:

Nút Gọi sẽ quay số điện thoại khi bấm vào.
Nút Chia sẻ cho phép mọi người chia sẻ tin nhắn bot với bạn bè của họ. (Chỉ dành cho thẻ ảnh) API Ví dụ: https://www.mocky.io/v2/5c18d5952f00003400af11d5
{ "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" } ] } ] } } } ] }

Bạn cũng có thể lưu attribute và thẻ từ tùy chọn của người dùng. Ví dụ nếu người dùng bấm vào Show Block thì sẽ lưu 1 vào attribute number, còn nếu người dùng bấm vào Visit Website thì sẽ lưu 2 vào attribute number API Ví dụ: https://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"]
            }
          ]
        }
      }
    }
  ]
}

Gửi 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ụ: 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"
        }
      ]
    }
  ]
}

Bạn cũng có thể lưu attribute và thẻ từ tùy chọn của người dùng. Ví dụ nếu người dùng bấm vào Number 1 thì sẽ lưu 1 vào attribute number, còn nếu người dùng bấm vào Number 2 thì sẽ lưu 2 vào attribute number API Ví dụ: https://www.mocky.io/v2/5c18dbee2f00004e00af1216

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

Cài đặt thuộc tính cho khách

Sử dụng JSON này để đặt thuộc tính người dùng mà không cần người dùng bấm vào bất kỳ nút nào. (Chú ý nếu kiểu số thì sẽ không có dấu "", ví dụ: "number": 1) API Ví dụ: https://www.mocky.io/v2/5c19ce9c320000550064ad4e

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

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

{
  "set_attributes":
    {
      "text 1": "some value",
      "text 2": "another value",
      "numbers": [1, 2, 3],
      "number 2": 2
    },
    "messages":[
      {"text": "Add attributes successfully!"}
    ]
}

Cài đặt thẻ cho khách

Sử dụng JSON này để đặt thuộc tính người dùng mà không cần người dùng bấm vào bất kỳ nút nào. API Ví dụ: https://www.mocky.io/v2/5c19cc9b320000570064ad3c

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

Hoặc cài đặt thẻ người dùng kèm theo tin nhắn (văn bản, hình ảnh...) API Ví dụ: https://www.mocky.io/v2/5c19cd993200006d0064ad46

{
  "set_tags":["tag1", "tag2"],
  "messages":[
    {"text": "Add tag successfully!"}
  ]
}

Chuyển hướng đến block khác

Bạn có thể chuyển hướng người dùng đến một block hội thoại khác - không cần hành động của người dùng. Ví dụ nếu người dùng đã cung cấp số điện thoại thì di chuyển đến block 1, còn nếu chưa thì di chuyển đến block 2. API Ví dụ: https://www.mocky.io/v2/5ebd2710310000e2c05b1103

{
  "redirect_to_block": "Block 1"
}

3. Lấy thông tin khách hàng

Cách 1: Lấy thông tin khách hàng bằng user_id

Link API (phương thức GET): https://ahachat.com/api/users

ahachat_token = (token của bot)
user_id = (messenger_user_id của khách hàng)

Cách 2: Lấy thông tin khách hàng bằng user_phone

Link API (phương thức GET): https://ahachat.com/api/users

ahachat_token = (token của bot)
user_phone = (số điện thoại của khách hàng) áp dụng cho sđt có mã vùng hoặc ko. Ví dụ +84918123123 hay 0918123123)

Có thể test bằng cách bấm nút Gửi.

Bạn sẽ lấy được các tham số sau

Để lấy được các thông tin của khách hàng ra tin nhắn hoặc sử dụng để lưu vào thuộc tính của bot ta thực hiện theo cấu trúc

{{api.tên_block.key}}

Ví dụ ở trên nếu muốn hiển thị số điện thoại thì sẽ là:

{{api.user.data.phone}}

Trong kết quả trả về bao gồm "is_followup_enabled": true nghĩa là khách hàng này tương tác trong 24h.

Bạn có bất kỳ câu hỏi nào liên quan đến Block JSON API? Bạn muốn khởi chạy chiến dịch tiếp cận khách hàng của mình bằng Chatbot với một số lời khuyên chuyên môn từ Đối tác tiếp thị của Facebook? Đừng ngần ngại liên hệ với chúng tôi để có câu trả lời nhanh nhất và hiệu quả nhất! Tận hưởng công cụ chatbot miễn phí của chúng tôi mà không cần phải trả bất kỳ chi phí nào!

1. Lấy thông tin hiển thị lên Bot#

1.1 Nhập link API#

1.2 Nhập các tham số vào API#

1.3 Lấy kết quả trả về từ API#

2. Gửi tin nhắn từ bên ngoài#

Gửi văn bản#

Gửi hình ảnh#

Gửi video#

Gửi âm thanh#

Gửi tập tin#

Gửi thẻ ảnh ngang#

Gửi danh sách#

Gửi biên lai#

Gửi nút bấm#

Gửi trả lời nhanh#

Cài đặt thuộc tính cho khách#

Cài đặt thẻ cho khách#

Chuyển hướng đến block khác#

3. Lấy thông tin khách hàng#

Cách 1: Lấy thông tin khách hàng bằng user_id#

Cách 2: Lấy thông tin khách hàng bằng user_phone#