Đã đăng vào thg 4 3, 2023 7:57 SA

trong

15 phút đọc

219

Hướng dẫn xây dựng tổng đài với Stringee Programmable Contact Center API (PCC API)

1. Các khái niệm cơ bản nhất về tổng đài

Hình bên dưới là luồng 1 cuộc gọi khi khách hàng gọi vào số tổng đài (Number) của doanh nghiệp

Ví dụ, bạn có thể gọi vào số tổng đài của Stringee: 02473.0000.97‬ (hoặc bấm +84.2473.0000.97‬ nếu bạn không ở Việt Nam) để thử.

a. IVR (Interactive voice response)

Ở hình trên, đầu tiên khách hàng (Customer) sẽ nghe 1 thông báo (Greeting): "Vui lòng nhấn phím 1 để nghe hướng dẫn bằng tiếng Anh, phím 2 nghe hướng dẫn bằng tiếng Tây Ban Nha". Khi bấm phím 1, khách hàng sẽ nghe thông báo bằng tiếng Anh: "Để gặp bộ kinh doanh bấm phím 1, để gặp bộ phận hỗ trợ kỹ thuật bấm phím 2",...

Lúc này, khách hàng đang ở trong 1 cây IVR (IVR tree). Một đoạn thông báo trên gọi là 1 nốt (IVR node). Tại 1 nốt khách hàng có thể bấm phím để đi đến 1 nốt khác, hoặc chuyển sang chờ gặp tư vấn viên (Agent); 1 phím bấm (IVR node keypress) này có thể hiểu là 1 nhánh.

b. Queue

Ở hình trên, khi khách hàng đang nghe thông báo bằng tiếng Anh: "Để gặp bộ kinh doanh bấm phím 1, để gặp bộ phận hỗ trợ kỹ thuật bấm phím 2", khách hàng tiếp tục bấm phím 2 thì sẽ được chuyển vào hàng đợi (Queue) 2, để chờ được Agent phục vụ.

Queue được sinh ra để đảm bảo khi số lượng Agent bé hơn số lượng khách hàng chờ thì khách hàng sẽ được phục vụ theo thứ tự mong muốn: gọi vào trước được phục vụ trước, khách VIP được phục vụ trước,... Hình ảnh này giống như khi bạn xếp thành nhiều hàng chờ để mua vé xem phim vậy.

c. Agent và Group

Ở hình trên, các Agent được phân thành 3 nhóm (Group) khác nhau với các kỹ năng khác nhau:

Group 1: nói được tiếng Anh, có kỹ năng bán hàng
Group 2: nói được tiếng Anh và tiếng Tây Ban Nha, có kỹ năng hỗ trợ kỹ thuật cho khách hàng
Group 3: nói được tiếng Tây Ban Nha, có kỹ năng bán hàng

d. Định tuyến cuộc gọi vào các nhóm (Group routing)

Ở hình trên:

Queue 1: được gán cho Group 1 phục vụ vì khách hàng đang cần các Agent biết tiếng Anh hỗ trợ họ mua hàng.
Queue 2: được gán cho Group 2 phục vụ vì khách hàng đang cần được hỗ trợ kỹ thuật. Ngoài ra, khi tất cả các Agent ở Group 2 bận thì khách hàng đợi ở Queue 2 vẫn có thể được phục vụ bởi Agent ở Group 3.
Queue 3: được gán cho Group 3 phục vụ vì khách hàng đang cần các Agent biết tiếng Tây Ban Nha hỗ trợ họ mua hàng.

Việc gán Group vào từng Queue có đánh độ ưu tiên (primary_group) gọi là Group routing.

e. Có thể bỏ qua IVR

Có thể bỏ qua IVR, cho khách hàng gọi thì vào thẳng Queue bằng cách thiết lập tham số enable_ivr=false của Number (https://developer.stringee.com/docs/pcc-rest-api/integrable-contact-center-number-management)

2. Các bước thực hiện xây dựng 1 tổng đài dựa trên Stringee PCC API

Xem hướng dẫn qua video tại đây:

Timestamp cho video hướng dẫn:

0:6 - Bước 1: Tạo Project và mua số tổng đài
1:51 - Bước 2: Cấu hình Number (hotline), IVR, Queue, Agent, Group, Group routing
31:17 - Bước 3: Viết client nhận cuộc gọi

Bước 1: Tạo Project và mua số tổng đài

Tạo 1 Project tại đây

Tích chọn "Enable Programmable Contact Center API for this Project?" hoặc thiết lập các URL cho Project này như sau:

Answer URL: http://v2.stringee.com:8282/project_answer_url
Event URL: http://v2.stringee.com:8282/project_event_url

Lưu ý: để sử dụng PCC API thì bạn bắt buộc phải cấu hình URL đúng như trên

Mua 1 số điện thoại để làm số tổng đài tại đây (hoặc cũng có thể chuyển đổi số SIP có sẵn của bạn sang Stringee, liên hệ với chúng tôi để được hướng dẫn chi tiết). Gán số đã mua này vào Project trên.

Tích chọn "Enable Programmable Contact Center API for this Number?" hoặc thiết lập các URL cho số này như sau:

Answer URL: http://v2.stringee.com:8282/answer_url
Event URL: http://v2.stringee.com:8282/event_url

Lưu ý: để sử dụng PCC API thì bạn bắt buộc phải cấu hình URL đúng như trên

Bước 2: Cấu hình Number (hotline), IVR, Queue, Agent, Group, Group routing

Để cấu hình các tham số/thành phần trên, bạn có thể dùng REST API được mô tả ở đây. Tuy nhiên, để bắt đầu nhanh chóng bạn có thể dùng tool chúng tôi cung cấp ở đây: https://pcc.stringee.com/

Đăng nhập vào https://pcc.stringee.com/ và chọn Project bạn đã tạo ở bước 1.

a. Cấu hình Number:

Thêm số đã mua ở bước 1 vào tại đây: https://pcc.stringee.com/setting/number

b. Cấu hình IVR:

Tạo mới 1 cây IVR tại đây: https://pcc.stringee.com/setting/ivrtree
Tạo Node đầu tiên cho cây IVR

c. Cấu hình Agent:

Thêm mới Agent ở đây: https://pcc.stringee.com/setting/agent

d. Cấu hình Group:

Thêm mới Group ở đây: https://pcc.stringee.com/setting/group
Thêm các Agent vừa tạo vào group

e. Cấu hình Queue:

Tạo mới Queue ở đây: https://pcc.stringee.com/setting/queue

f. Cấu hình Group routing:

Chọn 1 Queue và nhấn vào "Group routing" để gán 1 hoặc nhiều Group phục vụ Queue đó

g. Cấu hình khi bấm phím IVR thì vào Queue

Chọn 1 cây IVR, chọn 1 node và thêm phím bấm cho node đó

h. Các file thông báo, nhạc chờ trong Queue

Upload, quản lý các file nhạc chờ trong Queue (lúc chưa gặp Agent) hoặc các file thông báo khi khách hàng đang ở IVR ở đây: https://pcc.stringee.com/setting/greeting

i. Thiết lập khi gọi vào số tổng đài thì đổ vào cây IVR

Vào link https://pcc.stringee.com/setting/number , chọn "Edit" số đã cấu hình ở trên, chọn "Enable IVR" và chọn cây IVR đã tạo.

Khi thực hiện xong các bước trên, bạn đã có thể gọi thử vào số tổng đài, nghe IVR, nhấn phím để chuyển sang Node khác hoặc chuyển vào Queue. Nếu vẫn chưa được, vui lòng kiểm tra lại .

Bước 3: Viết client nhận cuộc gọi

a. Agent và các loại trạng thái

Mỗi Agent có các thông tin cần lưu ý sau:

{
    "stringee_user_id": "agent_1",
    "phone_number": "84909982888",
    "routing_type": 1,
    "manual_status": "AVAILABLE",
    "system_status": 0
}

Chi tiết hơn xem tại đây.

Trong đó:

stringee_user_id: là userId mà Agent đó xác thực vào hệ thống Stringee. Chi tiết xem thêm tại đây, lưu ý phần payload phải có thêm icc_api=true (chỉ riêng PCC API yêu cầu tham số này):

{
    "jti": "SK...-...",//JWT ID
    "iss": "SK...",//API key sid
    "exp": ...,//expiration time
    "userId": "...",
    "icc_api": true
}

phone_number: số điện thoại của Agent (phải bao gồm cả mã nước phía trước)
routing_type: 1 nếu muốn nhận cuộc gọi đến trên App/SIP Phone; 2 nếu muốn nhận cuộc gọi đến số điện thoại (sẽ bị tính thêm phí nhà mạng)
manual_status: trạng thái do Agent tự chọn. Để cuộc gọi đổ đến, trạng thái này bắt buộc là: AVAILABLE. VD: khi Agent ra ngoài, họ có thể chuyển trạng thái này thành: INVISIBLE, lúc đó cuộc gọi sẽ không đổ đến Agent này.
system_status: trạng thái này do Stringee PCC API thay đổi, khi Agent này đang nghe cuộc gọi trạng thái này sẽ được tự động set bằng 0, ngược lại khi đang không nghe cuộc gọi nào trạng thái này sẽ được set là 1.
Trạng thái online/offline: 1 Agent được tính là online khi thoả mãn 1 trong các điều kiện sau:
- Đang login vào Stringee qua App/Web
- Đã login vào App 1 lần, đã có PUSH NOTIFICATION device token (iOS/Android) đảm bảo có thể nhận cuộc gọi qua đường push notification.
- Đang online 1 thiết bị SIP Phone

b. Điều kiện cần để cuộc gọi được đổ đến 1 Agent

Stringee PCC sẽ đổ cuộc gọi của khách hàng đến 1 Agent chỉ nếu:

system_status=1
manual_status=AVAILABLE
routing_type=1 và Agent đang online; hoặc routing_type=2 và Agent đã cấu hình số điện thoại

c. Đăng nhập 1 Agent (trên App/Web) để nghe cuộc gọi

Để đăng nhập 1 Agent vào Stringee để nhận cuộc gọi, bạn cần 1 access_token như đã mô tả tại đây.

Để tạo nhanh access_token, bạn có thể dùng tool chúng tôi cung cấp tại đây, chọn đúng Project đã tạo ở bước 1 mục 2 và "User ID" có giá trị bằng stringee_user_id của Agent. Lưu ý cần tích vào "For PCC API" (payload sẽ có thêm icc_api=true):

Tải sample chúng tôi cung cấp tại đây và thay thế giá trị access_token:

Ngoài ra, chúng tôi cung cấp Stringee Web Phone (xây dựng 100% dựa trên Stringee JavaScript SDK) với đầy đủ giao diện để bạn có thể nhúng nhanh chóng vào Web của mình:

Nhúng đoạn mã JavaScript sau vào Web của bạn:

<script src="https://static.stringee.com/web_phone/lastest/js/StringeeSoftPhone-lastest.js"></script>
<script>
    var config = {
        showMode: 'full',//full | min | none
        top: 45,
        left: 50,
        //right: 810,

        arrowLeft: 155,
        arrowDisplay: 'top',//top | bottom | none

        //list your Stringee Number
        fromNumbers: [{alias: 'Number-1', number: '+84899199586'}, {alias: 'Number-2', number: '+2222'}]
    };
    StringeeSoftPhone.init(config);

    var access_token2 = 'YOUR_ACCESS_TOKEN';

    StringeeSoftPhone.on('displayModeChange', function (event) {
        console.log('displayModeChange', event);
        if (event === 'min') {
            StringeeSoftPhone.config({arrowLeft: 75});
        } else if (event === 'full') {
            StringeeSoftPhone.config({arrowLeft: 155});
        }
    });

    StringeeSoftPhone.on('requestNewToken', function () {
        console.log('requestNewToken+++++++');
        StringeeSoftPhone.connect(access_token2);
    });
    
    StringeeSoftPhone.connect(access_token2);
</script>

Demo: https://v1.stringee.com/demo/web_phone.html

Xem thêm hướng dẫn chi tiết tại đây

Mã nguồn được chúng tôi cung cấp tại đây.

d. Đăng nhập 1 Agent qua SIP Phone để nghe cuộc gọi (Tuỳ chọn)

Nếu bạn muốn Agent nghe cuộc gọi qua SIP Phone (IP Phone hoặc SIP Softphone), ở bước tạo Agent bạn cần tích vào "Create SIP Phone account" và nhập "SIP Phone password":

Bạn có thể dùng API để quản lý SIP Phone: https://developer.stringee.com/docs/call-rest-api/sip-phone-management

Thông tin để đăng ký SIP Phone vào Stringee như sau:

Domain: v2.stringee.com:15060
Username: projectId_userId
Password: password đã nhập ở trên

Bước 4: Gọi ra cho khách hàng

a. Cách 1:

Dùng Mobile SDK hoặc Web SDK gọi hàm makeCall, VD với bản web:

call = new StringeeCall(stringeeClient, fromNumber, toNumber);
settingCallEvents(call);
call.makeCall(function (res) {
    console.log('make call callback: ' + JSON.stringify(res));
});

trong đó:

fromNumber là số tổng đài đã mua ở Bước 1 mục 2
toNumber là số của khách hàng

b. Cách 2:

Sử dụng REST API sau để tạo 1 cuộc gọi ra App/SIP Phone của Agent trước, khi Agent nghe máy thì mới gọi ra cho khách hàng và cho 2 người nói chuyện với nhau:

POST https://icc-api.stringee.com/v1/call/callout

{
    "agentUserId": "huy",
    "toAgentFromNumberDisplay": "Call-out-from-842473082686",
    "toAgentFromNumberDisplayAlias": "Call-out-from-842473082686-Alias",
    "toCustomerFromNumber": "84899199586",
    "customerNumber": "84909982888"
}

trong đó:

agentUserId: Stringee User ID của Agent muốn tạo cuộc gọi đến
toAgentFromNumberDisplay: số hiển thị đến Agent khi Agent nhận cuộc gọi đến (trường fromNumber)
toAgentFromNumberDisplayAlias: số hiển thị đến Agent khi Agent nhận cuộc gọi đến (trường fromAlias)
customerNumber: số của khách hàng muốn gọi đến (sau khi Agent nhấc máy)
toCustomerFromNumber: số hiển thị đến KH khi KH nhận cuộc gọi đến

c. Cách 3:

Bấm phím và gọi trực tiếp trên SIP Phone.

Bước 5: Tuỳ chỉnh tập Agent nhận cuộc gọi từ các khách hàng khác nhau (tuỳ chọn)

Mặc định cuộc gọi của khách hàng khi vào Queue sẽ được PCC API đổ đến các Agent trong các Group mà đã gán cho Queue đó (xem hình đầu tiên).

Tuy nhiên, bạn cũng có thể tuỳ chỉnh tập Agent để nhận cuộc gọi cho từng cuộc gọi (từng khách hàng) khác nhau. VD: khách hàng A đã để lại số điện thoại trên website của bạn, hệ thống CRM đã gán khách hàng này cho bạn Sales 1 hỗ trợ; sau đó khách hàng A gọi lên tổng đài, bạn muốn: ưu tiên cuộc gọi đổ đến Sales 1 trước, nếu Sales 1 không nghe máy hoặc bận thì mới đổ đến Sales 2, 3,...

Để thực hiện việc này bạn cần thiết lập tham số "get_list_agents_url" của Queue đó.

a. Khi có cuộc gọi vào Queue, Stringee gửi HTTP POST sang get_list_agents_url để lấy danh sách Agents cho các cuộc gọi trong Queue

Method: POST

Body:

{
    "queueId": "queue_1",
    "calls": [{
        "callId": "call-vn-1-EHHC6JW1LT-1534145391502",
        "from": "84986776777",
        "to": "842473082666"
    }, {
        "callId": "call-vn-1-EHHC6JW1LT-1534145391504",
        "from": "84919982888",
        "to": "842473082888"
    }],
    "projectId": 25
}

trong đó

Field	Type	Require	Description
queueId	String	Yes	Queue ID
projectId	Int	Yes	Your project ID
calls	Array	Yes	Danh sách các cuộc gọi trong Queue tại thời điểm đó

b. Dữ liệu bạn cần trả về như sau

{
    "version": 2,
    "calls": [{
            "callId": "call-vn-1-EHHC6JW1LT-1534145391502",
            "agents": [{
                    "stringee_user_id": "agent_1",
                    "phone_number": "84909992666",
                    "routing_type": 2,
                    "answer_timeout": 15
                },
                {
                    "stringee_user_id": "agent_2",
                    "phone_number": "84909992666",
                    "routing_type": 1,
                    "answer_timeout": 10
                }
            ]
        },

        {
            "callId": "call-vn-1-EHHC6JW1LT-1534145391504",
            "agents": [{
                    "stringee_user_id": "agent_1",
                    "phone_number": "84909992666",
                    "routing_type": 2,
                    "answer_timeout": 15
                }
            ]
        }
    ]
}

trong đó

Field	Type	Require	Description
version	Int	Yes	Bắt buộc là 2
calls	Array	Yes	Danh sách các cuộc gọi trong Queue tại thời điểm đó, tương ứng với request mà Stringee gửi sang

các tham số của từng "call" như sau:

Field	Type	Require	Description
callId	String	Yes	Call ID
agents	Array	Yes	Danh sách các Agent có thể nhận cuộc gọi, được xếp theo thứ tự ưu tiên: Agent ở trước có độ ưu tiên cao hơn Agent ở sau. Nếu Agent ở trước rảnh thì cuộc gọi sẽ được đổ vào, ngược lại nếu Agent ở trước bận thì hệ thống sẽ kiểm tra lần lượt các Agent phía sau

các tham số của từng "agent" như sau

Field	Type	Require	Description
stringee_user_id	String	Yes	User ID của Agent dùng để xác thực vào Stringee
phone_number	String	No	Phone Number của Agent, bắt đầu bằng mã nước
routing_type	Int	Yes	1: đổ cuộc gọi sang App/SIP Phone, 2: đổ cuộc gọi ra Phone Number của Agent
answer_timeout	Int	Yes	Nếu Agent rảnh, cuộc gọi sẽ đổ vào Agent và thời gian tối đa để Agent nghe máy là tham số này tính bằng giây. Sau thời gian này, nếu Agent ko nghe máy, cuộc gọi sẽ đổ sang Agent tiếp theo trong list Agents mà YourServer trả về

Bước 6: Một số tham số hay sử dụng cần lưu ý

Không muốn sử dụng IVR, cuộc gọi của khách hàng đến số tổng đài đẩy thẳng vào Queue:

Cấu hình tham số "enable_ivr=false" cho số đó (API)

Các tham số quan trọng của Queue (API):
- wait_agent_answer_timeout: cuộc gọi đổ đến 1 Agent, nếu sau khoảng thời gian này (tính bằng giây) mà Agent không nghe máy thì cuộc gọi sẽ đổ sang Agent khác. Nếu Group chỉ có 1 Agent rảnh thì cuộc gọi lại đổ vào Agent này tiếp.
- wrap_up_time_limit: nếu tham số agent_wrap_up_after_calls=true, sau khi Agent ngắt máy với khách hàng thì Agent sẽ có tiếp wrap_up_time_limit giây để nhập liệu thông tin về khách hàng, cuộc gọi sẽ không đổ vào trong khoảng thời gian này kể cả Agent rảnh.
- get_list_agents_url: nếu giá trị này được thiết lập, Stringee PCC sẽ không lấy danh sách Agent từ các Group được gán vào mà lấy từ kết quả trả về của URL này
Phân quyền, điều khiển việc gọi ra: Sử dụng API này, thiết lập tham số: callout_answer_url. Lúc này khi Agent gọi ra, Stringee PCC sẽ gửi yêu cầu sang URL này (Answer URL), URL này cần trả về SCCO quyết định việc cho phép gọi hay không.

Tham khảo hướng dẫn sau: https://developer.stringee.com/docs/server/event-url-and-answer-url