Tích hợp Alohub Softphone vào Salesforce — Hướng dẫn từng bước

Tài liệu này hướng dẫn quy trình tích hợp softphone WebRTC của Alohub vào một Salesforce org từ đầu đến khi gọi ra/nghe gọi được trong Lightning Experience. Trọng tâm là các bước cấu hình thực tế và những lỗi thường gặp (CSP chặn click-to-dial, micro không hoạt động, cuộc gọi bị từ chối) cùng cách xử lý.

Đối tượng: Salesforce admin/developer triển khai package vào org. Yêu cầu Salesforce CLI (sf), quyền cấu hình Session Settings, Call Center, Utility Bar và Lightning App Builder.

1. Kiến trúc tích hợp (tóm tắt)

Softphone chạy như một Lightning Web Component (alohubPhone) trên Utility Bar, kết nối SIP/WebRTC qua JsSIP tới SIP server của Alohub. Một lớp Open CTI bridge (Visualforce) và component Alohub Call Button đảm nhiệm click-to-dial qua Lightning Message Service (LMS).

Thành phần	Loại	Vai trò trong tích hợp
`alohubPhone`	LWC (Utility Bar)	Giao diện softphone, đăng ký SIP, quay số, nghe/gọi
`alohubCallButton`	LWC (Record Page)	Nút gọi trên record — thay thế click-to-dial native bị CSP chặn
`alohubCtiBridge`	Visualforce	Adapter Open CTI: nhận click-to-dial native, screen-pop cuộc gọi đến
`CallMessageChannel`	Message Channel	Kênh LMS nối bridge/Call Button ↔ softphone

2. Yêu cầu trước khi bắt đầu

Hạng mục	Yêu cầu
Tài khoản SIP	WSS URL, SIP domain, username (extension), password — do Alohub cung cấp
Trình duyệt	Chrome/Edge mới, truy cập org qua HTTPS (My Domain), cho phép micro
Quyền admin	Sửa Session Settings, Call Center, Utility Bar, Lightning Record Page

Quan trọng: Thông số SIP do Alohub cấp riêng cho từng khách hàng. Liên hệ để nhận: https://alohub.vn/lien-he.

3. Bước 1 — Deploy package vào org

Đăng nhập org và deploy source. Ví dụ với alias myOrg:

sf org login web --alias myOrg \
  --instance-url https://login.salesforce.com

sf project deploy start --source-dir force-app --target-org myOrg

4. Bước 2 — Bật Lightning Web Security (bắt buộc cho micro)

Softphone dùng navigator.mediaDevices.getUserMedia để lấy micro. Dưới Locker Service (chế độ bảo mật cũ), navigator.mediaDevices không được expose cho LWC → cuộc gọi báo lỗi Cannot read properties of undefined (reading 'getUserMedia'). Lightning Web Security (LWS) expose đầy đủ API này.

Vào Setup → Session Settings → bật "Use Lightning Web Security for Lightning web components and Aura components" → Save.

Cảnh báo: LWS là thay đổi org-wide, có thể ảnh hưởng các LWC/Aura khác. Hãy bật và kiểm thử trên sandbox trước khi áp dụng production.

Cách kiểm tra nhanh trạng thái: mở DevTools Console khi softphone đang chạy, log khởi tạo media sẽ in hasMediaDevices: true nếu LWS đã expose đúng.

5. Bước 3 — Khai báo CSP Trusted Site cho WSS

Kết nối SIP đi qua WebSocket Secure (WSS). Domain WSS phải nằm trong CSP Trusted Sites với connect-src được bật, nếu không trình duyệt sẽ chặn kết nối.

Trường	Giá trị
Endpoint URL	`wss://crm.alohub.vn:57445` (thay bằng WSS Alohub cấp)
Active	true
connect-src (CSP)	Bật

Lưu ý: Nếu Alohub cấp WSS khác (vd wss://app.alohub.vn:57443), phải thêm domain đó vào Trusted Sites — nếu không sẽ lỗi Refused to connect.

6. Bước 4 — Thêm softphone vào Utility Bar

Vào Setup → App Manager → chọn Lightning App đang dùng → Edit → Utility Items → Add Utility Item → chọn alohubPhone.

Quan trọng: Bật "Start automatically" (Load in background when app opens). Component Utility Bar được load lười (lazy) — nếu không bật auto-start, softphone chưa khởi tạo thì không subscribe được kênh LMS, dẫn đến click-to-dial từ record page bấm không có phản hồi cho tới khi mở panel thủ công.

7. Bước 5 — Cấu hình SIP cho nhân viên

Có hai cách nạp cấu hình SIP (WSS URL, domain, username, password, display name):

Cách	Khi nào dùng
Nhân viên tự nhập trên màn hình Settings của softphone	Triển khai nhỏ, mỗi người tự quản lý extension
Admin set sẵn qua Admin Panel (`alohubAdminConfig`)	Triển khai tập trung cho nhiều nhân viên

Sau khi nhập, bật Auto-login để softphone tự đăng ký SIP khi mở app. Trạng thái registered nghĩa là đã sẵn sàng gọi.

8. Bước 6 — Bật click-to-dial trên Record Page

Trường Phone native của Salesforce dùng link javascript: để kích hoạt click-to-dial. Org bật strict CSP (đa số org mới) sẽ chặn link này với lỗi:

Running the JavaScript URL violates the following Content Security Policy
directive 'script-src ...'. The action has been blocked.

Đây là giới hạn nền tảng — không có cấu hình nào "mở" được javascript: navigation trong Lightning Experience (CSP Trusted Sites chỉ thêm domain, không thêm 'unsafe-inline'). Giải pháp là dùng component alohubCallButton: render số điện thoại thành nút bấm thật, publish qua LMS tới softphone để quay số — không dùng javascript: nên miễn nhiễm CSP.

Cấu hình một lần cho mỗi object (áp dụng cho tất cả record của object đó):

Bước	Thao tác	Ghi chú
1	Mở record → ⚙️ → Edit Page	Vào Lightning App Builder
2	Kéo Alohub Call Button vào layout	Mục Custom components
3	Set Phone field API name	VD `Phone`, `MobilePhone`, `SuppliedPhone`
4	Save → Activation	Gán Org Default hoặc theo App/Profile

Component đã expose sẵn cho Lead, Contact, Account, Case, Opportunity. Lặp lại cho từng object cần dùng.

Lưu ý: Có thể giữ nguyên trường Phone native để xem/copy số, chỉ thêm Call Button bên cạnh để bấm gọi.

9. Bước 7 — Click-to-dial native qua Open CTI (tùy chọn)

Nếu org chưa bật strict CSP (còn 'unsafe-inline' trong script-src), click-to-dial trên trường Phone native vẫn hoạt động qua adapter Open CTI. Khai báo Call Center:

Trường	Giá trị
CTI Adapter URL	`/apex/alohubCtiBridge` (nên dùng URL tương đối)
Use CTI API	true

Quan trọng: Dùng URL tương đối /apex/alohubCtiBridge thay vì domain tuyệt đối. Hard-code domain Visualforce (vd ...vf.force.com) của org khác sẽ khiến Lightning không frame được adapter và báo Refused to frame. Sau đó gán user vào Call Center qua Setup → Call Centers → Manage Call Center Users.

10. Kiểm tra cuộc gọi ra

Mở DevTools Console, bấm gọi và đối chiếu log [Alohub] / [Alohub SIP]:

Log	Ý nghĩa
`handleCall {canCall: true, sipState: 'registered'}`	LMS + đăng ký SIP OK, bắt đầu gọi
`getUserMedia OK`	Micro đã cấp quyền (LWS hoạt động)
`progress (ringing)`	INVITE đã tới tổng đài, đang đổ chuông

Lưu ý về định dạng số: Click-to-dial gửi số nguyên trạng từ record (vd 0982483437). Nếu tổng đài trả 603 Decline, thường do định dạng số chưa đúng (cần bỏ số 0 đầu + thêm mã quốc gia, vd 84982483437, hoặc thêm prefix gọi ra ngoài). Hãy xác nhận định dạng tổng đài yêu cầu và cấu hình outsidePrefix cho phù hợp.

11. Khắc phục sự cố

Triệu chứng	Nguyên nhân	Cách xử lý
Click số native báo Running the JavaScript URL ... blocked	Strict CSP chặn `javascript:` navigation	Dùng Alohub Call Button (Bước 6); native không thể bypass bằng config
`Cannot read properties of undefined (reading 'getUserMedia')`	Locker Service không expose `navigator.mediaDevices`	Bật Lightning Web Security (Bước 2)
Bấm Call Button không phản hồi, không có log	Softphone chưa khởi tạo trên Utility Bar (lazy load)	Bật Start automatically cho utility item (Bước 4)
Refused to frame ...vf.force.com	Adapter URL hard-code domain sai	Đổi sang URL tương đối `/apex/alohubCtiBridge`
Refused to connect tới WSS	Domain WSS chưa có trong CSP Trusted Sites	Thêm Trusted Site, bật `connect-src` (Bước 3)
Gọi đổ chuông rồi `603 Decline`	Tổng đài từ chối: sai định dạng số hoặc thiếu quyền route outbound	Chuẩn hóa số (mã quốc gia/prefix); kiểm tra quyền outbound, caller ID, số dư trên PBX

Hỗ trợ

Cần thông số SIP hoặc hỗ trợ triển khai, liên hệ Alohub: https://alohub.vn/lien-he.