Integrating Alohub Softphone into Salesforce — Step-by-Step Guide

This document guides the process of integrating Alohub's WebRTC softphone into a Salesforce org from start to making outbound/inbound calls in Lightning Experience. The focus is on practical configuration steps and common issues (CSP blocking click-to-dial, microphone not working, call being rejected) along with solutions.

Audience: Salesforce admin/developer deploying the package into the org. Requires Salesforce CLI ( sf), permissions to configure Session Settings, Call Center, Utility Bar, and Lightning App Builder.

1. Integration Architecture (summary)

The softphone runs as a Lightning Web Component ( alohubPhone) on Utility Bar , connecting SIP/WebRTC via JsSIP to Alohub's SIP server. An Open CTI bridge (Visualforce) and the Alohub Call Button component handle click-to-dial via Lightning Message Service (LMS).

Components	Type	Role in Integration
`alohubPhone`	LWC (Utility Bar)	Softphone interface, SIP registration, dialing, answering/calling
`alohubCallButton`	LWC (Record Page)	Call button on record — replaces native click-to-dial blocked by CSP
`alohubCtiBridge`	Visualforce	Open CTI Adapter: receives native click-to-dial, screen-pop for incoming calls
`CallMessageChannel`	Message Channel	LMS channel connecting bridge/Call Button ↔ softphone

2. Requirements Before Starting

Item	Requirement
SIP Account	WSS URL, SIP domain, username (extension), password — provided by Alohub
Browser	New Chrome/Edge, access org via HTTPS (My Domain), allow microphone
Admin Rights	Modify Session Settings, Call Center, Utility Bar, Lightning Record Page

Important: The SIP parameters are provided by Alohub specifically for each customer. Contact to receive: https://alohub.vn/lien-he .

3. Step 1 — Deploy the package into the org

Log into the org and deploy the source. For example with 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. Step 2 — Enable Lightning Web Security (required for microphone)

The softphone uses navigator.mediaDevices.getUserMediato access the microphone. Under Locker Service (old security mode), navigator.mediaDevices it cannot be exposed to LWC → call reports an error Cannot read properties of undefined (reading 'getUserMedia'). Lightning Web Security (LWS) fully exposes this API.

Go to Setup → Session Settings → enable "Use Lightning Web Security for Lightning web components and Aura components" → Save .

Warning: LWS is an org-wide change, which may affect other LWC/Aura components. Please enable and test on sandbox before applying to production.

Quick status check: open DevTools Console when the softphone is running, the media initialization log will print hasMediaDevices: trueif LWS has been exposed correctly.

5. Step 3 — Declare CSP Trusted Site for WSS

The SIP connection goes through WebSocket Secure (WSS). The WSS domain must be included in CSP Trusted Sites with connect-srcenabled, otherwise the browser will block the connection.

Field	Value
Endpoint URL	`wss://crm.alohub.vn:57445`(replace with WSS provided by Alohub)
Active	true
connect-src (CSP)	Enabled

Note: If Alohub provides a different WSS (e.g. wss://app.alohub.vn:57443), that domain must be added to Trusted Sites — otherwise, it will result in Refused to connect .

6. Step 4 — Add softphone to Utility Bar

Go to Setup → App Manager → select the Lightning App in use → Edit → Utility Items → Add Utility Item → select alohubPhone.

Important: Enable "Start automatically" (Load in background when app opens). The Utility Bar component is loaded lazily — if auto-start is not enabled, the softphone has not initialized so it cannot subscribe to the LMS channel , leading to click-to-dial from the record page having no response until the panel is manually opened.

7. Step 5 — Configure SIP for employees

There are two ways to load SIP configuration (WSS URL, domain, username, password, display name):

Method	When to use
Employees enter it themselves on the softphone Settings screen	Small deployment, each person manages their own extension
Admin pre-sets it via Admin Panel ( `alohubAdminConfig`)	Centralized deployment for multiple employees

After entering, enable Auto-login for the softphone to automatically register SIP when opening the app. The status registeredmeans it is ready to call.

8. Step 6 — Enable click-to-dial on Record Page

The Phone native field of Salesforce uses the link javascript:to activate click-to-dial. Org enabling strict CSP (most new orgs) will block this link with the error:

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

This is a platform limitation — there is no configuration that can "open" javascript:navigation in Lightning Experience (CSP Trusted Sites only adds the domain, not 'unsafe-inline'). The solution is to use the alohubCallButtoncomponent: render the phone number as a real button, publish via LMS to the softphone to dial — not using javascript:so it is immune to CSP.

Configure once for each object (applies to all records of that object):

Step	Action	Note
1	Open record → ⚙️ → Edit Page	Go to Lightning App Builder
2	Drag Alohub Call Button into the layout	Custom components section
3	Set Phone field API name	e.g. `Phone`, `MobilePhone`, `SuppliedPhone`
4	Save → Activation	Assign Org Default or by App/Profile

The component is already exposed for Lead, Contact, Account, Case, Opportunity . Repeat for each object needed.

Note: You can keep the native Phone field to view/copy the number, just add the Call Button next to it to make a call.

9. Step 7 — Native click-to-dial via Open CTI (optional)

If the org has not enabled strict CSP (still 'unsafe-inline'in script-src), click-to-dial on the native Phone field still works via the Open CTI adapter. Declare Call Center:

Field	Value
CTI Adapter URL	`/apex/alohubCtiBridge`(should use relative URL)
Use CTI API	true

Important: Use relative URL /apex/alohubCtiBridgeinstead of absolute domain. Hard-coding the Visualforce domain (e.g. ...vf.force.com) of another org will cause Lightning to not frame the adapter and report Refused to frame . Then assign the user to the Call Center via Setup → Call Centers → Manage Call Center Users.

10. Test Outbound Call

Open DevTools Console, click to call and compare the log [Alohub]/ [Alohub SIP]:

Log	Meaning
`handleCall {canCall: true, sipState: 'registered'}`	LMS + SIP registration OK, starting call
`getUserMedia OK`	Microphone has been granted permission (LWS functioning)
`progress (ringing)`	INVITE has reached the switchboard, ringing

Note on number format: Click-to-dial sends the number as is from the record (e.g. 0982483437). If the switchboard returns 603 Decline, usually due to incorrect number format (need to remove leading 0 + add country code, e.g. 84982483437, or add prefix for outbound calls). Please confirm the format required by the switchboard and configure outsidePrefixaccordingly.

11. Troubleshooting

Symptoms	Cause	Resolution
Clicking native number reports Running the JavaScript URL ... blocked	Strict CSP blocking `javascript:`navigation	Use Alohub Call Button (Step 6); native cannot be bypassed by config
`Cannot read properties of undefined (reading 'getUserMedia')`	Locker Service not exposing `navigator.mediaDevices`	Enable Lightning Web Security (Step 2)
Clicking Call Button has no response, no log	Softphone not initialized on Utility Bar (lazy load)	Enable Start automatically for the utility item (Step 4)
Refused to frame ...vf.force.com	Adapter URL hard-coded domain incorrect	Switch to relative URL `/apex/alohubCtiBridge`
Refused to connect to WSS	WSS domain not in CSP Trusted Sites	Add Trusted Site, enable `connect-src`(Step 3)
Call rings then `603 Decline`	Switchboard rejects: incorrect number format or lacks outbound route permission	Normalize the number (country code/prefix); check outbound permissions, caller ID, balance on PBX

Support

Need SIP parameters or deployment support, contact Alohub: https://alohub.vn/lien-he .