HƯỚNG DẪN CHO PHÉP NHẬP
DỮ LIỆU VÀO BEEIQ DATA Platform
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.
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:
Để tăng tính bảo mật và hạn chế rò rỉ thông tin bạn nên thêm IP hợp lệ
Thẻ mặc định
Gắn duy nhất 1 thẻ 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.
Nguồn Contact/Account mặc định
Thiết lập kênh khách hàng cho khách hàng được tạo mới từ Contact/Account
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
Nguồn Lead mặc định
Thiết lập kênh khách hàng cho khách hàng được tạo mới từ Lead
Thông tin kênh khách hàng của Lead 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 Lead được tạo mới
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.
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à:
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ố
Tham số | Kiểu | Bắt buộc | Mô tả |
senderUser | String | Y
| |
data | Array của Object | N | Đây chính là một loạt các hành động tương tác lên BeeIQ |
|
Tham số | Kiểu | Bắt buộc | Mô tả | actionType | String | Y | Loại hành động của thông tin dữ liệu đi kèm. Có 7 loại hành động sau: | data | Object | Y |
|
|
2.2.1. Cấu trúc dữ liệu cho hành động thêm mới Contact/Account
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": "", "type": 0, //if want to add new Account then change 0 to 1 "title": "", "passport": "", "gender": [0, 1, 2] // 0: male; 1: female; 2: other "bgInfo"" <Background information>, //String "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>}}], "im": [{protocol: <im_type>, value: <im>},...],, "tag": "", //String "cusFields": [{ "name": <custom field name>, "value": <value> }], "permit": { "status": <status_of_permit>, // 1: everybody; 2: onlyme; 3: me+group; 4: me+users "group": <name_of_group>, is group name in an org of beeiq "users": [<email_of_user>] is email of users in an org of beeiq }, "companyContact": { // remove it if empty or want to add new account "emails": [{value: <email>}], "phones": [{value: <email>}], "name": "" , "websites": [ { "value": "" } ], "addresses": [], "im": [], } } }] } |
Mô tả tham số
Tham số | Kiểu dữ liệu | Bắt buộc | Giải thích |
senderUser | String | Y
| Trường thông tin này, người dùng thay thế <email> bằng một trong những email bất kỳ của một user thuộc tài khoản đã đăng ký Format theo định dạng email
|
data | actionType | String | Y | |
data | name | String | Y | |
lastname | String | N | |
type | Number | N | - Dùng để phân biệt hành động sẽ là thêm mới Contact hay thêm mới Account. - Nếu 0 là Contact còn 1 là Account - Mặc định sẽ là 0 |
title | String | N | |
passport | String | N | |
gender | Number | N | |
bgInfo | String | N | - Trường Thông tin thêm |
dateOfBirth | Date | N | |
emails |
| Object Array | N | [{type: "Work", value: "example1@gmail.com"}, {type: "Home", value: "example2@gmail.com"},...] |
type | String |
| Loại email (có 4 loại email trong BeeIQ Data Platform: Work, Home, Mobile, Other.) |
value | String |
| Email (format theo định dạng email) |
phones |
| Object Array | N | Trường thông tin Phones Format theo định dạng email Type là loại Phones, có 4 loại phones trong BeeIQ Data Platform: Work, Home, Mobile, Other. Ví dụ:
[{type: "Work", value: "0905000001"}, {type: "Home", value: "0905000002"},...] |
type | String |
| Loại phones |
value | String |
| Số điện thoại |
addresses |
| Object Array | N | |
type | String |
| Có 3 loại địa chỉ: Work, Home, Other |
street | String |
| Tên đường |
city | String |
| Tên thành phố |
state | String |
| Tên tiểu bang |
zip | String |
| Mã bưu chính |
country |
| Object |
| Quốc gia |
code | String |
| Mã quốc gia |
name | String |
| Tên quốc gia |
websites | String | N | |
im |
| Object Array | N | Trường thông tin Tin nhắn Có 6 loại tin nhắn: Skype, Facebook, Yahoo, Viber, Hangouts, Other Ví dụ
[{protocol: "Facebook", value: "facebook_url_"}, {protocol: "Skype", value: "skype_username"},...] |
protocol | String |
| - Loại tin nhắn - Có 6 loại tin nhắn: Skype, Facebook, Yahoo, Viber, Hangouts, Other |
value | String |
| Giá trị của loại tin nhắn tương ứng |
tag | String | N | "tag": "tag_1, tag_2,...", |
cusFields |
| Object | N | - Trường thông tin Tùy chọn "cusFields": [{ "name": <custom field name>, "value": <value> }], |
- Ví dụ: "cusFields": [{"name": "name_01","value": "value_01"}, {"name": "name_02","value": "value_02"}] - Trường hợp trường tùy chỉnh là loại checkbox hoặc checkbox Inline thì các giá trị được ngăn cách bởi dấu "|" . Ví dụ: "cusFields": [{"name": "Bạn thích con gì?", "value": "Chó|Mèo"}]
- Trường hợp trường tùy chỉnh là loại Date thì giá trị format về dạng YYYY-MM-DDTHH:mm:ssZ. Ví dụ:
"cusFields": [{"name": "Ngày bạn nhập học?", "value": "2019-07-08T00:00:00+07:00"}] |
name | String | Tên của trường tùy chỉnh |
value | String | Giá trị của trường tùy chỉnh tương ứng |
permit | Object | N | - Trường thông tin Chia sẻ - Có 4 trạng thái: Tất cả, Chỉ tôi, Tôi và nhóm, Tôi và những nhân viên
Ví dụ: - Trạng thái: Tất cả "permit": {
"status": 1
} - Trạng thái: Chỉ tôi "permit": {
"status": 2
} - Trạng thái: Tôi và nhóm "permit": {
"status": 3, "group": "Nhóm Test"
} - Trạng thái: Tôi và những nhân viên "permit": {
"status": 4, "users": ["huy.nguyen@htklabs.com","luyt.ngo@htklabs.com"] } |
companyContact |
| Object | N | - Trường thông tin Company mà contact thuộc về - Nếu không có thông tin của trường Company thì xóa - Trường thông tin Company cũng là một contact, tham số trong Company giống như 1 contact Lưu ý: Nếu muốn thêm mới một Account thì không dùng đến trường này |
emails | Array Object |
| - Trường Email - Ví dụ [{"value": "crm@beeiq.co"}] |
phones | Array Object |
| - Trường Điện thoại - Ví dụ [{"value": "0906613999"}] |
name | String |
| - Trường Tên Account - Ví dụ "name": "Ngọc Trinh" |
websites | Array Object |
| - Trường Website -Ví dụ [{"value": "BeeIQ"}] |
addresses | Array Object |
| - Tương tự như trường addresses bên trên |
im | Array Object |
| - Tương tự như trường Im bên trên |
Lưu ý:
Các trường sẽ được kiểm tra trùng khi tạo mới Contact/Account là "passport", "phones", "emails". Nếu một trong số những trường này bị trùng với Contact/Account có sẵn, việc thêm mới sẽ không diễn ra. Thay vào đó trong phần Lịch sử của Contact/Account này sẽ được thêm một dòng để báo cho ta biết như hình dưới.
"companyContact": Đây là 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.
Nếu tạo mới thành công trong phần Lịch sử của Contact/Account vừa tạo sẽ có một dòng để báo như hình dưới
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, "bgInfo": "Thành viên AntBuddy", "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"}], "permit": { "status": 1 }, "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 "bgInfo": <Background information>, //String "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": [], "permit": { "status": <status_of_permit>, "group": <group_name>, "users": [<email_of_user>] }, "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
Tham số | Kiểu | Bắt buộc | Mô tả |
actionType | String | Y | Loại hành động của là "add-lead" |
type | String | N | Mặc định "type": 0, |
companyLead | String | N | Account mà Lead thuộc về, nếu không có thông tin trường thông tin này thì xóa |
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, "bgInfo": "Thành viên AntBuddy", "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" } ], "permit": { "status": 1 }, "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ự cấu trúc đị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, "bgInfo": <Background information>, //String "dateOfBirth": "", "emails": [{value: <email>}], "phones": [{value: <email>}], "addresses": [], "websites": [], "permit": { "status": <status_of_permit>, "group": <group_name>, "users": [<email_of_user>] }, "im": [], "tag": "", //String "contactId": <idcontact>, //String "customerId": <code>, //String, exist in BeeIQ "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, "bgInfo": "Thành viên của AntBuddy", "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", "permit": { "status": 2 }, "contactId": "1234567897", "customerId": "LID-123" "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/Account
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": "", "type": 0 //if want to update account then change 0 to 1 "title": "", "passport": "", "gender": [0, 1, 2] // 0: male; 1: female; 2: other "bgInfo": <Background information>, //String "dateOfBirth": "", "emails": [{value: <email>}], "phones": [{value: <email>}], "addresses": [], "websites": [], "permit": { "status": <status_of_permit>, "group": <group_name>, "users": [<email_of_user>] }, "im": [], "tag": "", //String "customerId": <code> //String, exists in BeeIQ "cusFields": [{ "name": <custom field name>, "value": <custom field value> }], "companyContact": { // remove it if empty or want to add new account "customerId": <code>, //String "emails": [{value: <email>}], "phones": [{value: <email>}], "name": "" , "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", "customerId".
Thứ tự thông tin được sắp xếp của BeeIQ Data Platform sẽ như sau: 1. "customerId", → 2. "contactId", → 3. "name", → 4. "emails", → 5. "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, "bgInfo": "Thành viên AntBuddy", "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", "permit: { "status": 3, "group": "Nhom test" }, "customerId": "PID-678", "cusFields": [{ "name": "Referred By", "value": "Cong Nguyen" }], "companyContact": { "customerId": "CID-123", "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 động 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 "email": "<contact email>", "phone": "<contact phone number>", "passport": "<contact passport>", "name": <name deal>, "customerId": <LID hoặc PID>, "dealId": <id-Deal>, "permit": { "status": <status_of_permit>, "group": <group_name>, "users": [<email_of_user>] }, "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ố
Tham số | Kiểu dữ liệu | Bắt buộc | Giải thích |
body | String | Y | Nội dung của Ghi chú |
dealId | String | N | ID của một Giao dịch |
contactId | String | N | ID của một Contact |
model | String | N | - Mặc định "contact" - Có 2 loại "model: |
channel | String | N | Kênh đã cấu hình trong mục cài đặt Kênh Khách hàng trên BeeIQ |
permit | Object | N | Quyền chia sẻ của Ghi chú |
customerId | String | N | - Là mã khách hàng. - Nếu muốn add note cho một Contact thì sẽ là PID. Ví dụ: "customerId":"PID-124" - Nếu muốn add note cho một Lead thì trường này phải đi kèm với trường "contactType": "lead". Ví dụ:
"customerId":"LID-112",
"contactType":"lead" |
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 "customerId", "passport", "emails", "phones". Và Ưu tiên sắp xếp theo thứ tự sau "customerId", → "passport", → "email", → "phone".
Dữ liệu mẫu tham khảo
{ "senderUser": "huy.nguyenviet@htklabs.com", "data": [{ "actionType": "add-note", "data": { "body": "This is body of Note", "email": "huy.nguyen@htklabs.com", "phone": "0123456789", "passport": "0123469988", "customerId": "LID-345", "contactType": "lead", //remove or replace "lead" to "customer" if want to add note for Contact "model": "contact", "tag": "webhook", "permit": { "status": 4, "users": ["huy.nguyen@htklabs.com","luyt.ngo@htklabs.com"] } } }] } |
{ "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, "currency": "VND", "description": "This is desciption", "stage": "", //name stage in org BeeIQ. "closeDate": 1482470382793, //time stamp "category": "UI Design", //name category in org BeeIQ "package": "Goi A", //name package in org BeeIQ "owner_opportunity": { // Owner opportunity "users": ["nhanvien1@beeiq.co","nhanvien2@beeiq.co"], //Emails of users in org BeeIQ "groups": ["Nhom 1","Nhom 2"] //Array of group name in org BeeIQ }, "dealWith": { "type": 0, "name": "Nguyen viet huy", "lastname": "", "title": "", "customerId": "LID-123", "contactType": "lead", //remove or replace "lead" to "customer" if want to add note for Contact/Account "passport": "", "gender": "", "dateOfBirth": "", "emails": [{"value": "huy@gmail.com"}], "phones": [{"value": "0987654321"}], "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": "", "customerId": "LID-123", "contactType": "lead", //remove or replace "lead" to "customer" if want to add note for Contact/Account "passport": "", "gender": "", "dateOfBirth": "", "emails": [{"value": "phong@gmail.com"}], "phones": [], "addresses": [], "websites": [], "im": [] }], "permit": { "status": 4, "users": ["huy.nguyen@htklabs.com","luyt.ngo@htklabs.com"] }, "cusFields": [{ "name": <custom field name>, "value": <custom field value> }], } }] }
|
Mô tả tham số
Tham số | Kiểu dữ liệu | Bắt buộc | Giải thích |
dealId | String | N | - Là mã của một giao dịch đã có trong BeeIQ  => "dealId": 192
- Nếu tìm thấy thấy dealId thì sẽ thực hiện cập nhật giao dịch, nếu không sẽ thêm mới một giao dịch |
name | String | Y | - Là trường tên của giao dịch - Nếu tìm thấy một deal trùng name thì sẽ thực hiện cập nhật giao dịch còn nếu không thì sẽ thêm mới một giao dịch Lưu ý:
- Trường hợp nếu có truyền dealId thì sẽ dựa vào dealId để tìm kiếm giao dịch còn nếu không có thì sẽ dựa vào name |
value | String | N | Là trường Trị giá của giao dịch |
currency | String | N | Là loại tiền tệ thuộc danh sách loại tiền tệ có sẵn trong BeeIQ |
description | String | N | Là trường Mô tả giao dịch |
stage | String | N | - Là trường Trạng thái trong Giao dịch được cấu hình trong BeeIQ - Khi một giao dịch được tạo thì bắt buộc phải có trường này |
owner_opportunity | Object Array | N | - Là trường Người quản lý giao dịch trong giao dịch. - Danh sách những người tham gia quản lý giao dịch đó bao gồm: + Danh sách user: là một mảng danh sách các email của các user có trong org BeeIQ. Trường sử dụng là users + Danh sách nhóm: là một mảng danh sách tên của các nhóm có trong org BeeIQ. Trường sử dụng là groups Ví dụ: "owner_opportunity": {
"users": ["nhanvien1@beeiq.co","nhanvien2@beeiq.co"], "groups": ["Nhom A","Nhom B"] } |
package | String | N | Là trường Gói của giao dịch được cấu hình trong BeeIQ |
category | String | N | Là trường Danh mục của giao dịch được cấu hình trong BeeIQ |
closeDate | Number |
| Là trường Ngày kết thúc trong Giao dịch |
dealWith | Object | N | - Là trường Khách hàng trong giao dịch trên BeeIQ Data Platform - Khi một giao dịch được tạo thì bắt buộc phải có trường này - Nếu như khách hàng không được tìm thấy trong hệ thống, BeeIQ sẽ tạo một khách hàng mới với thông tin được truyền vào |
Tham số | Bắt buộc | Kiểu dữ liệu | Giải thích | passport | Y | String | - Số hộ chiếu của khách hàng | phones | Y | Array Object | - Cấu trúc tương tự như ở phần thêm Contact/Account | emails | Y | Array Object | - Cấu trúc tương tự như ở phần thêm Contact/Account | name | N | String | - Tên khách hàng. Nếu muốn tạo mới Khách hàng bạn cần nhập tên | lastname | N | String | - Họ khách hàng | addresses | N | Array Object | - Cấu trúc tương tự như ở phần thêm Contact/Account | cusFields | N | Array Object | - Cấu trúc tương tự như ở phần thêm Contact/Account | dateOfBirth | N | Date | - Cấu trúc tương tự như ở phần thêm Contact/Account | tag | N | String | Trường thông tin Nhãn/thẻ Ví dụ "tag": "tag_1, tag_2,...",
| permit | N | Object | - Cấu trúc tương tự như ở phần thêm Contact/Account | contactType | N | String | - Dùng để phân biệt loại khách hàng trong BeeIQ - Có 2 loại là: + "contactType": "lead" chỉ đối tượng là Lead + "contactType": "customer" chỉ đối tượng là Contact và Account - Mặc định tham số này là customer | type | N | Number | - Dùng để phân biệt loại khách hàng trong BeeIQ - Có 2 loại là: + "type": 0 chỉ đối tượng là Lead và Contact + "type": 1 chỉ đối tượng là Account - Mặc định tham số này là 0 | customerId | N | String | - Là mã khách hàng trên BeeIQ. - Nếu muốn add deal cho một Contact thì sẽ là PID. Ví dụ: "customerId":"PID-124" - Nếu muốn add deal cho một Lead thì trường này phải đi kèm với trường "contactType": "lead". Ví dụ:
"customerId":"LID-112",
"contactType":"lead" | companyContact |
Tham số | Bắt buộc | Kiểu dữ liệu | Giải thích | customerId | Y | String | - Là mã khách hàng trên BeeIQ. - Nếu muốn add deal cho một Contact thì sẽ là PID. Ví dụ: "customerId":"PID-124" - Nếu muốn add deal cho một Lead thì trường này phải đi kèm với trường "contactType": "lead". Ví dụ:
"customerId":"LID-112",
"contactType":"lead" | emails | Y | Array Object | - Cấu trúc tương tự như ở phần thêm Contact/Account | phones | Y | Array Object | - Cấu trúc tương tự như ở phần thêm Contact/Account | websites | Y | Array Object | - Cấu trúc tương tự như ở phần thêm Contact/Account | name | N | String | - Tên khách hàng | addresses | N | Array Object | - Cấu trúc tương tự như ở phần thêm Contact/Account | permit | N | Object | - Cấu trúc tương tự như ở phần thêm Contact/Account |
|
|
permit | Object | N | - Cấu trúc tương tự như ở phần permit trong add/update Contact/Account |
contacts | Array Object | N | - Là trường Khách hàng liên quan của giao dịch trên BeeIQ Data Platform - Nếu như khách hàng không được tìm thấy trong hệ thống, BeeIQ sẽ tạo một khách hàng mới với thông tin được truyền vào - Cấu trúc tương tự như dealWith |
cusFields | Object | N | - Cấu trúc tương tự như ở phần thêm Contact/Account nhưng sử dụng trường tùy chỉnh của Deal |
2.2.7. Cấu trúc dữ liệu cho hành độ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 "email": "<contact email>", "phone": "<contact phone number>", "passport": "<contact passport>", "name": <name contact>, "contactId": <id-contact>, "customerId": <code_customer> "dealId": <id-Deal>, "tag": "webhook", "groupName": "", "slaName": "", "channel": "Kite Chat", // channel ticket } }] } |
Mô tả tham số
Tham số | Kiểu dữ liệu | Bắt buộc | Giải thích |
contactType | String | Y | - Có 2 loại contact: lead, customer - Mặc định "contactType": "customer", |
body | String | Y | - Trường thông tin Mô tả của Ticket - Bắt buộc phải có |
groupName | String | N | - Nhóm người dùng được cấu hình trên BeeIQ |
slaName | String | N | - Trường thông tin SLA được cấu hình ở phần cài đặt Ticket (SLA) |
channel | String | N | - Có 9 Kênh: Email, Phone, Web Contact Form, Kite Call, Kite Chat, Kite Viber, Kite Facebook, Kite Skype |
Dữ liệu mẫu tham khảo
{ "senderUser": "huy.nguyenviet@htklabs.com", "data": [{ "actionType": "add-ticket", "data": { "contactType": "lead", //remove or replace "lead" to "customer" if want to add ticket for Contact/Account "title": "title", "body": "This is body of Ticket", "email": "huy.nguyen@htklabs.com", "phone": "0123456789", "passport": "0123469988", "contactId": "1234567897", "customerId": "LID-123", "groupName": "Phong Kinh Doanh", "slaName": "custom", "channel": "Contact Form", "tag": "webhook" } }] } |
2.2.8. Cấu trúc dữ liệu cho hành động gửi sms
Cấu trúc dữ liệu cho hành đồng gửi sms trên hệ thống BeeIQ Data Platform:
{ "senderUser": <email>, //required "data": [{ "actionType": "send-sms", // required "data": { "content": "", //required "phones": [“list phones”] //required } }] } |
Mô tả tham số
Tham số | Kiểu dữ liệu | Bắt buộc | Giải thích |
content | String | Y | Nội dung sms |
phones | Array | Y | Danh sách các số điện thoại gửi sms |
Lưu ý:
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.
Dữ liệu mẫu tham khảo
{ "senderUser": "huy.nguyenviet@htklabs.com", "data": [{ "actionType": "send-sms", "data": { "content": "This is content", "phones": [“0333456789”,”098765431”] } }] } |