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.
Last updated
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.
Last updated
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
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.
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}}
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
Chuẩn bị payload để tạo mã token cuộc gọi
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
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
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.
POST https://capi.caresoft.vn/{domain}/thirdParty/login
token*
String
{{token}} Chuỗi token nhận được ở trên
Mẫu minh họa gọi hàm login từ postman
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)
Copy dòng sau giữa thẻ body:
Thực hiện việc kết nối với tổng đài CareSoft qua hàm sau:
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:
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.
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:
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:
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
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
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
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
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
