Hướng dẫn cho phép nhập dữ liệu vào BeeIQ tự động


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: 

  1. Để 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ệ

  2. 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.

  1. 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

  1. 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

  1. 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.

  1. 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ật Contact/Account

  • Thêm/cập nhật Lead

  • Thêm Note (Ghi chú)

  • Thêm/cập nhật Deal (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

URL

Listener URL thực hiện copy từ giao diện BeeIQ Data Platform


Ví dụ https://company.beeiq.co/listeners/5aaf2ee7ab22c9a10ecc690f/90aeb7d900febeccd41969c12f955a2bff482ce4

Phương thức

POST

Content-Type

application/json

Giá trị trả về

OK (luôn luôn trả về kết quả này)


Mô tả Tham số

Tham số

Kiểu

Bắt buộc

Mô tả

senderUser

String

Y


  • Email của tài khoản trên BeeIQ tương tác dữ liệu. User tương ứng với email này trên hệ thống sẽ chính là user tương tác cho các hoạt động Thêm /Cập nhật. 

  • Format theo định dạng email

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:

  • add-contact: tạo Contact

  • update-contact: cập nhật Contact

  • add-lead: tạo Lead

  • update-lead: cập nhật Lead

  • add-note: thêm Ghi chú

  • add-deal: thêm Deal

  • add-ticket: thêm Ticket

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

  • Loại hành động là "add-contact"

data

name

String

Y

  • Trường thông tin Tên khách hàng

lastname

String

N

  • Trường thông tin Họ khách hàng

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

  • Trường thông tin Nghề nghiệp

passport

String

N

  • Trường thông tin Số hộ chiếu

gender

Number

N

  • Trường thông tin Giới tính

  • Mặc định "gender": 2,

  • Chú thích:

    • 0: Nam

    • 1: Nữ

    • 2: Khác

bgInfo

String

N

- Trường Thông tin thêm 

dateOfBirth

Date

N

  • Trường thông tin Ngày sinh

  • Format: yyyy-mm-dd

emails


Object Array

N

  • Trường thông tin Email address

  • Format theo định dạng email

  • Ví dụ:

[{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

  • Trường thông tin Địa chỉ

  • Có 3 loại địa chỉ: Work, Home, Other.

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

  • Trường thông tin Website

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

  • Trường thông tin Nhãn/thẻ

  • Ví dụ

"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""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:

  • contact

  • deal

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

"model": "deal"


  • Để 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

"model": "contact"


  • Để 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

  • Contact

{

  "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"]

        }

    }

  }]

}






  • 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,

      "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

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à ContactAccount

- 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 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"    

    }

  }]

}


Bài viết này có hữu ích không? Đánh giá: -15
Chi tiết bài viết:
Ngày đăng: 28/03/2018 4:46PM
Lần cập nhật gần đây: 09/08/2019 6:09PM (manle - man.le@htklabs.com)
Chia sẻ bài viết:   
Tác giả:manle (man.le@htklabs.com)