Tích hợp kênh thoại trên ứng dụng Web (Voice API)

Giải pháp tích hợp kênh thoại trên ứng dụng Web, bao gồm cả luồng gọi vào và gọi ra.

• Hỗ trợ các loại ứng dụng web (web app) tích hợp tổng đài thoại CareSoft.

• Người dùng (user) của doanh nghiệp có thể thực hiện việc tiếp nhận cuộc gọi hay gọi điện ra ra cho khách hàng thông qua số hotline CareSoft.

• Popup thông tin khách hàng khi có cuộc gọi đến

• Công nghệ sử dụng WebRTC không cần cài đặt thêm phần mềm nghe gọi điện.

• Hỗ trợ tích hợp với các thiết bị nghe gọi như IP Phone, Softphone

Chuẩn bị thông tin

1. Lấy mã xác thực từ giao diện admin CareSoft. Truy cập vào CareSoft bằng tài khoản admin mà CareSoft cấp cho khách hàng.

2. Tại menu Admin --> Api --> Api Token. Ở dòng Token voice api hiện tại chọn Tạo token mới nếu chưa có hoặc Copy nếu đã có và lưu lại thành 1 cấu hình {{apiVoiceAccessToken}}

3. Thư viện JWT phù hợp với ngôn ngữ lập trình của bạn để tạo mã token cho mỗi cuộc gọi. Xem thêm ở www.jwt.io

LƯU Ý: Khi bấm nút tạo mới hệ thống sẽ thay thế apiVoiceAccessTokencũ bằng apiVoiceAccessToken mới khiến các ứng dụng đang tích hợp sẽ mất quyền truy cập. Vui lòng cập nhật token ở các ứng dụng theo token mới nếu bạn bấm "Tạo token mới" để đảm bảo hệ thống hoạt động liền mạch

Cách thức tích hợp

1. Chuẩn bị payload để tạo mã token cuộc gọi

{
  "ipphone": "{{agent_id}}",
  "expired": "2017-07-30 00:00:00"
}

Trong đó:

• IpPhone Là số Iphone của Chuyên viên tương ứng (Xem thêm thông tin chuyên viên ở Chuyên viên)

• expired Thời hạn hết hạn của token

2. Lập trình với thư viện JWT để tạo ra chuỗi token trong hình dưới là cách thức gen token sử dụng trực tiếp từ trang web jwt.io. Xem các hướng dẫn và thư viện tương thích trong mục "Libraries" của JWT

Ví dụ: Tạo chuỗi token đăng nhập vào hệ thống Caresoft sử dụng giao diện JWT.io

Copy chuỗi token JWT lưu thành biến {{token}} Ví dụ ở trường hợp trên sẽ là eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....e_ZYyfTxg3EDG6vrKxhbZXPx9tQXrLcB5o

3. Sau khi gen token, CRM gọi API service bên dưới để login vào Caresoft để đăng ký token với hệ thống.

Payload body đăng nhập

 {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....g3EDG6vrKxhbZXPx9tQXrLcB5o"
  }

Đăng nhập VoiceAPI

POST https://capi.caresoft.vn/{domain}/thirdParty/login

Request Body

Name	Type	Description
token*	String	{{token}} Chuỗi token nhận được ở trên

200: OK Thành công

{
    "code": "ok",
    "user": {
        "accountId": 1223,
        "account_id": 1223,
        "userId": "1",
        "email": "[e-mail]",
        "name": "Sale Department",
        "username": "Sale Department",
        "agentId": "5000",
        "agent_id": "5000",
        "phone_no": "0864894596",
        "ipAddress": "222.252.98.36",
        "groupId": "10001",
        "role": "1",
        "active": "1"
    }
}

401: Unauthorized

400: Bad Request

500: Internal Server Error

Mẫu minh họa gọi hàm login từ postman

Lập trình tích hợp tiếp nhận cuộc gọi CareSoft vào CRM

Chú ý: Nếu bạn lập trình trên localhost, cài extension "Allow Cross Domain" trên Chrome để không bị lỗi Cross Domain.

• Import các lib javascript đã được CareSoft cung cấp sẵn vào CRM (trong đó custom.js là file js chứa các hàm CareSoft định nghĩa sẵn để hỗ trợ thông báo, xử lý giao diện, tương tác tuỳ theo nhu cầu của từng CRM)

  	<script src="https://capi.caresoft.vn/js/embed/jquery.min.js" type="text/javascript"></script>    
  	<script src="https://capi.caresoft.vn/js/embed/jssip-3.2.10.js" type="text/javascript"></script>
  	<script src="https://capi.caresoft.vn/js/embed/init-3.0.7.js" type="text/javascript"></script>
  	<script src="https://capi.caresoft.vn/js/embed/web.push.js" type="text/javascript"></script>
  	<script src="https://capi.caresoft.vn/js/embed/cs_const.js" type="text/javascript"></script>
  	<script src="https://capi.caresoft.vn/js/embed/cs_voice.js" type="text/javascript"></script>
  	<script src="custom.js" type="text/javascript"></script>

• Copy dòng sau giữa thẻ body:

  	<video id="my-video" style="display: none;" autoplay playsinline muted></video>
  	<video id="peer-video" style="display: none;" autoplay playsinline></video>

• Thực hiện việc kết nối với tổng đài CareSoft qua hàm sau:

    csInit(token, domain);

Trong đó token là token đã được tạo ra ở bước 1

• Tại một thời điểm, chỉ 1 tab có quyền gọi và tiếp nhận cuộc gọi. Để cho 1 tab bật quyền tiếp nhận cuộc gọi, gọi hàm csEnableCall();

• Hệ thống hỗ trợ 2 loại thiết bị nghe gọi:

• Nghe gọi trên trình duyệt

• Nghe gọi qua softphone, IP Phone

Tuỳ thuộc vào loại thiết bị sẽ sử dụng mà chọn thiết bị bằng cách gọi hàm sau:

         changeDevice(type);

Trong đó: - type = 1: nghe gọi trên trình duyệt - type = 2: nghe gọi qua softphone, IP Phone

Trong trường hợp muốn tắt trình duyệt đi mà vẫn tiếp nhận được cuộc gọi qua ipphone/softphone, chuyển type = 4.

Trong trường hợp muốn tắt trình duyệt đi mà vẫn tiếp nhận được cuộc gọi qua GSM, chuyển type = 3 và truyền vào số điện thoại di động sẽ tiếp nhận cuộc gọi.

           changeDevice(3, '093xxxxxxxx');

Sau khi F5, hoặc đăng xuất, không sử dụng nữa thì phải huỷ đăng ký gọi và chuyển về thiết bị gọi mặc định để có thể tiếp tục sử dụng bình thường bằng cách sử dụng đoạn code sau:

          $(window).bind('unload', function () {
             csUnregister();
                 if (csVoice.enableVoice) {
                         reConfigDeviceType();
                 }
            });

Sau khi kết nối thành công với tổng đài, ngay lúc này đã có thể nhận và gọi điện tới khách hàng. Các hàm dùng để tương tác với hệ thống:

STT	Hàm	Mô tả
1	csEnableCall();	CareSoft chỉ cho phép tại 1 thời điểm có 1 tab được quyền gọi. Vì thế nếu bật nhiều tab hoặc đăng nhập tại nhiều nơi thì cũng chỉ có duy nhất 1 tab được sử dụng chức năng thoại. Tab đầu tiên đăng nhập vào hệ thống sẽ có quyền thoại này. Các tab về sau muốn dùng thì sử dụng hàm này
2	changeCallStatus();	CareSoft có hỗ trợ trạng thái tiếp nhận cuộc gọi là On/Off. Nếu để trạng thái là On thì cuộc gọi sẽ đổ về. Ngược lại thì sẽ không đổ về. Để chuyển qua lại 2 trạng thái thì sẽ dùng hàm này
3	csCallout(number,calloutId);	Gọi điện thoại tới số điện thoại của khách hàng (numberlà số điện thoại cần gọi, calloutId là id dịch vụ gọi ra (optional, nếu không truyền vào sẽ gọi theo dịch vụ mặc định))
4	onAcceptCall();	Tiếp nhận cuộc gọi đến
5	endCall();	Kết thúc cuộc gọi
6	holdCall();	Hold/Unhold cuộc gọi
7	muteCall();	Mute/Unmute cuộc gọi. Sự kiện này được gọi khi cuộc gọi bị Mute. Hàm này chỉ hoạt động cho cuộc gọi nhận từ khách hàng, không hoạt động cho cuộc gọi ra
8	changeDevice(type)	Thay đổi thiết bị tiếp nhận cuộc gọi
9	reConfigDeviceType()	Đối với nhân viên có vai trò Extension, Mobile, Softphone, khi đăng nhập vào để gọi điện sẽ gây bất đồng bộ khiến không thể tiếp nhận cuộc gọi trên các thiết bị mặc định được nữa. Gọi hàm này khi đăng xuất hoặc F5 web tích hợp để chuyển thiết bị nhân viên này về mặc định và tiếp nhận cuộc gọi như bình thường
10	getTransferAgent()	Lấy thông tin agent đang online
11	csTransferCallAgent(ipphone)	Chuyển cuộc gọi qua agent khác, ipphone số ipphone của agent muốn chuyển,Chú ý: agent phải đang trong cuộc gọi mới có thể chuyển cuộc gọi
12	csTransferCallAcd(queueId)	Chuyển cuộc gọi qua nhánh acd khác, queueId id của nhánh acd muốn chuyển,Chú ý: agent phải đang trong cuộc gọi mới có thể chuyển cuộc gọi
13	responseTransferAgent(action)	Tiếp nhận cuộc gọi được chuyển,action=1 đồng ý,action=0 từ chối
14	transferSurvey(survey)	Chuyển cuộc gọi sang khảo sát (after call survey). Chỉ hoạt động khi đang trong cuộc gọi. survey : { id: id của survey, sipurl : sipurl }

Ngoài ra, khi muốn thay đổi giao diện hoặc xử lý thông tin mỗi khi có một sự kiện của cuộc gọi, CareSoft hỗ trợ các hàm sau

Chú ý: Tất cả các hàm dưới đây đều phải được implement để đảm bảo tính đúng đắn của chương trình

STT	Hàm	Mô tả
1	csCallRinging(phone)	Sự kiện này được gọi khi có cuộc gọi đến nhân viên (phone là số điện thoại gọi đến)
2	csAcceptCall();	Sự kiện này được gọi khi nhân viên tiếp nhận cuộc gọi
3	csEndCall();	Sự kiện này được gọi khi cuộc gọi kết thúc.
4	csMuteCall();	Sự kiện này được gọi khi cuộc gọi bị Mute. Hàm này chỉ hoạt động cho cuộc gọi nhận từ khách hàng, không hoạt động cho cuộc gọi ra
5	csUnMuteCall();	Sự kiện này được gọi khi cuộc gọi bị unMute. Hàm này chỉ hoạt động cho cuộc gọi nhận từ khách hàng, không hoạt động cho cuộc gọi ra
6	csHoldCall();	Sự kiện này được gọi khi cuộc gọi bị Hold
7	csUnHoldCall();	Sự kiện này được gọi khi cuộc gọi bị UnHold
8	showCalloutInfo(number)	Sự kiện này được gọi khi có nhân viên gọi ra ngoài cho khách hàng (number là số gọi đi)
9	showCalloutError(errorCode, sipCode)	Sự kiện này được gọi khi có xảy ra lỗi lúc gọi đến khách hàng (errorCode, sipCode sẽ được mô tả trong bảng dưới)
10	csShowEnableVoice(isEnable)	Sự kiện này xảy ra khi một tab này được kích hoạt hay bị tắt chức năng thoại
11	csShowCallStatus(status)	Sự kiện này xảy ra khi trạng thái cuộc gọi bị thay đổi
12	csCustomerAccept()	Sự kiện này được gọi khi khách hàng nghe cuộc gọi đối với cuộc gọi ra
13	csShowDeviceType(type)	Sự kiện này được gọi khi thông tin loại thiết bị đang dùng để tiếp nhận cuộc gọi thay đổi (1: gọi bằng trình duyệt, 2: nhận cuộc gọi qua IP phone nhưng phải đăng nhập vào mới tiếp nhận được, 4: nhận cuộc gọi qua IP phone nhưng không cần đăng nhập vào)
14	csCurrentCallId(callId)	Sự kiện xảy ra khi có cuộc gọi đang diễn ra và trả về callId của cuộc gọi
15	csInitError(errorCode)	Sự kiện này xảy ra khi thiết lập thông số không thành công và sẽ trả về mã lỗi(token lỗi, lỗi kết nối,…)
16	csInitComplete()	Sự kiện được gọi khi thiết lập thành công mọi thông số và đã sẵn sang để bắt đầu nhận hay tiếp nhận cuôc gọi Lưu ý : Trong trường hợp muốn kích hoạt thoại luôn thì sẽ gọi hàm csEnableCall() trong hàm này
17	csListTransferAgent(listTransferAgent)	Sự kiện được gọi khi lấy thành công list agent đang online
18	csTransferCallError(error, tranferedAgentInfo)	Sự kiện được gọi khi chuyển cuộc gọi thất bại. error là mã lỗi trả về, tranferedAgentInfo là thông tin agent được chuyển (có thể null)
19	csTransferCallSuccess(tranferedAgentInfo)	Sự kiện được gọi khi chuyển cuộc gọi thành công. tranferedAgentInfo là thông tin agent được chuyển
20	csNewCallTransferRequest(transferCall)	Sự kiện được gọi khi có một cuộc gọi được chuyển
21	csTransferCallResponse(status)	Sự kiện được gọi khi người được chuyển cuộc gọi bấm từ chối hoặc tiếp nhận yêu cầu. status=OK tiếp nhận,status=NOK từ chối
22	csTransferSurveyResponse(status)	Sự kiện được gọi khi nhận được kết quả gửi khảo sát (status=true thành công, status=false thất bại)
23	csNotifyReconnecting(retry,maxRetry)	Sự kiện được gọi khi socket bị mất kết nối và đang kết nối lại retry Lần retry hiện tại maxRetry Số lần retry tối đa
24	csOndisconnected()	Sự kiện được gọi khi socket đã thất bại quá số lần retry tối đa ở functioncsNotifyReconnecting

Chú ý: csTransferCallError,csTransferCallSuccess,csNewCallTransferRequest chỉ áp dụng cho cuộc gọi chuyển từ agent sang agent , không áp dụng cho cuộc gọi chuyển nhánh, cuộc gọi chuyển nhánh sẽ hoạt động như 1 cuộc gọi vào bình thường

Các hàm này đã được để trong file custom.js

Phụ lục: Bảng mã lỗi khi gọi ra

STT	Error Code	Sip Code	Mô tả
1	IPCC_NOT_CONNECT_CUSTOMER		Gọi ra thất bại, chi tiết trong các mã sip Code bên dưới
2		486	Khách hàng đang bận
3		408	Khách hàng không nghe máy hoặc có lỗi xảy ra
4		403	Lỗi đầu số, xin vui lòng liên hệ đơn vị cung cấp đầu số để được hỗ trợ
5		487	Khách hàng không nghe máy
6		480	Khách hàng không nghe máy
7		404	Không kết nối được đến số thuê bao, xin vui lòng liên hệ đơn vị cung cấp đầu số để được hỗ trợ
8		500	Có lỗi xảy ra, xin vui lòng liên hệ đơn vị cung cấp đầu số để được hỗ trợ
9		600 || 603	Khách không nghe máy hoặc đang bận
10		703	Số gọi ra bị Caresoft chặn
11		786	Lỗi trạng thái nghe gọi, gen token mới hoặc on/off lại trạng thái
12	Các mã khác		Có lỗi xảy ra
13	IPCC_NOT_CONNECT_AGENT_ID		Không thể kết nối được đến thiết bị nghe gọi của tư vấn viênkiểm tra lại IP Phone/SoftPhone và đường truyền Internet
14	CALLOUT_AGENT_BUSY		Busy. Vui lòng đăng xuất và đăng nhập lại để tiếp tục sử dụng.
15	CALLOUT_PERMISSION_DENY		Không có quyền gọi ra. Liên hệ Admin để cấu hình
16	ERROR_CALLOUT_CONNECT		Có lỗi xảy ra
17	ERROR_CALLOUT_NUMBER_BLOCKED		Số điện thoại gọi ra bị chặn theo cấu hình

Bảng mã lỗi khi chuyển cuộc gọi

STT	Error Code	Mô tả
1	NOT_CHOOSE_TYPE_TRANSFER	Chưa chọn loại chuyển cuộc gọi
2	TRANSFER_CALL_FAILED	Chuyển cuộc gọi thất bại
3	NOT_IN_A_CALL	Không trong cuộc gọi
4	COULD_NOT_GET_CALL_INFO	Không thể lấy thông tin cuộc gọi

Các thuộc tính trong csVoice

STT	Thuộc tính	Kiểu dữ liệu	Mô tả
1	isCallout	bool	Có phải là cuộc gọi ra hay không
2	deviceType	int	thiết bị hiện tại, có 5 loại : 1 = web 2 = ipphone/softphone (phải đăng nhập) 3 = divert di động 4 = ipphone/softphone (không cần đăng nhập) 8 = Ứng dụng CareSoft
2	enableVoice	bool	Trạng thái kích hoạt thoại
3	isMute	bool	Đang mute cuộc gọi hay không
4	isHold	bool	Đang hold cuộc gọi hay không
5	getCalloutServices	func	Trả về danh sách các dịch vụ gọi ra mà agent hiện tại được gán quyền. Danh sách trả về gồm 1 mảng object có cấu trúc sau: { "callout_id": Id dịch vụ, "agent_id":ipphone của agent hiện tại, "is_default":có phải dịch vụ mặc định không, "descriptions":Mô tả }

Tham khảo: Code demo https://gitlab.com/caresoftpublic/Demo-Embed-VoiceAPI