@expertflow/sdk-for-customer-facing-channels

SDK for Customer Facing Channels

This SDK is used for embedding customer-facing channel capabilities in a mobile-app (native, hybrid) or a web-app. Developers can use their own user interface on a Web or any Native-App. Learn more about the products we build at Expertflow CX

SDK Capabilities

With this SDK, the developer can enable the customer to:

• Start and End Chat.
• Make an audio or a video call via WebRTC
• Receive system events and notifications and deliver necessary information to the customer
• Send and Receive delivery notifications
• Send and Receive all of the supported chat messages including rich-media messages
• Enable call controls in the customer app for audio and video calls
• Get contact center stats ROADMAP
• Contact center available timings ROADMAP
• Get to know the availability of agents before initiating a request ROADMAP
• Get to know expected waiting time ROADMAP

Get Started

Dependencies

Add the following custom library to your project.

Name	Description
config.js	All the required configurations related to Chat, Audio and Video Calls from client app should be in this file.

Pre-requisites

Make sure you have access to the Unified Admin Panel of the Expertflow CX. The following configurations are needs to be added in the Web Widget Settings.

Configuration Properties

Update config file

Make sure to pass following configurations from config file to SDK

Properties	Explanation	Sample Value
widgetIdentifier	String value required to get widget configurations.	widgetIdentifier = "Web"
serviceIdentifier	String value required to get channel manager details	serviceIdentifier = "5155"
socketUrl	String value of web channel manager IP or FQDN	socketUrl = "https://<public_ip>"
fileServerUrl	String value of file server engine IP or FQDN	fileServerUrl = "https://<public_ip>"
ccmUrl	String value of customer channel manager IP or FQDN	ccmUrl = "https://<public_ip>"
transcriptUrl	String value of chat transcript IP or FQDN	transcriptUrl = "https://<public_ip>"
authenticator_url	String value required to get secure link IP or FQDN.	authenticator_url = "https://<public_ip>"
channel_identifier	String value required to push data as customer identifer.	channel_identifier = "phone"
channel	String value required to check client device info.	channel = "Mobile"

🔧 Widget Configuration (Chat + WebRTC)

Make sure you have access to Unified Admin Panel of the Expertflow CX. The Following configurations are needs to be added in the Web Widget Settings.

Property	Description	Example Value
widgetIdentifier	Widget platform name	Web
theme	Primary theme color for the widget	#2889e9
title	Main title on widget	Expertflow
subTitle	Subtitle under the main title	Cx
enableFontResize	Allow font resizing in widget	true
enableEmoji	Enable emoji picker	true
enableFileTransfer	Allow file sharing	true
enableDynamicLink	Enable rich link previews	true
enableDownloadTranscript	Allow users to download chat transcript	true
customerReconnectTime	Session reconnect timeout (0 = no reconnect)	0
language.code	Default language code	en
form	Pre-chat form ID	67e639de74315a03beb7b06f

📞 WebRTC Configuration

Property	Description	Example Value
webRtc.enableWebRtc	Enable/disable WebRTC feature	true
webRtc.diallingUri	EF switch DN used for dialling	369852
webRtc.sipExtension	SIP extension number	1001
webRtc.enabledSipLogs	Enable SIP debug logs	true
webRtc.extensionPassword	SIP extension password	supersecurepassword
webRtc.channel	Channel type	web
webRtc.websocket	WebSocket protocol prefix	ws
webRtc.wssFs	WebSocket IP/FQDN of EFswitch	192.168.1.201
webRtc.uriFs	WebRTC (WSS) port	7443
webRtc.iceServers	Array of ICE server URLs	[{"urls": ["stun:stun.l.google.com:19302", "stun:stun1.l.google.com:19302"]}]

📞 Optional Callback & Webhook Configs

Property	Description	Example Value
callback.enableCallback	Enable/disable callback functionality	false
callback.callbackUrl	Callback API URL	``
callback.campaignId	Campaign ID	0
callback.allowDuplicate	Allow duplicate requests	``
callback.callBackForm	Form ID used for callback	``
callback.standaloneCallback	Standalone callback flag	false
webhook.enableWebhook	Enable webhook for notifications	false
webhook.webhookUrl	Webhook receiver URL	``

📲 In-App Customer Channels via Expertflow SDK

Easily integrate In-App Chat, Voice, and Video Calling into your web application using Expertflow CX SDK — available via CDN or by directly importing the SDK into your project assets.

---

🌐 Web Application SDK (Recommended)

Expertflow fully supports integration via CDN or by adding the SDK files directly to your application's assets folder.

✅ Option 1: Include via CDN

Add one of the following <script> tags inside your HTML <head> to instantly enable the SDK:

• Standard CDN Script

<script src="https://cdn.jsdelivr.net/gh/expertflow/sdk-for-customer-facing-channels@latest/index.js"></script>

• Minified CDN Script

<script src="https://cdn.jsdelivr.net/gh/expertflow/sdk-for-customer-facing-channels@latest/index.min.js"></script>

✅ Option 2: Include via Local Assets

If you're working offline or prefer bundling locally:

• Download the SDK from the GitHub repository.
• Copy the SDK folder into your app's assets directory.
• Reference the SDK locally in your HTML file:

<script src="/assets/sdk/index.js"></script>

Here's a professional and visually appealing way to present this information in your README.md file using Markdown formatting:

Native Application Support (Beta) ⚠️

Important Notice
Native Mobile SDK support for Native Application is currently in beta and not recommended for production use until v4.8 is released.

Current Status

🟡 Beta Phase

• Limited support available
• Additional setup may be required
• Not production-ready

Installation (For Early Testing Only)

npm install @expertflow/sdk-for-customer-facing-channels

Recommendations

✅ For Production Use
We strongly recommend using our Web SDK (via CDN or static assets) for stable, production-ready implementations.

❌ For Native Application
Only use the Native SDK if you're willing to:

• Work with beta software
• Handle potential issues
• Make necessary custom configurations

Customer Data Payload
Here is the configuration object:

{
   serviceIdentifier : "2342342",
   channelCustomerIdentifier : "2342342342",
   browserDeviceInfo : {
     browserId : '123124',
     browserIdExpiryTime :  '9999',
     browserName : 'chrome',
     deviceType : 'desktop'
   },
   queue : '',
   locale : {
    timezone : 'asia/karachi',
    language : 'english',
    country : 'pakistan'
   },
   formData : {
     attributes : [{ 
       value : 'test',
       key : 'firstName',
       type : 'string'
     }, ...],
     createdOn : "Standard GMT DateTime",
     filledBy : "web-init",
     formId : "0.0313465461351",
     id : "0.1025556665461"
   }
}

All About SDK Chat Functions

S.No#	Function	Parameters	Sample Payload/Data	Sample Response
1	widgetConfigs(ccmUrl, widgetIdentifier, callback)	- ccmUrl → Customer Channel Manager Url. - widgetIdentifier → Widget Identifier. - callback → callback function with the response data.	ccmUrl → 'https://<public FQDN>' widgetIdentifier → 'Web' → case sensitive	{ id: "629dd96ac2fc5e06bf842c19", widgetIdentifier: "123123", theme: "yellow_theme", title: "Dummy widget", subTitle: "Call center", enableFontResize: true, enableEmoji: true, enableFileTransfer: true, enableDynamicLink: true, enableDownloadTranscript: true, customerReconnectTime: 100, language: { code: "en", policy: null }, webRtcConfig: { serverIp: "192.168.1.23", ... } }
2	establishConnection(socket_url,serviceIdentifier, channelCustomerIdentifier, callback)	- socket url for resume the existing connection or to start existing connection - serviceIdentifier → Service Identifier to identify the service in channel manager. - channelCustomerIdentifier → Customer Channel Identifier to identify the customer. - callback → Callback function with the response data.	-	In Callback Response socket returns an object { type: "SOCKET_CONNECTED", data: { socket connection details. } }
3	chatRequest(data)	- data → includes an object with type "CHAT_REQUEST" and customer information in data	{ type: "CHAT_REQUEST", data: { See Customer Data Section at the last for Payload } }	In Callback Response socket returns an object of channel session start { type: "CHANNEL_SESSION_STARTED", data: { channel session details. } }
4	sendMessage(data) For cimMessage Payload	- data → parameter includes message payload.	check cimMessage section for different messages payload.	In Callback Response socket returns an object { type: "MESSAGE_RECEIVED", data: { message details } }
5	chatEnd(data)	- data → parameter includes customer information.	check customer information payload	In Callback Response socket returns an object { type: "CHAT_ENDED", data: { end chat details } }
6	uploadToFileEngine(fileServerUrl, formData, callback)	- file server to upload file on server. -and form data to send on that file server - callback → function to call right after file upload.	{ file: "file name with ext", conversationId: random 5 digits number }	In Callback Response, Api returns an object { message: "File uploaded successfully", etag:"9109239e595cd2706c3b2180594351b6", name:"13318_developer.png", type:"image/png", size:52991 }
7	setConversationData(conversationUrl, conversationId, data)	- conversationId → Conversation Id received on chat session start. - conversationUrl → Conversation Manager Url - data → data includes any data in the form of key value pair e.g: form data.	-	-
8	getConversationData(conversationUrl, conversationId)	- conversationId → Conversation Id received on chat session start. - conversationUrl → Conversation Manager Url	-	-
9	getPreChatForm(formUrl, formId, callback)	- fomUrl → Unified Admin form Url - formId → Form Id Received in widgetConfigs response - callback → Call any function to render that form.	-	-

Chat Resume Scenarios

S.No#	Function	Parameters	Scenarios	Sample Response
1	establishConnection(socketurl,serviceIdentifier, channelCustomerIdentifier, callback)	- socket url for resume the existing connection or to start existing connection - serviceIdentifier → Service Identifier to identify the service in channel manager. - channelCustomerIdentifier → Customer Channel Identifier to identify the customer. - callback → Callback function with the response data.	On page refresh if you get SOCKET_CONNECTED event then you first need to check the local storage. If user information (serviceIdentifier, channelCustomerIdentifier) is stored in local storage that means the session already exists and you need to send a chat resume request with that information	{ "type": "SOCKET_CONNECTED", "data": { "socket connection details" } }
2	establishConnection(socketurl,serviceIdentifier, channelCustomerIdentifier, callback)	- socket url for resume the existing connection or to start existing connection - serviceIdentifier → Service Identifier to identify the service in channel manager. - channelCustomerIdentifier → Customer Channel Identifier to identify the customer. - callback → Callback function with the response data	If you receive a SOCKET_RECONNECTED event, you should call the chat resume function with user information (get that information from local storage or from anywhere you store that information)	-
3	resumeChat(data,callback)	- data contains --> serviceIdentifier → Service Identifier to identify the service in channel manager. --> channelCustomerIdentifier → Customer Channel Identifier to identify the customer. - callback → Callback function with the response data.	-	{ "isChatAvailable": true, "data": "previous chat data" }

Socket Event Listeners

On calling establish_connection( ) function → following Event Listeners are enabled during chat session and return an object in callback response.

S.No#	Socket Event Listener	Callback Response
1	connect	{ "type": "SOCKET_CONNECTED", "data": { "... socket details" } }
2	connect_error	{ "type": "CONNECT_ERROR", "data": { "... socket details" } }
3	disconnect	{ "type": "SOCKET_CONNECTED", "data": { "... socket details" } }
4	CHANNEL_SESSION_STARTED	{ "type": "CHANNEL_SESSION_STARTED", "data": { "... socket details" } }
5	MESSAGE_RECEIVED	{ "type": "MESSAGE_RECEIVED", "data": { "... socket details" } }
6	CHAT_ENDED	{ "type": "CHAT_ENDED", "data": { "... socket details" } }
7	ERRORS	{ "type": "ERRORS", "data": { "... socket details" } }

WebRTC SDK - Function & Event Overview

This section provides a comprehensive overview of the available WebRTC SDK functions, including their usage, parameters, sample code, related events, and descriptions.

Action	Parameters	Sample Usage	Related Events	Description
Register User	- event_callback: Function triggered on registration status.	registerUser(event_callback);	registered registrationFailed	Registers a user to enable WebRTC functionalities. Must be called before initiating any calls.
Initiate Call (Audio/Video)	- callType: 'audio' or 'video' - mediaStreamID: ID of the remote media stream (use '-' for mobile) - localMediaStreamID: ID of the local media stream (use '-' for mobile) - customerData: JSON object containing user details Example: js<br>let userData = {<br> first_name: 'John',<br> last_name: 'Doe',<br> email: '[e-mail]',<br> 'Customer-Caller-Id-number': '1234567890'<br>};<br>	sendInvite('audio', 'remoteAudio', '-', userData, event_callback);	Channel Creating session-accepted session-confirmed session-failed session-ended	Initiates an audio or video call. For mobile channels, pass '-' for media stream IDs.
Toggle Audio	None	audioControl();	None	Toggles the audio stream. If muted, it will unmute and vice versa. Currently supported on web channel only.
Toggle Video	None	videoControl();	None	Toggles the video stream. If paused, it will resume and vice versa. Currently supported on web channel only.
End Call	None	hangUp();	session-ended	Terminates the ongoing call session.
Unregister User	- event_callback: Function triggered after unregistration.	terminateCurrentSession(event_callback);	unregistered	Unregisters the user and terminates any existing sessions. Required before making a new call.

Event Received on Callback for WebRTC

All events are received in the callback function named event_callback(event). The sipcontrol.js looks for this function call if you have implemented it with event parameters.

In order to initiate a WebRTC audio or video call, users should be registered with EFswitch. When you call the Initiate Call (Audio/Video) command, it tries to register an agent and sends the respective callback.

S.No#	Event	Description	Payload
1	registered	If the user is successfully registered, this event is triggered.	{ "event": "registered", "response": {} }
2	registrationFailed	If the user is unable to register to EFswitch, this error event is triggered.	{ "event": "registrationFailed", "response": {} }
3	Channel Creating	When your call has started dialing DN.	{ "event": "Channel Creating", "response": {} }
4	session-accepted	When your call has been connected to the agent, this event is triggered.	{ "event": "session-accepted", "response": {} }
5	session-failed	If the call fails to connect to an agent, this event is triggered.	{ "event": "session-failed", "response": {} }
6	session-terminated	When the session is terminated, this event is triggered.	{ "event": "session-terminated", "response": {} }
7	session-confirmed	When the session is confirmed, this event is triggered.	{ "event": "session-confirmed", "response": {} }
8	session-ended	When the session is ended, this event is triggered.	{ "event": "session-ended", "response": {} }