1. Giới thiệu

BeeIQ Data Platform cho phép người dùng nhập dữ liệu qua nhiều nguồn khác nhau, đa dạng thông tin, và quản lí thông tin tốt hơn. Tài liệu này dùng để hướng dẫn cách để thực hiện nhập dữ liệu từ bên ngoài vào BeeIQ Data Platform một cách tự động. Những nguồn dữ liệu BeeIQ Data platform hỗ trợ:

- Dữ liệu từ Call Center

- Dữ liệu từ Email, SMS, Facebook, Zalo

- Dữ liệu từ Webform khi khách để lại thông tin - Dữ liệu tài khoản khi khách hàng đăng ký trên Website - Dữ liệu đơn hàng - Dữ liệu mua hàng - Dữ liệu thẻ thành viên/ khách hàng thân thiết

2. Cách cấu hình

2.1. Khởi tạo URL dùng để nhận dữ liệu từ ngoài vào

Để nhập dữ liệu vào hệ thống BeeIQ Data Platform, người dùng cần phải khởi tạo URL cho tài khoản của riêng mình. URL này dùng tại bất kì nơi đâu  người dùng muốn đưa dữ liệu vào BeeIQ Data Platforrm. Mỗi tài khoản người dùng có thể đăng kí được nhiều URL cho nhiều mục đích. Để tạo URL này, người dùng cần đăng nhập hệ thống bằng tài khoản admin hoặc owner để khởi tạo URL. Các bước thực hiện cụ thể như bên dưới:

Bước 1: Vào phần Cài đặt → chọn Other settings → chọn Webhook

Bước 2: Chọn Tab Listener và tạo webhook listener

Bước 3: BeeIQ sẽ tự động tạo ra như mô tả ở trên. Đây là URL được sử dụng cho riêng tài khoản người dùng khởi tạo nên không cần nhận thực khi truyền dữ liệu do đó người dùng cần bảo mật URL này để tránh bị SPAM data vào hệ thống.

Khi dữ liệu khách hàng được tạo ra trên hệ thống, ngoài các thuộc tính cơ bản mà trên dữ liệu truyền vào thông qua URL, BeeIQ còn cho phép gắn một số thông số mặc định hoặc tự động kích hoạt một số các hoạt động như sau:

a. Gắn Tag

• Gắn duy nhất 1 Tag cho khách hàng được tạo mới.

• Khi có một yêu cầu tạo dữ liệu gởi về hệ thống theo URL đã tạo, nếu có thông tin khách hàng thì hệ thống sẽ tự kiểm tra sự tồn tại của khách hàng trên hệ thống dựa vào thông tin các trường sau trong thông tin khách hàng: contactId, passport, email, phone. Nếu thông tin khách hàng (Contact / Account) đã có trên hệ thống thì Tag sẽ không được gán cho khách hàng. Tuy nhiên nếu thông tin Tag đã được mô tả trong data gởi vào URL thì cũng ko gán Tag đã được định nghĩa này.

b. Thiết lập kênh khách hàng - sourceContact

• Thiết lập kênh khách hàng  cho khách hàng được tạo mới từ

• Thông tin kênh khách hàng  của Contact/Account chỉ được lấy từ thiết lập này. Các dữ liệu truyền từ data vào sẽ không được chấp nhận sử dụng.

• Tương tự như Tag, hệ thống chỉ thiết lập kênh khách hàng  cho những Contact/Account được tạo mới

c. Tự động gửi Email khi tạo mới khách hàng

• Tính năng cho phép gởi / không gởi email đến khách hàng mới

• Khi cho phép gởi Email đến khách hàng mới, Email được tự động gởi khi có khách hàng mới được tạo ra trên hệ thống thông qua URL này.

• Khi cho phép gởi Email đến khách hàng mới, người dùng phải thiết lập nội dung email để hệ thống tự động gởi.

d. Tự động gửi tin nhắn khi tạo mới khách hàng

• Tính năng cho phép gởi / không gởi email đến khách hàng mới. Tính năng này chỉ áp dụng cho các tài khoản đã đăng kí tài khoản gởi SMS với nhà cung cấp SMS và đã thiết lập tài khoản gởi SMS trên BeeIQ

• Các tài khoản không thiết lập SMS thì sau khi hết các SMS trial của hệ thống sẽ không gởi được nữa.

• Khi cho phép gởi SMS đến khách hàng mới, SMS được tự động gởi khi có khách hàng mới được tạo ra trên hệ thống thông qua URL này.

• Khi cho phép gởi SMS đến khách hàng mới, người dùng phải thiết lập nội dung SMS để hệ thống tự động gởi.

2.2. Cấu trúc data truyền vào URL

Để nhập dữ liệu từ bên ngoài vào BeeIQ Data Platform một cách tự động, người dùng cần theo đúng chuẩn cấu trúc dữ liệu của BeeIQ. Với webhook listener của BeeIQ, người dùng cần sử dụng phương thức <POST> để đẩy dữ liệu qua URL đã kích hoạt.

Những thao tác được cho phép sử dụng để thực hiện việc nhập dữ liệu từ bên ngoài vào BeeIQ Data Platform tự động là:

• Thêm/cập nhậtontact

• Thêm Ghi chú

• Thêm/cập nhật Giao dịch

• Thêm Ticket

Mô hình cấu trúc dữ liệu chung (model-flow) của BeeIQ có dạng sau:

{
  senderUser: <email>, is email of user in an org of beeiq
  data: [
    {
      "actionType": "add-contact", // required
    	 "data":  <data content>
    }
  ] 
}

Sử dụng: người dùng thực hiện gửi một http request đến Listener URL của BeeIQ Data Platform

Mô tả Tham số

2.2.1. Cấu trúc dữ liệu cho hành động thêm mới contact

Nếu người dùng muốn nhập thông tin về và tự động tạo mới contact trên BeeIQ Data Platform, thì thức hiện POST dữ liệu theo cấu trúc sau:

{
   senderUser: <email> //required
   data: [ //required
   {
     "actionType": "add-contact", //required
     "data": { //required
        "name": "",   		//required
        "lastname": "",
        "title": "",
        "passport": "",
        "gender": [0, 1, 2]      // 0: male; 1: female; 2: other
        "dateOfBirth": "",
        "emails": [{type: <email_type>, value: <email>},...], 
        "phones": [{type: <phone_number>, value: <phone_number>},...],
        "addresses": [{type:<type>, street: <street>, city:<city>, state: <state>, zip:<zip>, country:       {code:<country_code>, name:<country_name>}}],
        "websites": [],
        "im": [{type: <im_type>, value: <im>},...],,
        "tag": "",       //String
        "cusFields": [{
               "name": <custom field name>,
		    "value": <value>
        }],
        “companyContact”: {  // remove it if empty
	          "emails": [{value: <email>}], 
    	          "phones": [{value: <phone_number>}], 
                     “name”: “” ,                     
        "websites": [ {
		“value”: “” 
         } ],
         "addresses": [],
 	          "im": [],
         }
      }
   }]
}

Mô tả tham số

[
   {
      type: “Work”, 
      value: “example1@gmail.com”
   }, 
   {
      type: “Home”, 
      value: “example2@gmail.com”
   },...
]

[
   {
      type: “Work”, 
      value: “0905000001”
   }, 
   {
      type: “Home”, 
      value: “0905000002”
   },...
]

[
   {
      type: “Facebook”, 
      value: “facebook_url_”
   }, 
   {
      type: “Skype”, 
      value: “skype_username”
   },...
]

"cusFields": [{
         "name": <custom field name>,
	   "value": <value>
}],

“companyContact”: {  // remove it if empty
   "emails": [{value: <email>}], 
   "phones": [{value: <email>}], 
   “name”: “” ,  
   "websites": [ {
   “value”: “” 
   }],
   "addresses": [],
   "im": [],
}

Lưu ý:

• “companyContact”: Đây trường Công ty, có nghĩa là contact ở trên khi được thêm vào BeeIQ Data Platform nó sẽ thuộc Công ty nào trong dữ liệu Data Platform. Thứ tự thông tin được sắp xếp của BeeIQ Data Platform sẽ như sau: "name", → "emails", → "phones"

• Khi có dữ liệu Công ty trùng, BeeIQ sẽ tự thêm contact vào Công ty đã có

• Khi không có dữ liệu Công ty trùng, BeeIQ sẽ tự thêm Công ty mới và nhập contact vào

• Khi dữ liệu nhập về không có thông tin trường Công ty, BeeIQ sẽ bỏ qua, và chỉ tạo 1 contact không thuộc Công ty nào.

• Đối với những dữ liệu nhập về không có thông tin “emails” và “phones” thì những cấu hình tự động gửi Email hoặc SMS đến contact đó sẽ không được thực thi với những cấu hình trong Listener trên giao diện BeeIQ.

Dữ liệu mẫu

{
   "senderUser": "huy.nguyenviet@htklabs.com",
   "data": [ 
   {
      "actionType": "add-contact", 
      "data": { 
         "contactType": "customer",
         "type": 0,
         "name": "Huy", 
         "lastname": "Nguyen",
         "title": "This is title",
         "passport": "1945295865",
         "gender": 1,
         "dateOfBirth": "Fri Jan 01 1993 00:00:00 GMT+0700 (ICT)",
         "emails": [{"value": "huy.nguyen@htklabs.com"}], 
         "phones": [{"value": "01234567890"}], 
         "addresses": [{
            "street": "58 Ton That Dam",
            "city": "Da Nang",
            "state": "Thanh Khe",
            "zip": "5100000",
            "country": "VN"
         }],
        "websites": [{"value": "htk-inc.com"}],
        "im": [
          {
             "protocol": "Facebook",
             "value": "Huy Nguyen Viet"
          }
        ]
      }
   }]
 }
}

2.2.2. Cấu trúc dữ liệu cho hành động thêm Lead

Người dùng muốn nhập dữ liệu Lead về BeeIQ Data platform một cách tự động, thì thực hiện POST dữ liệu theo cấu trúc với định dạng sau:

{
  "senderUser": "youremail@here.com", //required
  "data": [ //required
  {
    "actionType": "add-lead", // required
    "data": { //required
      "type": 0,
      "name": "",   		//required
      "lastname": "",
      "title": "",
      "passport": "",
      "gender": [0, 1, 2]      // 0: male; 1: female; 2: other
      "dateOfBirth": "",
      "emails": [{
        type: <email_type>, 
        value: <email>},...
      ], 
      "phones": [{
        type: <phones_type>, 
        value: <phone_number>},...
        ],
      "addresses": [{
        type:<type>, 
        street: <street>, 
        city:<city>, 
        state: <state>, 
        zip:<zip>, 
        country:{
          code:<country_code>, 
          name:<country_name>}
        }],
      "websites": [],
      "im": [],
      "tag": "",       //String
      "contactId": <idcontact>     //String 
      "cusFields": [{
        "name": <custom field name>,
        "value": <value>
  		}],
      "companyLead":""  // remove it if empty
    }
  }]
}

Mô tả tham số

Lưu ý: Các tham số của Lead tương tự như Contact

Mẫu dữ liệu mẫu tham khảo

{
  "senderUser": "huy.nguyenviet@htklabs.com",
  "data": [
    {
      "actionType": "add-lead",
      "data": {
        "type": 0,
        "name": "Huy",
        "lastname": "Nguyen",
        "title": "This is title",
        "passport": "1945295865",
        "gender": 1,
        "dateOfBirth": "Fri Jan 01 1993 00:00:00 GMT+0700 (ICT)",
        "emails": [
          {
            "value": "huy.nguyen@htklabs.com"
          }
        ],
        "phones": [
          {
            "value": "01234567890"
          }
        ],
        "addresses": [
          {
            "street": "58 Ton That Dam",
            "city": "Da Nang",
            "state": "Thanh Khe",
            "zip": "5100000",
            "country": "VN"
          }
        ],
        "websites": [
          {
            "value": "htk-inc.com"
          }
        ],
        "im": [
          {
            "protocol": "Facebook",
            "value": "Huy Nguyen Viet"
          }
        ],
        "tag": "webhook",
        "contactId": "1234567897",
        "cusFields": [
          {
            "name": "Referred By",
            "value": "Cong Nguyen"
          }
        ],
        "companyLead": "GOOGLE"
      }
    }
  ]
}

2.2.3. Cấu trúc dữ liệu cho hành động cập nhật Lead

Việc cập nhật thông tin Lead cũng tương tự trúc và định dạng của hành động thêm mới Lead, bằng cách thay đổi hành động như sau: "actionType": "update-lead"

Định dạng cấu trúc đầy đủ như sau:

{
   senderUser: <email> //required
   data: [ //required
   {
      "actionType": "update-lead", // required
      "data": { //required
       "type": 0,
       "name": "", 
       "lastname": "",
       "title": "",
       "passport": "",
       "gender": [0, 1, 2]      // 0: male; 1: female; 2: other
       "dateOfBirth": "",
       "emails": [{value: <email>}], 
       "phones": [{value: <phone_number>}], 
       "addresses": [],
       "websites": [],
       "im": [],
       "tag": “",       //String
       "contactId": <idcontact>     //String 
       "cusFields": [
       {
          "name": <custom field name>,
          "value": <custom field value>
       }],
       “companyLead”: ""  // remove it if empty
     }
  }]
}

Mẫu dữ liệu tham khảo:

{
  "senderUser": "huy.nguyenviet@htklabs.com",
  "data": [
    {
      "actionType": "update-lead",
      "data": {
        "type": 0,
        "name": "Huy",
        "lastname": "Nguyen Viet",
        "title": "This is title",
        "passport": "1945295865",
        "gender": 1,
        "dateOfBirth": "Fri Jan 02 1993 00:00:00 GMT+0700 (ICT)",
        "emails": [
          {
            "value": "huy.nguyen@htklabs.com"
          }
        ],
        "phones": [
          {
            "value": "01234567890"
          }
        ],
        "addresses": [
          {
            "street": "58 Ton That Dam",
            "city": "Da Nang",
            "state": "Thanh Khe",
            "zip": "5100000",
            "country": "VN"
          }
        ],
        "websites": [
          {
            "value": "htk-inc.com"
          }
        ],
        "im": [
          {
            "protocol": "Facebook",
            "value": "Huy Nguyen Viet"
          }
        ],
        "tag": "webhook",
        "contactId": "1234567897",
        "cusFields": [
          {
            "name": "Referred By",
            "value": "Cong Nguyen"
          }
        ],
        "companyLead": "GOOGLE"
      }
    }
  ]
}

2.2.4. Cấu trúc dữ liệu cho hành động cập nhật contact

Với cấu trúc dữ liệu cho hành động cập nhật một contact về BeeIQ Data Platform thì sẽ tượng tự với cấu trúc của hành động tạo mới. Chỉ có trường "actionType" được thay đổi, phần này người dùng cần chuyển loại hành động thành "actionType": "update-contact"

Dưới đây cấu trúc đầy đủ của việc cập nhật contact vào BeeIQ Data Platform

{
   senderUser: <email> //required
   data: [ //required
     {
         "actionType": "update-contact", // required
         "data": { //required
"name": "", 
"lastname": "",
"title": "",
"passport": "",
"gender": [0, 1, 2]      // 0: male; 1: female; 2: other
"dateOfBirth": "",
"emails": [{value: <email>}], 
"phones": [{value: <phone_number>}], 
"addresses": [],
"websites": [],
"im": [],
"tag": “",       //String
"contactId": <idcontact>     //String 
"cusFields": [{
        "name": <custom field name>,
        "value": <custom field value>
   }],
“companyContact”: {  // remove it if empty
     "emails": [{value: <email>}], 
     "phones": [{value: <phone_number>}], 
“name”: “” , 
"contactId": <idcontact>     //String 
     "websites": [ {
         “value”: “” 
}],
   "addresses": [],
 	   "im": [],
     }
  }
}]
}

Lưu ý:

• Bắt buộc phải có thông tin một trong những trường thông tin sau: "contactId",  "passport", "emails", "phones".

• Thứ tự thông tin được sắp xếp của BeeIQ Data Platform sẽ như sau: 1. "contactId",  → 2. "name", → 3. "emails", → 4. "Phones"

• “companyContact”: Đây trường Công ty, có nghĩa là contact ở trên khi được thêm vào BeeIQ Data Platform nó sẽ thuộc Công ty nào trong dữ liệu Data Platform. Thông tin này được tìm kiếm trước khi thêm cho phép thêm một contact vào Công ty đó.

Dữ liệu mẫu tham khảo

{
  "senderUser": "huy.nguyenviet@htklabs.com",
  "data": [ 
    {
      "actionType": "update-contact", 
      "data": { 
        "name": "Huy", 
        "lastname": "Nguyen Viet",
        "title": "This is title",
        "passport": "1945295865",
        "gender": 1,
        "dateOfBirth": "Fri Jan 02 1993 00:00:00 GMT+0700 (ICT)",
        "emails": [{"value": "huy.nguyen@htklabs.com"}], 
        "phones": [{"value": "01234567890"}], 
        "addresses": [{
          "street": "58 Ton That Dam",
          "city": "Da Nang",
          "state": "Thanh Khe",
          "zip": "5100000",
          "country": "VN"
        }],
        "websites": [{"value": "htk-inc.com"}],
        "im": [
          {
            "protocol": "Facebook",
            "value": "Huy Nguyen Viet"
          }
        ],
        "tag": "webhook",    
        "contactId": "1234567897",   
         "cusFields": [{
            "name": "Referred By",
            "value": "Cong Nguyen"
        }],
        "companyContact": {  
             "emails": [{"value": "dong.nguyen@htklabs.com"}], 
             "phones": [{"value": "01234567833"}], 
             "addresses": [{
             "street": "58 Ton That Dam",
             "city": "Da Nang",
             "state": "Thanh Khe",
             "zip": "5100000",
             "country": "VN"
        }],
        "websites": [{"value": "htk-inc.com"}],
        "name": "GOOGLE" 
        }
      }
    }
  ]
}

2.2.5. Cấu trúc dữ liệu cho hành thêm Ghi chú

Đây là hành động dùng cho việc thêm một Ghi chú vào contact hoặc giao dịch. Thông loại hành động này là "actionType": "add-note".

Dưới đây là cấu trúc cho hành độn thêm Ghi chú:

{
	“senderUser”: <email>, //required
	“data”: [{
         "actionType": "add-note", //required
         "data": {
             "body": "", //required
             "emails": "<contact email>", 
             "phones": "<contact phone number>", 
             "passport": "<contact passport>", 
             "name": <name deal>,  
             "contactId": <id-contact>,      
             "dealId": <id-Deal>,    
             "tag": "webhook",    //if model is contact,
             “channel”: “Kite Chat”, // channel ticket
            "model": "contact" or “deal” // optional, default is ‘contact’, support contact, deal only for now
         }
    }]
}

Mô tả tham số

Lưu ý:

Nếu người dùng muốn thêm Ghi chú vào một giao dịch thì thay thế trường “model”: như sau

• Để thêm Ghi chú vào Giao dịch, bắt buộc thông tin được nhập vào phải có thông tin của 1 trong các trường sau "dealId",  "name". Và ưu tiên sắp xếp theo thứ tự các thông tin sau "dealId",  → "name".

Nếu người dùng muốn thêm Ghi chú vào một contact thì thay thế trường “model”: như sau

• Để thêm Ghi chú vào Contact, bắt buộc thông tin được nhập vào phải có thông tin của 1 trong các trường sau "contactId", "passport", "emails", "phones". Và Ưu tiên sắp xếp theo thứ tự sau "contactId", → "passport", → "emails", → "phones".

Dữ liệu mẫu tham khảo

• Contact

{
  "senderUser": "huy.nguyenviet@htklabs.com", 
  "data": [{
    "actionType": "add-note",
    "data": {
        "body": "This is body of Note", 
        "emails": "huy.nguyen@htklabs.com", 
        "phones": "0123456789", 
        "passport": "0123469988", 
        "contactId": "1234567897",       
        "model": "contact",
        "tag": "webhook"    
    }
  }]
}

• Giao dịch

{
  "senderUser": "huy.nguyenviet@htklabs.com", 
  "data": [{
    "actionType": "add-note",
    "data": {
        "body": "This is body of Note", 
        "name": "Booking-ID1135", 
        "dealId": "11358",       
        "model": "deal",
     }
  }]
}

2.2.6. Cấu trúc dữ liệu cho hàng động thêm và cập nhật Giao dịch

Cấu trúc dữ liệu để thêm hoặc cập nhật một giao dịch là giống nhau.

{
"senderUser": "viethuy110@gmail.com",
"data": [
  {
    "actionType": "add-deal",
    "data": {
        "dealId": "1234567890",		//id deal. 
        "name": "Booking-ID #0003",
        "value": 50000,
        "description": "This is desciption",
        "stage": "",  			//name stage in org beeiq. 
        "closeDate": 1482470382793,	//time stamp
        "dealWith": {   			// object contact follow data of action add-contact
          "type": 0,
          "name": "Nguyen viet huy", 
          "lastname": "",
          "title": "",
          "passport": "",
          "gender": "",
          "dateOfBirth": "",
          "emails": [{"value": "huy@gmail.com"}],
          "phones": [{"<phone number>"}], 
           "addresses": "addresses": [{"street":”street, "city": “city”, "country": “country” }],
          "websites": [],
          "im": [],
           "tag": "",                            //string
        },
        "contacts":[{  		// array objects contact follow data of action add-contact
            "type": 0,
            "name": "Quoc Phong", 
            "lastname": "", 
            "title": "",
            "passport": "",
            "gender": "",
            "dateOfBirth": "",
            "emails": [{"value": "phong@gmail.com"}], 
            "phones": [], 
            "addresses": [],
            "websites": [],
            "im": []
         }],
         "cusFields": [{
            "name": <custom field name>,
            "value": <custom field value>
         }],
     }
  }
]
}

Mô tả tham số

2.2.7. Cấu trúc dữ liệu cho hàng động thêm Ticket

Cấu trúc dữ liệu cho hành đồng thêm mới một Ticket trên hệ thống BeeIQ Data Platform:

{
	“senderUser”: <email>, //required
      “data”: [{
           "actionType": "add-ticket", // required
           "data": {
 		   "contactType": "lead", //lead:Lead - customer: Contact 
               “title”: “”
               "body": "", //required
               "emails": "<contact email>", 
               "phones": "<contact phone number>", 
               "passport": "<contact passport>", 
               "name": <name contact>,  
               "contactId": <id-contact>,      
               "dealId": <id-Deal>,    
               "tag": "webhook",
               “groupName”: “”,
               “slaName”: “”,
              “channel”: “Kite Chat”, // channel ticket
          }
     }]
}

Mô tả tham số

Dữ liệu mẫu tham khảo

{
  "senderUser": "huy.nguyenviet@htklabs.com", 
  "data": [{
    "actionType": "add-ticket",
    "data": {
       "contactType": "lead",
        “title”: “title”,
        "body": "This is body of Ticket", 
        "emails": "huy.nguyen@htklabs.com", 
        "phones": "0123456789", 
        "passport": "0123469988", 
        "contactId": "1234567897", 
       “groupName”: “Phong Kinh Doanh”,
       “slaName”: “custom”,
       “channel”: “Contact Form”,
        "tag": "webhook"    
    }
  }]
}