Introduction

Enreach Voice for Browser is a WebRTC phone client, which can be embedded to a webpage.

Example implementation serving as a test client is available here source code for the implementation is available here. It is not a guideline implementation or a model example how to embbed the WebRTC phone but a test client where developers can see how it works and explore different options and methods.

Embedding WebRTC phone

Take the webrtc-client-ui.js or webrtc-client-ui.min.js and embed it as a regular javascript file. It contains all necessary files, images, and icons, so it's only one file that you have to embed to your project. When in production you should use the minified version of the script file.

Place the WebRTC phone UI web component as any other HTML DOM element.

<script type="text/javascript" src="https://phone.enreachvoice.com/x.y.z/webrtc-client-ui.min.js"></script>

<webrtc-client-ui></webrtc-client-ui>

Versioning

Available client versions can be found in https://phone.enreachvoice.com/versions.html. For example version x.y.z can be accessed by adding script from https://phone.enreachvoice.com/x.y.z/webrtc-client-ui.min.js.

Release notes for the WebRTC phone are published here.

Requirements

WebRTC client UI requires few HTML API features that are not fully implemented in all of the browsers. Below you can find the list of HTML features that has to be enabled in browser to make WebRTC client UI work correctly.

Dependency	Can I use	Docs
HTMLMediaElement.setSinkId()	Link	Link
HTMLMediaElement.srcObject	Link	Link

Set PNPS mission type for user queries

Version 2024.3.0 and later.

You can specify PNPS mission type using pnps-mission-type attribute. This is for the PNPS queries WebRTC phone periodically asks from users through UI notifications.

Mission type determines the context for the queries which can have different questions depending on the type. Available values are default, standalone, d365 and salesforce. This is targeted for special use cases and doesn't need to be configured. The default is default if not set.

<webrtc-client-ui pnps-mission-type="salesforce"></webrtc-client-ui>

If you don't want WebRTC phone to periodically ask PNPS queries, you can disable it by using disable-pnps-query attribute.

<webrtc-client-ui disable-pnps-query></webrtc-client-ui>

Set client ID for SSO login

Version 1.8.0 and later.

If using SSO login method you can specify the embedding client via client-id attribute. The default is voice-for-browser if not set.

<webrtc-client-ui client-id="embdedding-system-name"></webrtc-client-ui>

Set discovery URL for testing/developing purposes

Version 2023.3.2 and later.

You ca specify discovery service for the authentication process using discovery-url attribute. This is mainly used for testing/development purposes with some test users. Doesn't need to be set if you aren't using some test setup. The default is https://discover.enreachvoice.com/api/user/ if not set.

<webrtc-client-ui discovery-url="https://discover.enreachvoice.com/api/user/"></webrtc-client-ui>

Authentication

To use WebRTC phone you have to authenticate in EnreachAPI or alternatively use a custom proxy between client and EnreachAPI. There are several ways to authenticate either through programmatic methods or using WebRTC phone's user interface. Check possible ways below,

Through user interface

The easiest way to authenticate and start using the phone is to provide username and password to the login form displayed in the phone UI. This is the default options and does not require use of any public methods exposed by the phone.

Using public method with credentials

webrtc.login({
  type: 'Credentials',
  username: 'user.name@example.com',
  password: 'UserPassword',
});

WebRTC phone allows programmatic login via public method as an alternative to authentication through UI. This is done by using the method called login() to supply username and password.

Detailed descriptions for all of the methods are documented in the Methods section.

Using public method with impersonation token

// Must have valid impersonation token
var token = GetImpersonationTokenFromSomewhere();
var userId = '134a4e3a-47dd-4e19-888f-6382add11f7f';
var username = 'user.name@example.com';

var authHeader = {
  value: 'Bearer ' + token.access_token,
  expiresIn: token.expires_in,
};

// You can hide login form in the UI by setting the authorization type to JWT
webrtc.setAuthType('JWT');

webrtc.login({ type: 'AuthHeader', authHeader, userId, username });

Authentication can also be done with impersonation token through the method called login() without the need for password. To use this option, an user-specific impersonation token must be aquired. Use it to supply JWT token, user id and email for authentication.

More information about impersonation in REST API documentation.

Token reneval

webrtc.addEventListener('auth-token-expired', () => {
  var token = GetImpersonationTokenFromSomewhere();

  webrtc.setAuthHeader({
    value: 'Bearer ' + token.access_token,
    expiresIn: token.expires_in,
  });
});

If authentication is done with impersonation token you will have to update the token manually. WebRTC phone will send an event 60 seconds before expiration called auth-token-expired which indicates that you should update the token as soon as possible. To update the token, use setAuthHeader() method.

Using Enreach Identity (aka. Modern Authentication)

webrtc.login({ type: 'SSO', username: 'user.name@example.com' });

Recommended option for authentication is to use SSO through Enreach Identity. You do this via login() method supplying only the username. Using this requires that the user has modern authentication enabled.

More information about Enreach Identity.

Methods

WebRTC client UI has exposed some public methods and events to be used outside the UI. Descriptions for all the available methods are below,

answerCall()

(callId: string): void

webrtc.answerCall('ahmh78im1qstcilmif6n');

Answer incoming call by giving its call id as a parameter.

Name	Type	Description
callId	string	Identifier for the call.

call()

(targetNumber: string, outboundServiceCallData?: OutboundServiceCallDataInterface): Promise

// Personal call
webrtc.call('+358293000988');

// Outbound service call
webrtc.call('+358293000988', {
  queueId: '05dd1655-5ff2-4612-93fa-2a2d1b19c925',
});

Start a phone call by giving the target phone number as a parameter. Optionally you can start an outbound service call (queue or callback call) by also providing the necessary ids. The method returns a promise with the call's id. The call id can also be found in the call events emitted by the phone.

Name	Type	Description	Version availability
targetNumber	string	Phone number where to call.	-
outboundServiceCallData	OutboundServiceCallDataInterface?	Optional. Override UI selected role for the call.	2024.3.0 and later

OutboundServiceCallDataInterface

Name	Type	Description
callbackListId	string?	Optional. Id of the callback list the call relates to.
callbackRequestId	string?	Optional. Id of the callback request the call relates to.
queueId	string?	Optional. Id of the queue the call relates to.
cli	string?	Optional. Calling Line Identification (CLI) number for the call.

callOutboundCallback()

(targetNumber: string, callbackListId: string, callbackRequestId: string, cli?: string): Promise

DEPRICATED: Recommended to use call() method with optional data object

Version 2024.2.0 and later.

webrtc.callOutboundCallback(
  '+358293000988',
  '78c79e79-32c7-4a76-9513-6fc5ca0227d6',
  'a014b3ba-1569-4798-b699-98b9601fe291',
);

Start an outbound service call instead of personal call on behalf of a callback list by providing ids related to the callback. The method returns a promise with the call's id.

Name	Type	Description
targetNumber	string	Phone number where to call the service call.
callbackListId	string	Id of the callback list the call relates to.
callbackRequestId	string	Id of the callback request the call relates to.
cli	string?	Optional. Calling Line Identification (CLI) number for the call.

callOutboundQueue()

(targetNumber: string, queueId: string, cli?: string): Promise

DEPRICATED: Recommended to use call() method with optional data object

Version 2024.2.0 and later.

webrtc.callOutboundCallback(
  '+358293000988',
  '05dd1655-5ff2-4612-93fa-2a2d1b19c925',
);

Start an outbound service call (queue) instead of personal call on behalf of a queue by providing the queue id. The method returns a promise with the call's id.

Name	Type	Description
targetNumber	string	Phone number where to call the service call.
queueId	string	Id of the queue the call relates to.
cli	string?	Optional. Calling Line Identification (CLI) number for the call.

confirmTransfer()

(): Promise

Version 1.8.3 and later.

webrtc.confirmTransfer().then((data: CallTransferStateInterface) => {
  // You may choose to do something with the data
});

Confirm a consulted call transfer programmatically. Consulted transfers must be confirmed to end the consulted call and successfully complete the transfer. The method returns a promise containing following data,

Look also transferCall() method for additional info.

CallTransferStateInterface

Name	Type	Description	Example
callId	string	Identifier for the call that is being transferred.	'ahmh78im1qstcilmif6n'
confirmed	boolean	Indicates if transfer is completed from the UIs perspective.	true
transferredTo	string?	Optional. Phone number where the call was transferred to.	'+358293000988'

endCall()

(callId: string): void

Version 1.8.3 and later.

webrtc.endCall('ahmh78im1qstcilmif6n');

End ongoing call by giving its id as a parameter. Similar to rejectCall() method.

Name	Type	Description
callId	string	Identifier for the call.

getCallExtraData()

(): Promise

Version 2024.5.0 and later.

webrtc.getCallExtraData().then((dataList: CallExtraDataInterface[]) => {
  // You may choose to do something with the data
});

Get extra data regarding the ongoing basic call (not consulted call). Extra data can be data regarding e.g. call strong authentication. The method returns a promise containing following data in a list format,

CallExtraDataInterface

Name	Type	Description	Example
CallId	string	Identifier for the call.	'ahmh78im1qstcilmif6n'
ExtraDataType	CallExtraDataTypeEnum?	Type identifier for the extra data.	1
Keyword	string	Keyword for the data.	'AUTH.GivenName'
Value	string	Value for the data.	'John'

CallExtraDataTypeEnum

Name	Value	Description
StrongAuth	1	Strong authentication data.

getUserRole()

(): Promise

Version 2024.3.0 and later.

webrtc.getUserRole().then((data: PublicUserRoleInterface) => {
  // You may choose to do something with the data
});

Find out currently selected user role. Requires V2 outbound UI mode to be enabled to the user. Role changes can also be caught through public event named user-role-changed exposed by the phone. The method returns a promise containing following data,

PublicUserRoleInterface

Name	Type	Description	Example
Name	string	Name of the role i.e. service queue name or 'personal' for personal role.	'test queue'
Numbers	UserRoleNumberInterface[]	All available display numbers for the role.	[ UserRoleNumberInterface ]
SelectedNumber	UserRoleNumberInterface	Currently selected display number for the role.	{ Default: true, DisplayNumber: '+358293000988', DisplayName: 'test queue'}
QueueId	string?	Optional. Service queue identification for associated service role. Populated only if role is service role.	'05dd1655-5ff2-4612-93fa-2a2d1b19c925'
Recorded	boolean?	Optional. If calls are recorded.	false

UserRoleNumberInterface

Name	Type	Description	Example
Default	boolean	If the number is default for the role.	true
DisplayNumber	string	Display number.	'+358293000988'
DisplayName	string	Display name for the number.	'test queue'

getUserRoles()

(): Promise

Version 2025.2.0 and later.

webrtc.getUserRoles().then((data: PublicUserRoleInterface[]) => {
  // You may choose to do something with the data
});

Returns all roles available for the user to select. The method requires the outbound UI mode to be set to v2. It rejects with an error if the user is not logged in or if an unsupported UI mode is in use. If successful, it resolves to an array of PublicUserRoleInterface objects.

getUserStatus()

(): Promise

webrtc.getUserStatus().then((data: PublicUserStatusInterface) => {
  // You may choose to do something with the data
});

Find out current user availability status. Availability changes can also be caught through public event named user-status-changed exposed by the phone. The method returns a promise containing following data,

PublicUserStatusInterface

Name	Type	Description	Example
EndDate	string?	Optional. Availability event specified end date.	'2022-12-01T09:01:45.613Z'
EventSourceCategory	EventSourceCategoryEnum	Event source category name.	'User'
EventTypeID	AvailabilityEventTypeIdEnum	Event main type.	2
Id	string?	Optional. Identifier for the availability event.	'fc7536af-5471-ed11-993c-005056895f22'
Note	string	User defined event note.	'Some note'
PresenceTypeID	PresenceTypeIdEnum	Event presence type.	0
StartDate	string?	Optional. Availability event start date.	'2022-12-01T08:46:45.787Z'
Timestamp	string?	Optional. When event was last changed.	'2022-12-01T08:46:45.880Z'
TransferNumber	string?	Optional. Number where incoming calls should be transferred to.	'+358293000988'
WrapUpEnd	string?	Optional. Timestamp indicating when wrap-up ends automatically.	'2022-12-01T08:46:45.880Z'

login()

(options: LoginOptionsInterface)

Version 2024.5.1 and later.

// Credentials login with username and password
webrtc.login({
  type: 'Credentials',
  username: 'user.name@example.com',
  password: 'UserPassword',
});

// SSO login with just the username
webrtc.login({ type: 'SSO', username: 'user.name@example.com' });

Authenticate in EnreachAPI using one of the three authentication options described in the Authentication section. Currently, login needs to be done everytime page refreshes because refreshing the page logs out the user. The method returns an error if user has already signed in or required data is missing from the options object. Otherwise it will return true indicating successful login or an API error.

LoginOptionsInterface

Name	Type	Description
type	LoginTypeEnum	Indicates which of the supported login types is to be used. Login type determines which of the other fields are required or optional.
username	string?	User’s name/email. Required by all login types.
userId	string?	Optional. User’s identification. Required by AuthHeader login type.
authHeader	AuthHeaderInterface?	Optional. User’s authorization header. Required by AuthHeader login type.
password	string?	Optional. User’s password. Required by Credentials login type.
isInIframe	boolean?	Optional. Alters the behavior of the phone to better suit embedded scenarios. If true permissions page will not show if not forced and browser notifications are disabled. Defaults to false.
siloName	string?	Optional. User is signed in to the provided silo if possible.
keycloak	Keycloak?	Optional. Keycloak object to be used the sign in process. Allows the phone to sign in without reloading the page. The object must be authenticated before calling the method. Optional for SSO login type.

LoginTypeEnum

Name	Value	Description
Credentials	'Credentials'	Legacy authentication using username and password.
Authentication header	'AuthHeader'	Legacy authentication using authentication header.
Single sign-on	'SSO'	Modern authentication using SSO.

AuthHeaderInterface

Name	Type	Description
value	string	Token type and token value.
expiresIn	number	Validity time in seconds for impersonation token (have to be more than 60).

loginUsingAuthHeader()

(authHeader: AuthHeaderInterface, userId: string, username: string, isInIFrame?: boolean, siloName?: string): Promise

DEPRICATED: Recommended to use login() method with type 'AuthHeader'

// Must have valid impersonation token
var token = GetImpersonationTokenFromSomewhere();
var userId = '134a4e3a-47dd-4e19-888f-6382add11f7f';
var username = 'user.name@example.com';

var authHeader = {
  value: 'Bearer ' + token.access_token,
  expiresIn: token.expires_in,
};

webrtc.loginUsingAuthHeader(authHeader, userid, username);

Authenticate in EnreachAPI using the impersonation token. The method returns a promise containing boolean value indicating if user was logged in successfully.

Name	Type	Description	Version availability
authHeader	AuthHeaderInterface	Authentication header used in EnreachAPI requests.	-
userId	string	Identifier that will be used as user context for EnreachAPI requests.	-
username	string	User email, that will be attached to logs and used to make API discovery request.	-
isInIFrame	boolean?	Optional. Alters the behavior of the phone to better suit embedded scenarios. If true permissions page will not show if not forced and browser notifications are disabled. Defaults to true.	-
siloName	string?	Optional. Set specific silo name to which the user is logged into.	2024.4.1 and later

AuthHeaderInterface

Name	Type	Description
value	string	Token type and token value.
expiresIn	number	Validity time in seconds for impersonation token (have to be more than 60).

loginUsingSSO()

(username: string, isInIFrame?: boolean, keycloak?: Keycloak, siloName?: string): Promise

DEPRICATED: Recommended to use login() method with type 'SSO'

webrtc.loginUsingSSO('user.name@example.com');

Authenticate in EnreachAPI using the SSO through Enreach Identity. The method returns a promise containing boolean value indicating if user was logged in successfully. If SSO authentication is not set to the user, returned boolean will be false.

Name	Type	Description	Version availability
username	string	User email, that will be attached to logs and used to make API discovery request.	-
isInIFrame	boolean?	Optional. Alters the behavior of the phone to better suit embedded scenarios. If true permissions page will not show if not forced and browser notifications are disabled. Defaults to true.	-
keycloak	Keycloak?	Optional. Provide already authenticated Keycloak object. Otherwise, it's automatically created and authenticated.	2023.2.2 and later
siloName	string?	Optional. Set specific silo name to which the user is logged into.	2024.4.1 and later

loginUsingUsernameAndPassword()

(username: string, password: string, isInIFrame?: boolean, siloName?: string): Promise

DEPRICATED: Recommended to use login() method with type 'Credentials'

webrtc.loginUsingUsernameAndPassword('user.name@example.com', 'UserPassword');

Authenticate in EnreachAPI using user's username and password. The method returns a promise containing boolean value indicating if usre was logged in successfully.

Name	Type	Description	Version availability
username	string	User email, that will be attached to logs and used to make API discovery request.	-
password	string	User password.	-
isInIFrame	boolean?	Optional. Alters the behavior of the phone to better suit embedded scenarios. If true permissions page will not show if not forced and browser notifications are disabled. Defaults to false.	-
siloName	string?	Optional. Set specific silo name to which the user is logged into.	2024.4.1 and later

logout()

(force?: boolean): void

webrtc.logout(true);

Sign out from the phone.

Name	Type	Description	Version availability
force	boolean?	If set to true, user is signed out without alert prompt notifying user of page reload. Defaults to false.	2024.3.0 and later.

makeAPICall()

(method: APICallTypeEnum, relativePath: string, payload?: object): Promise

webrtc
  .makeAPICall('GET', 'users/[me]/availability/current')
  .then((res: any) => {
    // You may choose to do something with the response
  });

Make API calls programmatically using WebRTC phone as a proxy. The method returns an error if user is not signed in or used unsupported HTTP method. Otherwise, a promise containing API response is returned.

Name	Type	Description
method	APICallTypeEnum	Used HTTP method.
relativePath	string	Used resource path. It can include '[ME]' (case-insensitive) placeholder which will be raplaced by users own id.
payload	object?	Optional. Payload for the request.

APICallTypeEnum

Name	Value	Description
GET	'GET'	GET request.
POST	'POST'	POST request.
PUT	'PUT'	PUT request.
DELETE	'DELETE'	DELETE request.

muteCall()

(callId: string): void

Version 1.8.3 and later.

webrtc.muteCall('ahmh78im1qstcilmif6n');

Mute ongoing call by giving its id as a parameter.

Name	Type	Description
callId	string	Identifier for the call.

pauseCall()

(callId: string): void

Version 1.8.3 and later.

webrtc.pauseCall('ahmh78im1qstcilmif6n');

Put ongoing call on hold by giving its id as a parameter.

Name	Type	Description
callId	string	Identifier for the call.

rejectCall()

(callId: string): void

webrtc.rejectCall('ahmh78im1qstcilmif6n');

Reject incoming call by giving its id as a parameter. Similar to endCall() method.

Name	Type	Description
callId	string	Identifier for the call.

resumeCall()

(callId: string): void

Version 1.8.3 and later.

webrtc.resumeCall('ahmh78im1qstcilmif6n');

Resume the call put on hold by giving its id as a parameter.

Name	Type	Description
callId	string	Identifier for the call.

setAudioHandling()

(type: AudioHandlingEnum): Promise

Version 2023.2.6 and later.

webrtc.setAudioHandling('legacy');

Select between legacy or default audio handling. Can be used before or after login. The method returns a promise containing boolean value true when the process is complete.

Legacy audio handling keeps audio streams always open while default audio handling closes them when not needed. Version 2023.3.2 onwards audio handing can also be selected from phone UI and this will override programmatical audio handling changing. If user has chosen audio handling mode via UI this method gives an error informing that mode cannot be changed because of user value.

Name	Type	Description
type	AudioHandlingEnum	Type of audio handling used. Defaults to 'default'

AudioHandlingEnum

Name	Value	Description
Default	'default'	Audio streams are closed when not used.
Legacy	'legacy'	Audio streams are always open.

setAuthHeader()

(authHeader: AuthHeaderInterface): void

// Must have valid impersonation token
var token = GetImpersonationTokenFromSomewhere();

var authHeader = {
  value: 'Bearer ' + token.access_token,
  expiresIn: token.expires_in,
};

webrtc.setAuthHeader(authHeader);

Update authorization header.

Name	Type	Description
authHeader	AuthHeaderInterface	Authentication header used in API requests.

AuthHeaderInterface

Name	Type	Description
value	string	Token type and token value.
expiresIn	number	Validity time in seconds for impersonation token (have to be more than 60).

setAuthType()

(authType: AuthTypeEnum): void

webrtc.setAuthType('JWT');

Set authorization type. Currently only changes login form into welcome screen in UI when type set to 'JWT'.

Name	Type	Description
authType	AuthTypeEnum	Type of authentication method. Defaults to 'loginForm'.

AuthTypeEnum

Name	Value	Description
Login form in UI	'loginForm'	Audio streams are closed when not used.
Impersonation token	'JWT'	Audio streams are always open.

setClientId()

(id: string): Promise

webrtc.setClientId('voice-for-browser');

Set client id for SSO login. If not set the default value will be voice-for-browser. The mehod returns a promise containing boolean value true when the process is done.

Name	Type	Description
id	string	Identification for embedded phone when using SSO login method.

setDiscoveryUrl()

(url: string): Promise

Version 2023.3.2 and later.

webrtc.setDiscoveryUrl('https://discover.enreachvoice.com/api/user/');

Set discovery service for authentication process. This is mainly used for development purposes to login with test users. Doesn't need to be set if you aren't using some test setup with test users. The mehod returns a promise containing boolean value true when the process is done.

Name	Type	Description
url	string	Address for the used discovery service.

setPNPSMissionType()

(type: PNPSMissionTypeEnum): void

Version 2024.3.0 and later.

webrtc.setPNPSMissionType('salesforce');

Set PNPS mission type for PNPS queries. Type can also be configured with pnps-mission-type HTML attribute (check the Introduction section). PNPS mission type must be set before login.

Name	Type	Description
type	PNPSMissionTypeEnum	Set mission type for PNPS query. Defaults to 'default'.

PNPSMissionTypeEnum

Name	Value	Description
Default	'default'	Default PNPS queries.
Standalone	'standalone'	Standalone specific PNPS queries.
Salesforce	'salesforce'	Salesforce specific PNPS queries.
Dynamics 365	'd365'	Dynamics 365 specific PNPS queries.

setPhoneAlerts()

(value: boolean): void

Version 1.8.3 and later.

webrtc.setPhoneAlerts(false);

Set phone alerts i.e. ringtone on or off.

Name	Type	Description
value	boolean	Determines if phone alerts are to be used. Defaults to true.

setPhoneLanguage()

(lang: string): void

webrtc.setPhoneLanguage('fi');

Set phone language by giving language code as a parameter. Currently supported languages and their corresponding codes can be found in the table below,

Name	Value	Version availability
English	'en'	All versions
Spanish	'es'	Version 2025.2.0 and later
Finnish	'fi'	All versions
Swedish	'sv'	All versions
Dutch	'nl'	Version 2023.3.0 and later

Name	Type	Description
lang	string	Language code. Defaults to 'en'.

setUserData()

(data: object): Promise

webrtc.setUserData({ WorkSpaceId: '928374912321' });

Set custom data to be used in call transfers. In case of consulted transfers, data must be set before consultation call is started. The custom data can be found in the detail property of the call event when receiving a call.

Name	Type	Description
data	object	Data object sent with the call data to the recipient of the transfer. Data length must be under 491 characters in serialized string format.

setUserRole()

(queueId?: string, number?: string): Promise

Version 2024.3.0 and later.

// Sets the default role with default number
webrtc.setUserRole();

// Set specific service role with its default number
webrtc.setUserRole('05dd1655-5ff2-4612-93fa-2a2d1b19c925');

// Set specific service role with specific display number
webrtc.setUserRole('05dd1655-5ff2-4612-93fa-2a2d1b19c925', '+358293000988');

Set user role when using V2 outbound UI mode. Leaving both parameters undefined will select default role with default number for the user. Specifying only queueId will select the corresponding service role with the default number for the role. Specifying only number will choose personal role with the given number. Returns a Promise with boolean value indicating whether the role change was successful (true) or not (false). If specified values for queueId or number are invalid, role is not changed. Role changes are notified by events sent by WebRTC phone.

Name	Type	Description
queueId	string?	Optional. Queue identification which determines service role.
number	string?	Optional. Display number to be used.

startCallSupervision()

(targetUserId: string): Promise

Version 2025.1.0 and later.

webrtc
  .startCallSupervision('17fd100e-7f80-e911-80d4-00505689257e')
  .then((result: boolean) => {
  // You may choose to do something with the result
});

Starts a call supervision session for the target user by checking if the user is logged in, no call is in progress, and a targetUserId is provided. The method rejects with an error if any validation fails or an API error occurs, and resolves to true if the session starts successfully.

Name	Type	Description	Example	Version availability
targetUserId	string	The ID of the user to start call supervision for.	'17fd100e-7f80-e911-80d4-00505689257e'	2025.1.0 and later

sendDTMF()

(callId: string, tones: string, options?: JsSIPDTMFRequestOptions): Promise

Version 2025.3.0 and later.

webrtc
  .sendDTMF('ahmh78im1qstcilmif6n', '1234#', { duration: 50, interToneGap: 50 })
  .then((result: boolean) => {
  // You may choose to do something with the result
});

Sends DTMF signals during an active call by checking if the user is logged in, call exists, and the provided call id, tones, and DTMF options are valid. The method rejects with an error if any validation fails or an error occurs during the DTMF sending process, and resolves to true if the DTMF tones are sent successfully.

Name	Type	Description	Example	Version availability
callId	string	Identifier for the call.	'ahmh78im1qstcilmif6n'	2025.3.0 and later
tones	string	The DTMF tones to be sent in the call. Should only contain valid characters [0-9, A-D, #, *, and ,].	'1234#'	2025.3.0 and later
options	JsSIPDTMFRequestOptions?	Optional. Optional settings for DTMF transmission, such as duration and interToneGap. Defaults to { duration: 160, interToneGap: 1200 }.	{ duration: 100, interToneGap: 50 }	2025.3.0 and later

JsSIPDTMFRequestOptions

Name	Type	Description
duration	number	The duration of each DTMF tone in milliseconds. The valid range is from 40 to 6000 milliseconds.
interToneGap	number	The gap between consecutive DTMF tones in milliseconds. The minimum valid value is 30 milliseconds.

startCallRecording()

(callId: string): void

Version 1.8.3 and later.

webrtc.startCallRecording('ahmh78im1qstcilmif6n');

Start call recording by giving call id as a parameter.

Name	Type	Description
callId	string	Identifier for the call.

stopCallRecording()

(callId: string): void

Version 1.8.3 and later.

webrtc.stopCallRecording('ahmh78im1qstcilmif6n');

Stop call recording by giving call id as a parameter.

Name	Type	Description
callId	string	Identifier for the call.

transferCall()

(transferType: TransferTypeEnum, transferToNumber: string): Promise

Version 1.8.3 and later.

// Transfer ongoing call immediately
webrtc
  .transferCall('direct', '+358293000988')
  .then((data: CallTransferStateInterface) => {
    // You may choose to do something with the data
  });

// Make consulted call before transferring the ongoing call
webrtc
  .transferCall('consulted', '+358293000988')
  .then((data: CallTransferStateInterface) => {
    // You may choose to do something with the data
  });
// When you want to connect the consultation call and ongoing call, envoke confirm method
webrtc.confirmTransfer().then((data: CallTransferStateInterface) => {
  // You may choose to do something with the data
});

Start direct or consulted transfer for ongoing call.

Direct transfers end the ongoing call and transfers it to the provided phone number. Consulted transfers puts the ongoing call on hold and creates a consulted call before making the actual transfer. When you want to connect the consulted call and the ongoing 'basic' call you can do it through UI button or public method called confirmTransfer().

Name	Type	Description
transferType	TransferTypeEnum	Type of call transfer.
transferToNumber	string	Phone number where to transfer the call either directly or after consulted call. In the case of consulted transfer this is the number where to make the consultation call.

TransferTypeEnum

Name	Value
Direct transfer	'direct'
Consulted call	'consulted'

The method returns a promise containing following status data for the transfer,

CallTransferStateInterface

Name	Type	Description	Example
callId	string	Identifier for the call that is being transferred.	'ahmh78im1qstcilmif6n'
confirmed	boolean	Indicates if transfer is completed from the UIs perspective.	true
transferredTo	string?	Optional. Phone number where the call was transferred to.	'+358293000988'

unmuteCall()

(callId: string): void

Version 1.8.3 and later.

webrtc.unmuteCall('ahmh78im1qstcilmif6n');

Unmute ongoing call by giving its id as a parameter.

Name	Type	Description
callId	string	Identifier for the call.

updateBeneUiUrl()

(url: string): void

webrtc.updateBeneUiUrl(
  'https://benedesk-qa.beneservices.com/Account/LogOn/?un=user@company.com',
);

Set UI endpoint. Internally, the passed URL is parsed using this.

Name	Type	Description
url	string	New UI endpoint.

updateJWT()

(token: string): void

// Must get valid JWT for WebRTC connection from Enreach API
var token = GetJWTFromAPI();

webrtc.updateJWT(token);

SDK JWT has validity period and sometimes you will have to renew the token manually. In such case, you can use this method to update the token inside WebRTC phone's SDK.

Name	Type	Description
token	string	New JWT token for SDK.

Events

WebRTC client UI emits events that you can listen to and then trigger your own custom actions. All events are instances of CustomEvent that comes from LitElement. Below you can find the descriptions of the events,

init

webrtc.addEventListener('init', () => {
  // You may choose to do something here
  // You can change language or audio handling with the methods

  webrtc.login({ type: 'SSO', username: 'user.name@example.com' });
});

Emitted after the app is initialized, before authentication. It's the best event that you can use to log in the user.

logged-in

webrtc.addEventListener('logged-in', () => {
  // You may choose to do something here
});

Emitted after a user has successfully logged in.

auth-token-expired

webrtc.addEventListener('auth-token-expired', () => {
  var token = GetImpersonationTokenFromSomewhere();

  webrtc.setAuthHeader({
    value: 'Bearer ' + token.access_token,
    expiresIn: token.expires_in,
  });
});

Emitted 60 seconds before impersonation token expires. This should give enough time to update the token before it's invalidated. Renewing the token is a manual step only if the user is logged in using impersonation method (check the Authentication section). The update should be done via setAuthHeader() method.

If the token is expired, WebRTC phone starts sending the event again in response to failed API requests. The event will be invoked at most in 2 second intervals to mitigate spam.

phone-error

Version 2023.3.2 and later.

webrtc.addEventListener('phone-error', (e) => {
  // You may choose to do something here
});

Emitted if an error occurs in WebRTC phone that needs to be exposed outside.

Payload for the event can be found in detail property of the CustomEvent. In the property, there is the name of the error occured. Below is descriptions for the possible errors tied to this event,

Name	Description	Version availability
user-click-needed	WebRTC phone cannot play audio (ringtone) when a call comes in. User needs to click the document (phone) to make it active in order to give browser permission to play audio.	2023.3.2 and later
user-click-resolved	When use-click-needed issue is resolved i.e. user clicks the document this event is emitted and it indicates that issue is no longer in effect.	2023.3.2 and later
connection-lost	WebRTC phone lost connection to the servers and no phone calls can be made or received. After the event phone tries actively restore the connection.	2024.4.1 and later
connection-failed	When WebRTC phone stops actively trying to restore connection to the servers this event is emitted and it indicates that you should restart the phone.	2024.4.1 and later
connection-restored	When WebRTC phone reconnects to the servers this evetn is emitted and it indicates that you can continue to use the phone normally.	2024.4.1 and later

restart-phone

webrtc.addEventListener('restart-phone', () => {
  // You may choose to do something here
  // Essentially you have to reload the page and log in again
});

Emitted if the connection to backend fails and it cannot be reconnected.

Call related events

webrtc.addEventListener('call-started', (e) => {
  // You may choose to do something with the data
});

webrtc.addEventListener('call-incoming', (e) => {
  // You may choose to do something with the data
});

webrtc.addEventListener('call-ended', (e) => {
  // You may choose to do something with the data
});

Call events is a group of events that are strictly related to calling process.

Event type	Description
call-started	Emitted right after call is started in WebRTC phone.
call-in-progress	Emitted when an outgoing call is acknowledged by the backend to be ongoing.
call-incoming	Emitted right after call is received by WebRTC phone.
call-answered	Emitted right after incoming call is answered in WebRTC phone.
call-confirmed	Emitted right after incoming or outbound call is confirmed.
call-ended	Emitted right after incoming or outbound call ends.
call-paused	Emitted right after call is put on hold by WebRTC phone.
call-resumed	Emitted when call on hold is resumed by WebRTC phone.
call-muted	Emitted right after call is muted by WebRTC phone.
call-unmuted	Emitted when muted call is unmuted by WebRTC phone.
call-transfer-started	Emitted right after direct transfer or consultation call starts. This is currently the only call transfer event direct transfers emit.
call-transfer-cancel	Emitted when consultation call ends and the transfer wasn't confirmed/completed.
call-transfer-success	Emitted when consultation call ends and the call was transfered successfully.

Each event in the group contains the same payload. The payload object can be found in detail property of CustomEvent and it is as follows,

Name	Type	Description	Example
callId	string	Identifier for the call given by FreeSwitch.	'ahmh78im1qstcilmif6n'
callDirection	CallTypeEnum	Indicates call direction. Value is either 'incoming' or 'outbound'.	'incoming'
phoneNumber	string	Phone number of the interlocutor.	'+358293093803'
startTime	Date	Date and time when call started.	Thu Mar 05 2020 12:30:39 GMT+0100 (Central European Standard Time) {}
isConsulted	boolean	Indicates if the call is consultation or basic call.	false
endTime	Date?	Optional. Date and time when call ends. Defined only for ended calls.	Thu Mar 05 2020 12:30:39 GMT+0100 (Central European Standard Time) {}
queueArrivalTime	string?	Optional. UTC timestamp when the user entered the last queue before being answered. Defined only for service calls.	'2025-02-10T16:17:19.268Z'
queueId	string?	Optional. Queue identifier. Defined only for service calls.	'17fd100e-7f80-e911-80d4-00505689257e'
queueName	string?	Optional. Queue name. Defined only for service calls.	'queue name'
transferredTo	string?	Optional. Phone number where call was transferred. Defined only for transferred calls.	'+358293093804'
userData	object?	Optional. Custom field used in call transfers to send additional data.	{ 'WorkspaceId': '928374912321' }
wrapUpDuration	string?	Optional. Wrap-up time in seconds after call ends.	"60"

user-status-changed

webrtc.addEventListener('user-status-changed', (e) => {
  // You may choose to do something with the data
});

Emitted after users current availability or wrap-up status changes.

Payload for the event can be found in detail property of the CustomEvent. Data object is descibed below and it's the same what getUserStatus() method returns,

PublicUserStatusInterface

Name	Type	Description	Example
EndDate	string?	Optional. Availability event specified end date.	'2022-12-01T09:01:45.613Z'
EventSourceCategory	EventSourceCategoryEnum	Event source category name.	'User'
EventTypeID	AvailabilityEventTypeIdEnum	Event main type.	2
Id	string?	Optional. Identifier for the availability event.	'fc7536af-5471-ed11-993c-005056895f22'
Note	string	User defined event note.	'Some note'
PresenceTypeID	PresenceTypeIdEnum	Event presence type.	0
StartDate	string?	Optional. Availability event start date.	'2022-12-01T08:46:45.787Z'
Timestamp	string?	Optional. When event was last changed.	'2022-12-01T08:46:45.880Z'
TransferNumber	string?	Optional. Number where incoming calls should be transferred to.	'+358293000988'
WrapUpEnd	string?	Optional. Timestamp indicating when wrap-up ends automatically.	'2022-12-01T08:46:45.880Z'

user-role-changed

Version 2024.3.0 and later.

webrtc.addEventListener('user-role-changed', (e) => {
  // You may choose to do something with the data
});

Emitted after users current role changes. Requires V2 outbound UI mode to be enabled for the user.

Payload for the event can be found in detail property of the CustomEvent. Data object is descibed below and it's the same what getUserRole() method returns,

PublicUserRoleInterface

Name	Type	Description	Example
Name	string	Name of the role i.e. service queue name or 'personal' for personal role.	'test queue'
Numbers	UserRoleNumberInterface[]	All available display numbers for the role.	[ UserRoleNumberInterface ]
SelectedNumber	UserRoleNumberInterface	Currently selected display number for the role.	{ Default: true, DisplayNumber: '+358293000988', DisplayName: 'test queue'}
QueueId	string?	Optional. Service queue identification for assosiated service role. Populated only if role is service role.	'05dd1655-5ff2-4612-93fa-2a2d1b19c925'
Recorded	boolean?	Optional. If the call is recorded.	false

UserRoleNumberInterface

Name	Type	Description	Example
Default	boolean	If the number is default for the role.	true
DisplayNumber	string	Display number.	'+358293000988'
DisplayName	string	Display name for the number.	'test queue'

call-supervising-state-changed

Version 2025.1.0 and later.

webrtc.addEventListener('call-supervising-state-changed', (e) => {
  // You may choose to do something with the data
});

Emitted when the call supervision state changes. The detail property of the CustomEvent contains a CallSupervisingInterface object with the updated state and targetUserId.

CallSupervisingInterface

Name	Type	Description	Example	Version availability
state	CallSupervisingStateEnum	The current state of call supervision. Possible values: connecting, started, ended, failed.	'started'	2025.1.0 and later
targetUserId	string	The ID of the user being supervised.	'17fd100e-7f80-e911-80d4-00505689257e'	2025.1.0 and later