Mizu WebPhone
v.4.0. June
25, 2024
About 2
Usage. 2
Steps. 2
Web Softphone. 4
Click-to-call 4
Developers. 4
Designers. 4
Features, technology and licensing. 5
Feature list 5
Requirements. 6
Technical details. 6
Licensing. 8
Integration and customization. 9
Concepts. 10
User interface Skin/Design. 10
Web Dialer/Softphone. 12
Click to call 17
Custom solutions. 21
Integration with Web server side applications or scripts. 21
Integration with SIP server side applications or scripts. 23
Development 23
Parameters. 26
SIP account settings. 28
Engine related settings. 31
Call divert and other settings. 51
User interface related settings. 60
Parameter security. 69
JavaScript API 70
About 70
Basic example. 70
Functions. 71
Events. 84
FAQ.. 93
Resources. 162
The Mizu WebPhone is a universal
JavaScript SIP client library to provide VoIP capability for all browsers
using a variety of technologies compatible with most OS/browsers. Since it is
based on the open standard SIP and RTP
protocols, it can inter-operate with any other SIP-based network, allowing
people to make true VoIP calls directly from their browsers. Compatible with
all SIP softphones (X-Lite, Bria, Jitsi others), devices (gateways, ATA’s, IP
Phones, others), proxies (SER, OpenSIPS, others), PBX (Asterisk, FreeSWITCH, FreePBX, Elastix, Avaya, FusionPBX,
3CX, Broadsoft, Alcatel, NEC, others), VoIP servers (Mizu, Voipswitch, Cisco,
Huawei, Kamailio, others), service providers (Twilio, Vonage and others) and
any SIP capable endpoint (UAC, UAS, proxy, others).
The Mizu WebPhone is truly cross-platform,
running from both desktop and mobile browsers, offering the best browser to SIP
phone functionality in all circumstances, using a variety of built-in
technologies referred as “engines”:
·
NS (Native Service/Plugin)
·
WebRTC
·
Java applet
·
Flash
·
App
·
P2P/Callback
·
Native Dial
The engine to use is automatically
selected by default based on OS, browser and server availability (It can be
also set manually from the configuration or priorities can be changed). This multi-engine capability has considerable benefits over other naive implementations.
The webphone can be used with the
provided user interface (as a ready to use softphone or click to call
button) or as a JavaScript SIP library via its API.
The provided user interfaces are
implemented as simple HTML/CSS and can be fully customized, modified, extended or removed/replaced.
The webphone is an all-in-one VoIP
client module which can be used as-is (as a ready to use softphone or click to
call) or as a JavaScript SIP library (to implement any custom VoIP client or
add VoIP call capabilities to existing applications). You can create custom
VoIP solutions from scratch with some JavaScript knowledge or use it as a
turn-key solution if you don’t have any programming skills as the webphone is
highly customizable by just changing its numerous settings.
Download the webphone.zip and extract it to your web server (or test it from
your local file system by just launching it from your desktop for example).
Open the webphone_config.js file and configure at least the serveraddress
parameter.
Launch any of the example html included with the webphone, for example the
index.html as from there you can access most examples.
Enter your SIP username/password (if
you haven’t preconfigured it in the webphone_config.js) and call any
account/extension/phone number.
A quick tutorial can be found here
and/or you might follow the below step by step detailed instructions:
The package can be downloaded from
here: webphone download.
It includes everything you need for a
browser to SIP solution: the engines, the JavaScript API, the skins and also a
few usage examples.
This public downloadable version has
some demo
limitations, but you can use it for
any tests or integration work before to purchase your license.
If you already have a webphone license, then use the webphone package sent to you by
Mizutech instead of the above link.
You can find the requirements here, which needs to be fulfilled to be able to use the
webphone.
There is no any web server related
requirements. You can host the webphone on any web server the exact same way as you host a static page or a
png images.
Unzip and copy the webphone folder into your webserver and refer it from your html (for
example from your main page) or open one of the included html in your browsers
by specifying its exact URL.
For example:
http://192.168.1.44/webphone/samples/techdemo_example.html or https://yourdomain.com/webphone/softphone.html
.
Notes:
·
You might have to enable the .jar,
.exe, .zip, .swf, .dll, .so, .pkg, .dmg and .dylib mime types in your webserver if not enabled by default (these
files might be used in some circumstances depending on the client OS/browser).
·
If you wish to use (also) the
WebRTC engine then your site should be secured (HTTPS with a valid SSL
certificate). Modern browsers requires secure connection for both your website
(HTTPS) and websocket (WSS). If your website doesn’t have an SSL certificate
then we can host
the webphone for you for free or you can install a cheap or free certificate.
·
More details can be found here
·
Alternatives:
o
You can also test it without a
webserver by launching the html files from your desktop (launch from
local file system)
o
You can also test it by using the online demo
hosted by Mizutech website, but in this case you will not be able to change the
configuration (you can still set any parameters from the user interface or from
URL)
The webphone has a long list of parameters which you can set to
customize it after your needs.
You can set
these parameters multiple ways (in
the webphone_config.js file, pass by URL
parameter or via the setparameter() API).
If you are using the webphone with a
SIP server (not peer to peer) then you must set at least the “serveraddress” parameter. For more details read here.
The easiest way to start is to just
enter the required parameters (serveraddress, username, password and any other
you might wish) in the webphone_config.js file.
The webphone can be used as a turn-key
ready to use solution (just refer to it from your HTML) or as a Java-Script
library to develop custom software.
There are multiple ways to use it:
o
Use one of the supplied templates
(the “softphone” or the “click to call”) and customize it after your needs. You
can place one of them as an iframe or
div to your website
o
Integrate the webphone with
your webpage, website or web application
o
Integrate the webphone with your server side application (if
you are a server side developer)
o
Create your custom solution by using the webphone as a JavaScript SIP
library (if you are a JavaScript developer)
If you are a designer then you might
create your own design or
modify the existing HTML/CSS. For simple design changes you don’t need to be a
designer. Colors, branding, logo and others can be specified by the settings
for the supplied “softphone” and “click to call” skins.
Mizutech can also supply a ready to use
pre-customized build of the softphone skin with your settings and branding for
no extra cost (ask for it).
Please note that the webphone also
works without any GUI.
Launch one of the examples (the html
files in the webphone folder) or your own html (from desktop by double clicking
on it or from browser by entering the URL). You might launch the “index.html”
to see the included templates.
At first start the webphone might offer
to enable or download a native plugin if no other suitable engine are supported
and enabled by default in your browser.
It will also ask for a SIP
username/password if you use the default GUI and these are not preset.
On init, the webphone will register
(connect) to your VoIP server (this can be disabled if not needed by setting
the register parameter to 0).
Then you should be able to make calls
to other UA (any webphone or SIP endpoint such as X-Lite or other softphone) or
to pstn numbers (mobile/landline) if outbound call service is enabled by your
server or VoIP provider.
Examples and ready to use solutions
(found in the webphone folder):
·
index.html: just an index page with direct links to the
below examples for your convenience
·
minimal_example.html: shortest example capable to make a call
·
basic_example.html: a basic usage example
·
techdemo_example.html: a simple tech demo. You might make any tests
by using this html or change/extend it to fit your needs
·
softphone.html: a full featured, ready to use browser softphone. You can use it as is on your website as a web
dialer. For example you can include it in an iframe or div on your website.
Change the parameters in the webphone_config.js). You can further customize it
by changing the parameters or changing its design.
·
softphone_launch.html: a simple launcher for the above to look better
when launched directly (since the softphone.html is used usually in a DIV or
iFrame)
·
click2call.html: a ready to use browser to SIP click to call
solution. You might further customize
after your needs
·
custom: you can easily create any custom browser VoIP solution by using the webphone java
script SIP library
More details:
·
Webphone
file list
·
Customization
·
How it works?
·
Quick webphone tutorial
The webphone package contains a ready
to use web
softphone.
Just copy the webphone folder to your
webserver and change the “serveraddress” setting in the in webphone_config.js
file to your SIP server IP or domain to have a fully featured softphone
presented on your website. You can just simply include (refer to) the
softphone.html via an iframe
(this way you can even preset the webphone parameters in the iframe URL) div or
on demand.
Note: you might have to enable the
following mime types in your web server if not enabled by default: .jar, .swf,
.dll, .dylib, .so, .pkg, .dmg, .exe
The web softphone can be configured via
URL parameters or in the " webphone_config.js" file, which can be found in
the root directory of the package. The most important configuration is the
“serveraddress” parameter which should be set to your SIP server IP address or
domain name. More details about the parameters can be found below in this
documentation in the “Parameters”
section.
We can also send you a build with all
your branding and settings pre-set: contact us.
Check here for more options.
The webphone package contains a ready
to use click to call solution.
Just copy the whole webphone folder to
your website, set the parameters in the webphone_config.js file and use it from
the click2call.html.
Rewrite or modify after your needs with
your custom button image or you can just use it via a simple URI or link such
as:
http://www.yourwebsite.com/webphonedir/click2call.html?wp_serveraddress=YOURSIPDOMAIN&wp_username=USERNAME&wp_password=PASSWORD&wp_callto=CALLEDNUMBER&wp_autoaction=1
You can find more details and
customization options in the click to call
section.
Developers can use the webphone as a JavaScript SIP library
to create any custom VoIP solution integrated in any webpage or web
application.
Just include the " webphone_config.js" to your project or html and
start using the webphone
API.
See the development
section for the details.
Note: You can adjust the webphone
behavior also without any development knowledge by just modifying its settings
described in “parameters” section.
If you are a designer, you
can modify all the included HTML/CSS/images or create your own design from
scratch using any technology that can bind to JS such as HML5/CSS, Flash or
others.
For simple design changes you don’t
need to be a designer. Colors, branding, logo and others can be set by the
settings.
See the “User
Interface Skin/Design” section for
more details.
Note: If you are using the built-in
softphone or click2call skins, then you can adjust them also without any
designer knowledge by just setting/modifying the user interface
related settings in the
webphone_config.js file.
Features, technology and licensing
The WebPhone is a cross-platform
JavaScript SIP client library running entirely in clients browsers compatible
with all browsers and all SIP servers, IP-PBX or softswitch. The webphone is
completely self-hosted without any cloud dependencies, completely owned and
controlled by you (just copy the files to your Web server).
·
Standard SIP voice calls
(in/out), video, chat, conference and others (Session Initiation Protocol)
·
Maximum browsers compatibility.
Runs in all browsers with Java, WebRTC or native plugin support (WebView,
Chrome, Firefox, IE, Edge, Safari, Opera)
·
Includes several different
technologies to make phone calls (engines): WebRTC, NS (Native Service or
Plugin), Java applet, Flash, App, Native and server assisted conference rooms,
calls through IVR, P2P and callback
·
SIP and RTP stack compatible with
all standard VoIP servers and devices like Cisco, Voipswitch, Asterisk,
softphones, ATA, IP phones and others
·
Transport protocols: IPv4/IPv6,
UDP, TCP, HTTP, RTMP, websocket (uses UDP for media whenever possible)
·
Encryption: SIPS, TLS, DTLS, SRTP
and end to end encryption for webphone to webphone calls even if TLS/DTLS/SRTP
is not supported
·
NAT/Firewall support: auto detect
transport method (UDP/TCP/HTTP), stable SIP and RTP ports, keep-alive, rport
support, proxy traversal, auto tunneling when necessary, ICE/STUN/TURN
protocols and auto configuration, firewall traversal for corporate networks,
VoIP over HTTP/TCP when firewalls blocks the UDP ports with full support for
ICE TCP candidates
·
Works over the internet and also
on local LAN’s (perfectly fine to be used with your own internal company PBX)
·
RFC’s: 2543, 3261, 7118, 2976,
3892, 2778, 2779, 3428, 3265, 3515, 3311, 3911, 3581, 3842, 1889, 2327, 3550,
3960, 4028, 3824, 3966, 2663, 6544, 5245 and others
·
Supported methods: REGISTER,
INVITE, re-INVITE, ACK, PRACK, BYE, CANCEL, UPDATE, MESSAGE, INFO, OPTIONS,
SUBSCRIBE, NOTIFY, REFER
·
Audio Codec: G.711 (PCMU, PCMA),
G.729, GSM, iLBC, iSAC, SPEEX, OPUS (including wide-band HD audio)
·
Video codec: H.263, H.264, H.265,
VP8 and VP9 for WebRTC only
·
SIP compatible codec auto
negotiation and adjustment (for example OPUS – G.711, G.729 - wideband or RTC
G.711 to G.729 transcoding if needed)
·
Video calls and Screen-sharing
(for WebRTC enabled browsers)
·
Call divert: rewrite, redial,
mute, hold, transfer, forward, conference and other PBX features
·
Call park and pickup,
auto-answer, barge-in
·
Voice call recording
·
IM/Chat (RFC 3428), SMS, file
transfer, DTMF, voicemail (MWI)
·
Multi-line support
·
Multi account support
·
Contacts: management,
synchronization, flags, favorites, block, auto prioritization
·
Presence
(DND/online/offline/others) via standard SIP PUBLISH/SUBSCIBE/NOTIFY
·
BLF (Busy Lamp Field)
·
Balance display, call timer,
inbound/outbound calls, caller-id display
·
High level JavaScript API: web
developers can easily build any custom VoIP functionality using the webphone as
a JS SIP library
·
Stable API: new releases are
always backward compatible so you can always upgrade to new versions with no
changes in your code
·
Full control: perpetual life-time
license self-hosted as you wish
·
Integration with any website or
application including simple static pages, apps with client side code only
(like a simple static page) or any server side stack such as PHP, .NET, java
servlet, J2EE, Node.js and others (sign-up, CRM, callcenter, payments and
others)
·
Phone API accessible from any
JavaScript framework (such as AngularJS, React, jQuery and others) or from
plain/vanilla JS or not use the JS API at all
·
Branding and customization:
customizable user interface with your own brand, skins and languages (with
ready to use, modifiable themes)
·
Flexibility: all
parameters/behavior can be changed/controlled by URL parameters, preconfigured
parameters, from javascript or from server side
The webphone is in continuous development with multiple new releases
every year.
Only the major releases are published on the software homepage
as a demo
(usually once per year), but new customers always receive the latest stable
release.
All versions are fully backward/forward compatible, thus upgrades
doesn’t require any change in existing configurations and code.
For the major new versions you can find the change list here.
Server side:
·
Any web hosting for the
webphone files (any webserver is fine: IIS, nginx, Apache, NodeJS, Java,
others; any OS: Windows, Linux, others).
Chrome and Opera
requires secure connection for WebRTC engine to work (otherwise this engine
will be automatically skipped). We can also host the webphone for free if you
wish on secure http. Note that the web phone itself doesn’t require any
framework, just host it as static files (no PHP, .NET, JEE, NodeJS or similar
server side scripting is required to be supported by your webserver, however
you are free to integrate the webphone with any such server side stacks if you
need so)
·
At least one SIP account
at any VoIP
service provider or your own SIP server or IP-PBX (such as Asterisk, Voipswitch, 3CX,
FreePBX, Trixbox, Elastix, SER, Cisco and others)
·
Optional: WebRTC capable SIP
server or SIP to WebRTC gateway (Mizutech free WebRTC to SIP service is enabled
by default. The webphone can be used and works fine also without WebRTC, however if you prefer this technology then free software is available and Mizutech also offers WebRTC to SIP gateway (free with the Advanced license) and free service
tier. Common VoIP servers also has built-in WebRTC support nowadays)
Client side:
·
Any browser supporting
WebRTC OR Java OR native plugins with JavaScript enabled (most browsers are
supported)
·
Audio device: headset or microphone/speakers
Compatibility:
·
OS: Windows (XP,Vista,7,8,10,11)
, Linux (most distros), MAC OSX, Android, iOS, BlackBerry, Chromium OS and
others
·
Browsers: Firefox, Chrome, IE
(6+), Edge, Safari, Opera and others
·
Different OS/browser might have
different compatibility level depending on the usable engines. For example the
rarely used Flash engine doesn’t implement all the functionalities of the
WebRTC/Java/NS engines (these differences are handled automatically by the
webphone API)
If you don't have an IP-PBX or VoIP
account yet, you can use or test with our SIP VoIP service.
·
Server address:
voip.mizu-voip.com
·
Account: create
free VoIP account from here or use
the following username/passwords: webphonetest1/webphonetest1,
webphonetest2/webphonetest2 (other people might also use these public accounts
so calls might be misrouted)
Some more details can be found here.
The goal of this project is to
implement a VoIP client compatible with all SIP servers, running in all
browsers under all OS with the same user interface and API. At this moment no
technology exists to implement a VoIP engine to fulfill these requirements due
to browser/OS fragmentation. Also different technologies have some benefits
over others. We have achieved this goal by implementing different “VoIP
engines” targeting each OS/browser segment. This also has the advantage of just
barely run a VoIP call, but to offer the best possible quality for all
environments (client OS/browser). All these engines are covered by a single,
easy to use unified API accessible from JavaScript. To ease the usage, we also
created a few different user interfaces in HTML/JS/CSS addressing the most common
needs such as a VoIP dialer and a click to call user interface.
More details about how it works can be
found here.
Each engine has its advantages and
disadvantages. The sip webphone will automatically choose the “best” engine
based on your preferences, OS/Browser/server side support and the enduser
preferences (this can be overridden by settings if you have some special
requirements): VoIP availability in browsers.
Native VoIP engine
implemented as a service or browser plugin. The engine works like a usual SIP client, connecting
directly from client PC to your SIP server, but it is fully controlled from web
(the client browser will communicate in the background with the native engine
installed on the client pc/mobile device, thus using this natively installed
sip/media stack for VoIP).
Available for: all
browsers on Windows, Linux
Pros:
·
All features all supported, native
performance
Cons
·
Requires install
(one click installer)
A new technology for media
streaming in modern browsers supporting common VoIP features. WebRTC is a built-in module in modern browsers which can be used to implement
VoIP. Signaling goes via websocket (unencrypted or TLS) and media via encrypted
UDP (DTLS-SRTP). These are then converted to normal SIP/RTP by the VoIP server
or by a gateway.
Available for: all
modern browsers.
Pros:
·
Comfortable usage
in browsers with WebRTC support because it is has no dependencies on plugins
Cons:
·
It is a black-box
in the browser with a restrictive API
·
Lack of popular
VoIP codec such as G.729 (this can be solved by CPU intensive server side
transcoding)
·
A WebRTC to SIP
gateway may be required if your VoIP server don’t have built-in support for WebRTC (there are
free software for this and we also provide a free service tier, included by
default)
A browser plugin
technology developed by Adobe with its proprietary streaming protocol called RTMP.
Available for: old
browsers.
Pros:
·
In some
old/special browsers only Flash is available as a single option to implement
VoIP
Cons:
·
Requires server
side Flash to SIP gateway to convert between flash RTMP and SIP/RTP (we provide
free service tier)
·
Basic feature set
Based on our powerful
JVoIP SDK, compatible with all JRE enabled browsers. Using the Java Applet technology you can make SIP calls
from browsers the very same way as a native dialer, connecting directly from
client browser to SIP server without any intermediary service (SIP over UDP/TCP
and RTP over UDP).
Available for: java
enabled browsers such as IE, Pale Moon and old Firefox/Chrome.
Pros:
·
All SIP/media
features are supported, all codecs including G.729, wideband and custom extra
modules such as call recording
·
Works exactly as
a native softphone or ip phone connecting directly from the user browser to
your SIP capable VoIP server or PBX (but with your user interface)
Cons:
·
Java is getting
deprecated by modern browsers (handled automatically by the webphone by just
choosing another available engine)
·
Some browsers may
ask for user permission to activate the Java plugin
Some platforms don’t
have any suitable technology to enable VoIP in browsers (a minor percentage,
most notably old iOS/Safari). In these cases the webphone can offer to the user
to install a native softphone application. The apps are capable to
fully auto-provision itself based on the settings you provide in your web
application so once the user installs the app from the app store, then on first
launch it will magically auto-provision itself with most of your
settings/branding/customization/user interface as you defined for the webphone
itself.
Available for: old
browsers with no any built-in or plugin based VoIP support.
Pros:
·
Covering
platforms with lack of VoIP support in browsers (most notable old iOS Safari)
Cons:
·
No API support.
Not the exactly same HTML user interface (although highly customized based on
the settings you provided for the webphone)
These are just
“virtual” engines with no real client VoIP stack.
·
P2P means server initiated phone to phone call
initiated by an API call into your VoIP server. Then the server will first call
you (on your regular mobile/landline phone) and once you pick it up it will
dial the other number and you can start talking (Just set the “p2p” setting to
point to your VoIP server API for this to work)
·
Callback is a method to make cheap
international calls triggering a callback from the VoIP server by dialing its
callback access number. It might be used only as a secondary engine if you set
a callback access number (Just set the “callback” setting to point to your VoIP
server API for this to work)
These are treated as a
secondary (failback) engines and used only if no other engines are available
just to be able to cover all uncommon/ancient devices with lack of support for
all the above engines which is very rare. However it might be possible that
these fits into your business offer and in that case you might increase their
priority to be used more frequently. Alternatively it might be used also to
initiate native call under low quality network conditions.
This means native calls
from mobile using your mobile carrier network. This is a secondary “engine” to
failback to if no any VoIP capabilities were found on the target platform or
there is no network connection. In these circumstances the webphone is capable
to simply trigger a phone call from the user smartphone if this option is
enabled in the settings. Rarely used if any.
The most important
engines are: NS, WebRTC and Java. The other engines are to provide support for
exotic or ancient browsers maximizing the coverage for all OS/browser
combinations ensuring that endusers always has call capabilities regardless of
the circumstances.
All the above engines
are covered with an easy to use unified Java Script API, hiding all the
differences between the engines as described below in the “JavaScript
API” section.
The webphone can be
used with or without a user interface.
The user interface can
be built using any technology with JS binding. The most convenient is HTML/CSS,
but you can also use any others such as Flash.
The webphone package
comes with a few prebuilt feature rich responsive user interfaces covering the
most common usage such as a full featured softphone user interface and a click
to call implementation. You are free to use these as is, modify them after your
needs or create your own from scratch. For more details check the “User interface Skin/Design” section.
The webphone is sold with life-time unlimited client
license (Advanced and Gold) or restricted number of licenses (Basic and
Standard). You can use it with any VoIP server(s) on your own and you can
deploy it on any webpage(s) which belongs to you or your company. Your VoIP
server(s) address (IP or domain name) and optionally your website(s) address
will be hardcoded into the software to protect the licensing. You can find the
licensing possibilities on the pricing page.
After successful tests please ask for your final version at webphone@mizu-voip.com. Mizutech will deliver your webphone build within
one workday after your purchase.
Release versions does not have any limitations (mentioned below in the “Demo
version” section) and are customized for your domains/brand. All “mizu” and
“mizutech” words and links are removed so you can brand it after your needs
(with your company name, brand-name or domain name), customize and skin (we
also provide a few skin which can be freely used or modified).
Your final build must be used only for you company
needs (including your direct sip endusers, service customers or integrated in
your software).
Title, ownership rights, and intellectual property
rights in the Software shall remain with MizuTech.
The webphone is licensed per server (except the Gold
version). Already licensed servers cannot be removed or changed, however, you
can use domain names, thus allowing changing your server or its IP address any
time later without any implications regarding the webphone license. The
exception for the server limitations is the Gold version, which has a more
flexible licensing, allowing also unlimited servers.
The agreement and the license granted hereunder will terminate automatically if
you fail to comply with the limitations described herein. Upon termination, you
must destroy all copies of the Software. The software is provided "as
is" without any warranty of any kind. You must accept the software SLA before
to use the webphone.
You may:
·
Use the webphone on any number of
computers, depending on your license
·
Give the access to the webphone
for your customers or use within your company
·
Offer your VoIP services via the
webphone
·
Integrate the webphone to your
website or web application (or native applications usually via a webview)
·
Use the webphone on multiple
webpage’s and with multiple VoIP servers (after the agreement with Mizutech).
All the VoIP servers must be owned by you or your company. Otherwise please
contact our support to check the possibilities
You may not:
·
Resell the webphone as is
·
Sell “webphone” services for
third party VoIP providers and other companies usable with any third-party VoIP
servers (except if coupled with your own VoIP servers)
·
Resell the webphone or any
derivative work which might compete with the Mizutech “webphone” software offer
·
Create competition for Mizutech
by reselling the webphone in similar way (not tied to your servers or apps, but
as a general browser VoIP client)
·
Reverse engineer, decompile or
disassemble or modify the software in any way except modifying the settings and
the HTML/CSS skins or the included JavaScript examples
Note: It is perfectly fine to sell or
promote it as a “webphone service” if that is tied to your own SIP servers. But
if you sell it as webphone software which can be used with any server than you
are actually selling the same as Mizutech and this is not allowed by the
license.
There are the following legal ways to
use the webphone:
·
you have your own
SIP server(s) and the webphone will be used with these server(s) (your customers
can integrate the webphone into any application or website but they will use
the webphone via your VoIP server)
·
you are building
some application or website (such as a CRM, portal or game), so the webphone
will be tightly integrated with your solution
·
both of the above
(webphone used via your own SIP server from within your own website or
application)
·
click to call for
your webpage (or click to call service for others via your SIP server)
·
your call center
or contact center
·
call center
software offered to other companies if the webphone is deeply integrated in
your callcenter software or uses your own SIP server for call
termination/reception
·
you are a VoIP
service provider and wish to allow your customers to make calls from your
website (without the need to install a native client)
Contact us
if you wish to use the webphone in some other way which is not covered by this
license or you are in doubt with the usage: webphone@mizu-voip.com
The downloadable
demo version can be used to try and test before any purchase. The demo version
has all features enabled but with some restrictions to prevent commercial
usage. The limitations are the followings:
·
commercial usage not allowed
·
maximum ~10 simultaneous webphone
instances at the same time (depending on the engine used)
·
might be restricted to up to ~5
or ~10 simultaneous calls (depending on the engine used)
·
will expire after several months
of usage (around 2 - 5 months, depending on the release date)
·
maximum ~100 sec call duration
restriction
·
maximum ~10 calls / session
limitation (after ~10 calls you will have to restart your browser)
·
will work maximum ~20 minutes
after that you have to restart it or restart the browser
·
can be blocked from Mizutech
license service
The demo version can be used for all
kind of tests or development, but it can’t be used for production. It can be
used by up to 5 developers to make short calls (below 100 seconds) and the
browser have to be restarted after 10 calls or 20 minutes, otherwise a “Trial”
or “License” error will be displayed or printed to the browser console.
Note: for the first few calls and in
some circumstances the limitations might be weaker than described above, with
fewer restrictions.
All these demo limitations are removed from the licensed versions.
See the pricing and order your licensed copy from here.
On request we
can also provide an one month trial without the above demo limitations.
Integration and customization
The webphone is a
flexible VoIP web client which can be used for various purposes such as a dialer on your website, a click to call button for contacts
or integrated with your web application (contact center, CRM, social media or
any other application which requires VoIP calls).
The webphone can be
customized by its numerous settings, webphone API’s and by changing
its HTML/CSS.
Deploy:
The webphone can be deployed as a static page (just copy the webphone file to
your website), as a dynamic page (with dynamically generated settings) or used
as a JavaScript VoIP library by web developers.
You can embed the webphone to your website in
a div, in an iFrame or on demand, as a module or as a separate page. The webphone
settings can be set also by URL parameters so you can just launch it from a link with all the required settings
specified.
VoIP platform:
All you need to use the
webphone is a SIP account at any VoIP service provider or your own
softswitch/IP-PBX.
Free SIP accounts can be
obtained from numerous VoIP service providers or you can use our service.
(Note that free accounts are free only for VoIP to VoIP calls. For outbound
pstn/mobile you will need to top-up your account).
If you wish to host it
yourself then you can use any SIP server software. For example FreePBX
for linux or the advanced /
free VoIP server for windows by Mizutech. We can also provide our WebRTC to SIP gateway (for free with the Advanced or Gold license) if your
softswitch don’t have support for WebRTC and you need a self-hosted solution.
Settings:
The webphone settings can
be passed multiple ways as described at the beginning of the parameters chapter.
The most important
parameter that you will need to set is the “serveraddress”
which have to be set to the domain or IP:port of your SIP server.
Other important
parameters are listed here.
More details regarding
the configuration with your SIP server can be found here.
Integration:
You can integrate the webphone with your web-site or web-application:
-using your own web server API
-and/or using the
webphone client side JavaScript API to insert any
business logic or AJAX call to your server API
The webphone library
doesn’t depend on any framework (as it is a pure client side library) but you
can integrate it with any server side framework if you wish (PHP, .NET, NodeJS,
J2EE or any server side scripting language) or work with it only from client
side (from your JavaScript).
On the client side you
can use the webphone API from any JavaScript framework (such as AngularJS,
React, Vue, Electron, WordPress and others) or from plain/vanilla JS or not use
the JS API at all.
You can tightly integrate
the web phone with your SIP server using the methods described here.
Design
You can completely change any of the included skins (click to call button,
softphone), or change the softphone colors or create
your user interface from scratch with your favorite tool and call the webphone
API from there.
Custom application:
For deep changes or to
create your unique VoIP client or custom application you will need to use the JavaScript API.
See the development section for more details.
Branding:
Since the webphone is
usually used within your website context, your website is already your brand
and no additional branding is required inside the webphone application itself.
However the softphone skin (if you are using this turn-key GUI) has its own branding
options which can be set after your
requirements.
Additionally you can
change the webphone HTML/CSS design
after your needs if more modifications are required.
On request, we can send
your webphone build already preconfigured with your preferences.
For this just answer the points
from the voip client customization page (as many as possible) and send to us by email.
Then we will generate and send your webphone build within one work-day. All the
preconfigured parameters can be further changed by you via the webphone
settings.
Of course, this is
relevant only if you are using a skin shipped with the webphone, such as the
softphone.html. Otherwise you can create your custom solution using the
webphone library with your unique user interface or integrate into your
existing website.
User
interface Skin/Design
You can use
the webphone with or without a user interface.
The webphone is shipped with
a few ready to use open source user interfaces such as a softphone and click to
call skins. Both of these can be fully customized or you can modify their
source to match your needs. You can also create any custom user interface using
any technique such as HTML/CSS and bind it to the web phone javascript API.
The default user interface for the
softphone and other included apps can be easily changed by modifying parameters
or changing the html/css. For simple design changes you don’t need to be a
designer. Colors, branding, logo and others can be set by the settings
parameters.
Also you can easily create your own app
user interface from scratch with any tool (HTML/CSS or others) and call the
webphone Java Script API from your code.
In short, there are two ways to achieve
your own (any kind of) custom user interface:
A.
Use one of the skins provided by
the webphone
Here you also have two possibilities:
o Quick customization changing the webphone built-in user-interface
related settings (you can change the colors, behaviors and others)
o If you are a web developer, then have a look at the
html and JavaScript source code and modify it
after your needs (we provide all the source code for these; it can be found
also in the downloadable demo)
B.
Create
your own user web VoIP user interface
and use the webphone as a JavaScript library for the SIP protocol from there.
The webphone has an easy to use API which can be easily integrated with any user
interface. For example from your “Call” button, just call the webphone
webphone_api.js.call(number) function. Have a look at the samples folder:
“minimal_example.html”, “basic_example.html” or “techdemo_example.html” (You
can also use the provided samples as a template to start with and modify/extend
it after your needs)
Just use the “colortheme” parameter to make quick and wide changes.
Then have a look at the “User interface
related” parameters (described in
the “Parameters” section) and change them after your needs (set
logo, branding, translate and others).
We can also send you a web softphone with
your preferred skin. For this just set your customization on the online designer form and send us the parameters.
We can also send you fully customized
and branded web softphone with your preferences. For this just send us
the customization details.
Read below if you need more
customizations.
Web developers/designers can easily
modify the existing skins or create their own.
For the softphone application all the
HTML source code can be found in "softphone.html" file as a
single-page application model.
There are a few possibilities to change
the skins:
·
Change the user interface
related parameters as already
discussed above (for example the “colortheme”
and other parameters)
·
You can manually edit the html
and css file with your favorite editor to change it after your needs
·
Or just create your design with
your favorite tools and call the web sip phone API from there
·
If you wish to customize the
softphone skin (softphone.html), it is discussed in details here
Note: If you are using the webphone as
a javascript SIP library then you can customize the “choose engine” popup in
"css\pmodal.css".
The webphone can be positioned on your
webpage after your needs. You can put it in a DIV or iFrame control and define
any position from HTML of CSS. For example you can make it floating as
described here.
If you have different needs or don’t
like the default skins, just create your own from scratch and call the webphone
JavaScript API from your code. Using the API you can easily add VoIP call
capabilities also to existing website or project with a few function calls as
described in the “Java Script API” section
below.
For specific needs, look at the
following sections:
·
Dialer
skin
·
Click
to call skin
·
Custom
solution
·
Floating skin
·
Multi-line
With the Mizu webphone you can create a
web based softphone which looks like and works like a native desktop softphone
application (such as X-Lite). A web based solution has a big advantage since it
is always available for endusers without the need to download and install an
application and also it is much more flexible than a traditional softphone
(tons of parameters, easy to build user interface with HTML/CSS and easy
integration with your backend).
The webphone includes a turn-key ready softphone
skin (softphone.html) which you can start using in production as-is or change
it after your needs.
You can create any HTML/CSS
web design (with call controls, contact lists, etc) and call out to the
WebPhone API to add the VoIP functionality.
You can start with any
custom design from scratch or you might extend the “api_example.html” to reach
your goals.
More details can be found here.
There are two possibilities to create
your web dialer:
·
Create your web softphone or
dialer from scratch
You can create any HTML/CSS web design (with call
controls, contact lists, etc) and call out to the WebPhone API to add the VoIP
functionality.
Start with any custom design from scratch or you
might extend the “api_example.html” (or any other from the samples folder) to
reach your goals.
Basically the purpose of the webphone library is to
create any web based SIP client solution and most of this documentation is
about describing this process.
Jump here to
begin the development.
·
Modify the existing softphone
skin
In this chapter below we will explore the
possibilities of customizing and extending the softphone skin (softphone.html)
Softphone
skin basic customization
An easier solution is to
use the turn-key softphone skin shipped with the webphone (softphone.html and
related css and js files). This can be used as-is (it is a ready to use
turn-key solution) or further modifying after your needs.
No any development
knowledge is required to deploy the
web softphone on your website
and you can also customize it easily via webphone parameters.
Note: You can quickly test
this also from the online demo if you haven’t downloaded
the webphone demo package yet: https://www.webvoipphone.com/webphone_online_demo/softphone_launch.html (this will launch the very same “softphone.html”
included in the download package).
If you are a JavaScript developer then you might implement even more
modifications by changing the HTML, CSS or JS files (softphone.html,
js\softphone files).
We can also ship the
webphone with ready to use customized softphone skin (with your branding and
settings). For this, just answer the points on this page
on your order and send the answers by email.
Here is the whole process
step by step:
1)
Order your webphone from Mizutech
with branding (send as many customization details as you can by answering these points).
At this point you
already have a turn-key ready to use solution which can be deployed and used as-is on your website/page/application,
without the need of any technical or developer knowledge.
2)
Customize your softphone by
adjusting the technical parameters
after your needs
This can be easily
done by just modifying or adding more parameters in the webphone_config.js. At
least the “serveraddress” parameter must be set.
3)
Modify the user interface
related parameters after your needs
For example you can
set the “colortheme” parameter to make quick and wide change about the
skin appearance.
4)
Optionally further customize your
softphone by making more user interface changes as described here and here.
This optional step
requires some basic HTML/CSS knowledge.
5)
Optionally further customize your
softphone by integrating it with your client side application, integrating it
with your server, integrate with server-side address
book or change/add functionalities
by using the phone
API .
This optional step requires
some development knowledge.
The softphone skin can be positioned on
your webpage after your needs. You can put it in a DIV or iFrame control and
define any position from HTML of CSS. For example you can make it floating as
described here.
Softphone
skin advanced customization
If the above described customization
options are not enough to achieve your goals, you can modify or extend the softphone
HTML, CSS or JavaScript code.
The softphone skin can be further
customized, with new functionality, new user interface elements including new
pages.
Adding a new functionality for the
softphone skin usually involves the followings:
·
Add some user interface element
to the softphone skin. This is described in this chapter below.
·
Add functionality for your user
interface element. This is usually interaction with the SIP client or
interaction with your app server (web service):
o To interact with the SIP client, just use the
webphone SIP
API. Learn more here.
o For the interaction with your backend you can use
AJAX requests. Learn more here.
Files
All the webphone SDK library related
files are located in the \js\lib\ directory.
The softphone skin related files are:
·
html file: this is a Single Page
Application and the HTML code is all in "softphone.html"
·
css files are located in \css\
directory
·
javascript files are located in:
\js\softphone\ directory.
JQuery Mobile
The softphone skin is a single page
application built using jQuery Mobile framework.
Note: jQuery Mobile is not maintained
anymore by its original developers, however we forked a copy, which we keep up
to date and optimized also for latest browser changes.
Every jQuery mobile "page"
defined in softphone.html has a corresponding Javascript file in /softphone/
directory.
Regarding css files, styling, most of
these css files in "css" directory are related to jQuery Mobile
framework which is used to aid in the build of the Single Page application and
these should not be edited/changed.
All the styling of the webphone skin is
defined in "mainlayout.css" and can be customized from here. This css
file should be used to change any styling.
A simple way to change the softphone
design can be achieved by changing the jQuery theme: The jQuery mobile Theme
Roller generated style sheet can be found in this file:
"css\themes\wphone_1.0.css".
Current jQuery mobile version is 1.4.2.
Using the Theme roller, you can create new styles:
http://themeroller.jquerymobile.com/
The style sheet which overrides the
"generated" one (in which all the customizations are defined) is
"css/mainlayout.css".
For basic color scheme changes you can
use the online designer form. Send us your preferred color parameters and we can send you a
softphone build preconfigured with your favorite colors.
Important note: jQuery namespace within
the webphone is changed from "$" to “webphone_api.$”.
Pages
Pages in softphone.html are <DIV>
elements with the following attribute: data-role="page".
Every jQuery mobile "page"
defined in softphone.html has a corresponding Javascript file in js/softphone/
directory.
For example settings page's HTML is
defined in softphone.html file in a <DIV> element with the id:
page_settings. The corresponding Javascript file for the settings page is:
\js\softphone\_settings.js. All these "page view" Javascript files
contain a few lifecycle functions which are used to initiate/load/destroy a page.
Helper containers
For your convenience, the softphone
skin already contains a few <DIV> elements where you can drop any custom
content.
These are place below the header on
each main page (settins, dialpad, contactslist, callhistorylist).
The ID of these elements is the
followings:
·
extra_header_settings
·
extra_header_dialpad
·
extra_header_contactslist
·
extra_header_callhistorylist
Of course, you can add, modify or
remove any user interface element as you wish. Edit the html and CSS files
after your needs.
These DIV’s were added only to help
beginners.
Extra customizable pages
There are 5 predefined extra pages
which can be customized as required. These pages are: page_extra1, page_extra2,
page_extra3, page_extra4, page_extra5.
The corresponding javascript files are:
_extra1.js, _extra2.js, _extra3.js, _extra4.js, _extra5.js.
In each javascript file related to a
page, there are three "lifecycle" functions predefined:
·
onCreate(): This lifecycle function is called only once per
session, when the user navigates to the page for the first time. This is where
most initialization should go: attaching event listeners, initializing static
page content, etc.
·
onStart():This lifecycle function is called every time the
user navigates to this page (every time the page is displayed). This is where
dynamic content can be added/refreshed. For example on Contacts page we load
and display the contacts list.
·
onStop():This lifecycle function is called every time the
user navigates away from this page. This is where you can save data that the
user modified, clear dynamically added page content, etc.
Page navigation:
Page navigation can be done by calling
jQuery mobile "changePage()" method:
Format:
webphone_api.$.mobile.changePage("#PAGE_ID", { transition:
"none", role: "page" });
Example:
webphone_api.$.mobile.changePage("#page_extra1", { transition:
"none", role: "page" });
To "close" a page, you can
either navigate to another page, or return to the previous page by calling
jQuery mobile method: webphone_api.$.mobile.back();
Page content:
The content of a page will be put in a
<DIV> element with the following attribute: role="main".
Content can be added:
·
statically, by defining the
content in softphone.html file. For example for page_extra1 the content will be
in <DIV> element with id: page_extra1_content.
·
dynamically, in function
"PopulateData()" defined in all javascript files corresponding to a
page.
Autocomplete:
You can turn autocomplete off for your
HTML input elements like this:
<input type="text"
autocomplete="off" name="destination" id=”destination”
/>
Auto login:
By default the softphone skin will stop
at the login screen only if there was no previous login (missing
username/password).
Otherwise it should auto-login.
If you wish to preset the
username/password then you can do it multiple ways:
·
Set it in the webphone_config.js
·
Pass as URL query parameters
https://www.youraddress.com/webphone_path/softphone.html?wp_username=xxx&wp_password=yyy
·
Pass it from JavaScript using the
setparameter() API
·
Pass it from your server side
script session variable
Add functionality to web softphone
skin
The webphone is shipped with a ready to
use softphone skin with full functionality, but this doesn't mean that other
desired functionalities cannot be added.
This can be achieved using the
webphone's API.
For example, capturing call state
events (or using any other API function) can be done like this:
- create a new javascript file, for
example new.js
- import this script right after
"webphone_api.js" in softphone.html file
- add the following javascript code in
new.js:
//start
interacting with the webphone only once the onAppStateChange callback has been
fired with the “loaded” event.
webphone_api.onAppStateChange
(function (state)
{
if
(state === 'loaded') //webphone loaded
{
webphone_api.onCallStateChange(function (event, direction, peername,
peerdisplayname, line, callid)
{
//handle
any events here. For example to catch the call connect events:
if
(event === 'connected')
{
//add your
code here
}
});
}
});
You can find a similar example of
webphone API usage in /samples/basic_example.html.
Empty callback functions can be found
in the _dialpad.js file for your convenience (onAppStateChange,
onRegStateChange, onCallStateChange, onCdr). You can just enter any code for
these functions body.
The full webphone API is available so
you can easily interact with the softphone skin from external modules or
injected code as described in the development
and API chapters. Please note that the onCallStateChange and
some other callbacks are not used internally by the softphone (because it uses
the low level notifications), but you can use them in your code to catch
webphone state changes. Just set your callback function(s) and it will work.
The skin HTML is located in
softphone.html.
This is a single page
application that uses jQuery Mobile
framework for the single page structure and also for UI elements cross browser
compatibility. Every “page” in “softphone.html” has a corresponding Javasript
file in “\js\softphone\” directory, for example: "page_dialpad" is managed by “_dialpad.js” file.
Each Javascript file
managing a page has three “life cycle” callback functions:
·
onCreate() - called only once –
it is a good practice to handle binding to all kind of events here
·
onStart() – called every time the
page is displayed
·
onStop() – called every time the
page is “closed”
Note: jQuery namespace within the webphone is
changed from "$" to "j$" or to “webphone_api.$”.
Page
list
Below is a list of all Javascript
files managing pages. These are located in \js\softphone\ directory:
“_accounts.js”: manage multiple SIP
accounts
“_addeditcontact.js”: user interface
for creating or editing contacts
“_call.js”: user interface of the in
call page
“_callhistorydetails.js”: call
history details page
“_callhistorylist.js”: call history
list page
“_message.js”: messaging page
“_messagelist.js”: messaging inbox
list page
“_contactdetails.js”: contact
details page
“_contactslist.js”: contacts list
page
“_filetransfer.js”: file transfer
page
“_filters.js”: simple prefix rewrite
page
“_internalbrowser.js”: web view used
as a browser
“_logview.js”: page for viewing
internal app log/trace
“_newuser.js”: new user
registration page
“_dialpad.js”: main dial pad page
“_settings.js”: settings/login page
“_startpage.js”: it’s a page
displayed once or on every start; can by a URL or text; usually used for
privacy policy
“themes.js”: contains all the
definitions of the different color themes that can be applied to the skin
Menu
Every page has a menu
which can be accessed when the menu button in top-right corner is clicked. This
click event triggers the CreateOptionsMenu() function in the corresponding page
javascript file. In CreateOptionsMenu() function the menu is assembled every
time it is displayed to the user.
Then in
MenuItemSelected() function the selected menu item will be handled.
Navigation
Navigation between pages can be
accomplished with the jquery mobile changePage() method. For example, to navigate
to settings page the following command will be used:
webphone_api.$.mobile.changePage("#page_settings", {
transition: "pop", role: "page"
});
Styling
All the skin related CSS files are
located in “\css\softphone\” directory. Here all the CSS files are jQuery
mobile generated style sheets, except “mainlayout.css”. All the styling is done
here.
All element dimensions are set
proportionally with percentages if possible, or using “em” unit of measure, to
assure that the skin user interface resizes well on any screen size and any
resolution.
Skin
start up
The main page launched is every time
the settings page. If the user has already entered login credentials before,
the skin will automatically login and display the dial pad page.
The softphone skin is open sourced
(plain html/css/js source code is included in the webphone package) and it can
be freely changed by any web developer.
A few common tasks are described below
for your convenience:
How
to add a new page
The ready to use skin which is
delivered with the webphone package is built as a single page application using
jQuery mobile framework (actually only a few things are used from jQuery
mobile, the rest is plain html/javascript).
Follow the steps below to create a
new page:
1) Create new <div> html element
with attribute data-role="page" in softphone.html file. You
can use “page_extra1” as template.
2) Create the equivalent JavaScript
file, which manages the behavior of the new page. You can use the “_extra1.js” file as template.
3) Add the three “life cycle” callback
Javascript functions in init.js
a.
webphone_api.$(document).on('pageinit
b.
webphone_api.$(document).on('pageshow'
c.
webphone_api.$(document).on('pagebeforehide'
The new page is ready.
How
to change the login page
The login page is managed in
“_settings.js” file. Basically, it displays only the main login settings:
serveraddress, username, password. There is also a traditional style login page
which can be enabled with the “useloginpage” parameter: -1=auto (default),
0=no, 1=only at first login, 2=always.
How
to change the main page (dial pad tab)
The main dial pad tab consists of
the “page_dialpad” id <div> defined in softphone.html and the associated
javascript file: _dialpad.js.
How to add a new setting
First establish the setting
parameter name, which should be in lowercase, for example “newsetting”.
Open stringres.js file and define
the new setting title, description and short description (short description is
optional) with the following format:
sett_display_name_mysetting: 'My settings',
sett_comment_mysetting: 'My new settings does the following',
sett_comment_short_mysetting: '',
If you want this setting to appear
on the user interface, then add the “newsetting” to the comma separated list
stored in String variable “settOrderWebphone” and
“settOrderWebphoneWebRTCFlash” located in _setings.js file. Also, the order in
this list will define the order in which the settings will be displayed. For a
setting to appear in “Basic settings”, the parameter name should be added to
the slit in variable “basicSettings”.
To actually define a new setting, go
to “InitializeSettings()” function in common.js file add the new settings using
SettingItem() function.
The following line of code will add
the new settings:
SettingItem ("newsetting", "", "1", GROUP_LOGIN, "", "", "1", "");
SettingItem function has the
following parameters:
·
(String)
parameterName: the name of the parameter.
·
(String) value:
the current value of the parameter. I can be empty string.
·
(String) type:
the type of the settings:
o “0” = (boolean) enabled/disabled
o “1” = text input
o “2” = dropdown list
·
(String) group:
it belongs to this group/submenu:
o “20” = displayed on login page
o “0” = basic settings list
o “1” = SIP settings
o “2” = Media settings
o “3” = Call divert settings
o “4” = General Settings
o “8” = Video settings
·
(String)
allNames: a comma separated list of the display names of possible values. Used
only for dropdown list type settings, otherwise empty string.
·
(String)
allValues: a comma separated list of the actual parameter values. Used only for
dropdown list type settings, otherwise empty string.
·
(String)
isdefault: the value here should always be “1”
·
(String)
defaultValue: the default value of the parameter
How
to remove a setting
Go to “InitializeSettings()”
function in common.js file and comment out/delete the “SettingItem()” function call for that parameter
that is to be removed.
Also search for setting parameter
name in “settOrderWebphone” and “settOrderWebphoneWebRTCFlash” and
“basicSettings” variable and remove it from there if found.
How
to add a new menu item
In every javascript file that
manages a page (located in \js\softphone\), the Menu is created in
“CreateOptionsMenu ()” method. Add a menu with the following line of code:
webphone_api.$(menuId).append('<li
id="ITEM_ID"><a
data-rel="back">TITLE</a></li>').listview('refresh');
In
MenuItemSelected() function handle the action for the added menu based on
itemId.
How
to remove a menu item
In every javascript file that
manages a page (located in \js\softphone\), the Menu is created in
“CreateOptionsMenu ()” method. Just comment out or delete the “webphone_api.$(menuId).append()” line for the item to be removed.
How
to add a header/footer
For every page there is already
added a header and a footer where custom content can easily be displayed.
The content to be displayed here can
be text or HTML and can be specified with the following parameters in
webphone_api.js: “header” and “footer”.
Click-to-call (also known as click-to-talk, webcall or click-to-dial)
is a simplified form to make a call when the enduser just needs to click on a
button or a hyperlink to request an immediate connection to another webphone,
softphone or PSTN (landline/mobile), without the need of configuration to be
set by the enduser.
You can use the webphone SIP library to implement your custom
click-to-call solution or use one of the skin templates for click to call.
Click to call buttons or links can be embedded into any webpage (sales page,
blogs, social media, others) and also in email (click to call from email
signature).
You can also set auto-dial feature when the call is initiated
automatically without enduser interaction, using the callto
and autoaction parameters.
There are multiple ways to achieve
click to call or clicktodial functionality with the sip webphone:
1) Click to call from HTML link via URL parameters
(single line copy-paste code into your html)
2) Use the webphone library directly (via it’s API) to
implement any custom click to call solution (for JavaScript developers)
3) Use the click2call template as-is. A click to call
skin is shipped with the webphone (click2call.html and related css/js files) as
a turn-key click to call solution which can be used without any development
knowledge
4) Modify the click2call template by changing its
settings and skin after your needs)
Details:
1) Click to call from HTML link
You can pass any setting as URL parameter
and the webphone (and the included templates) can be easily parametrized to act
as a click to call solution:
http://www.yourwebsite.com/webphonedir/click2call.html?wp_serveraddress=YOURSIPDOMAIN&wp_username=USERNAME&wp_password=PASSWORD&wp_callto=CALLEDNUMBER&wp_autoaction=1
A working example with the click to
call skin:
https://www.webvoipphone.com/webphone_online_demo/click2call.html?wp_serveraddress=voip.mizu-voip.com&wp_username=webphonetest1&wp_password=webphonetest1&wp_callto=testivr3&wp_autoaction=1
This will launch the click to call page
and will initiate the call automatically. You can find more examples for URL
parameters here.
You can also use any other skins for
click to call. For example here is with the softphone skin:
https://www.webvoipphone.com/webphone_online_demo/softphone.html?wp_serveraddress=voip.mizu-voip.com&wp_username=webphonetest1&wp_password=webphonetest1&wp_callto=testivr3&wp_autoaction=1
2) Use the webphone library directly
You can easily create your custom click
to call solution from scratch by using the webphone as a library/SDK.
Just create a HTML button after your
needs and call the webphone_api.call(number)
function from there.
This is recommended for JavaScript
developers and in this way you can create any custom web click to call solution
after your needs.
Have a look at the click2call_example.html in the samples folder for
a very basic click to call implementation (you can use this as a starting point
for your custom development).
See the Development
and the API sections about how to work with the web phone SDK.
3)
Use the Click2Call template as-is
The webphone package contains a ready
to use click to call solution (click2call.html and related JS/CSS files).
Just copy the whole webphone folder to
your website, set the parameters in the webphone_config.js file and use the
click2call.html as-is on your webpage or directly.
Configure it after your needs by
adjusting (changing and/or adding) the settings in the “Configuration
parameters” section in the “click2call.html” file. See the parameters settings for the full list of adjustable settings.
Note: You can quickly test this also
from the online demo if you haven’t downloaded
the webphone demo package yet: https://www.webvoipphone.com/webphone_online_demo/click2call.html
4) Modify the Click2Call template
You can completely customize the
click2call example for your needs (change any settings,
change the html/css/javascript, use your custom button image).
This click2call template/skin consists
of a few different files:
·
\click2call.html
·
\css\click2call\click2call.css
·
\js\click2call\click2call.js
In the HTML file there is short html
code which defines a click to call button: <div
id="c2k_container_0" title="" style="text-align:
center;"></div>
This is the single line of HTML code
which you will include in your webpage where you want the click to call button
to be displayed. For the call button to work, you will also have to include
(preferably in the <head> section of your web page) the related css (in
this case click2call.css), Javascript (click2call.js) and the webphone API
file: webphone_api.js.
The Configuration parameters in
click2call.html are put there just for convenience. These same parameters can
be just as easily set in webphone_config.js file where the other webphone
parameters are set.
In order for the click to call skin to
work, a valid SIP account and a destination number need to be configured with
the following API parameters :
·
serveraddress: yoursipdomain.com your VoIP server IP address or
domain name
·
username: SIP account username
·
password: SIP account password
·
callto: destination number to call (the click2call can be
also modified to load this at run-time if there are multiple target numbers)
(You can also fine-tune your solution
by setting/changing any of the webphone parameters)
The click-to-call buttons color, width,
height, radius or the displayed text can be customized after your needs from
the click2call.js file using the variables from the "Customizations"
section.
You can even add a background image, by
setting your image (jpg or png format) path for the call_button_color variable
in the following way:
var call_button_color =
'url(IMAGE_PATH/YOUR_PHOTO.png)';
Integrate
into web page
Below is an example code and steps to integrate the
click to call button into your web page:
Put the below code in your web
page's <head> section:
<link
rel="stylesheet" href="css/click2call/click2call.css" />
<script
src="webphone_api.js"></script>
<script
src="js/click2call/click2call.js"></script>
<script>
/**Configuration parameters*/
webphone_api.parameters['serveraddress'] = '';
webphone_api.parameters['username'] = '';
webphone_api.parameters['password'] = '';
webphone_api.parameters['md5'] = '';
webphone_api.parameters['realm'] = '';
webphone_api.parameters['callto'] = '';
webphone_api.parameters['autoaction'] = 1;
//Add any other parameter here
</script>
Copy this html element in you page,
where you want the click to call button to show up:
<div
id="c2k_container_0" title=""><a
href="tel://CALLTO"
id="c2k_alternative_url">CALLTO</a></div>
Customize the button
The provided click to call example
button can further be customized with customization parameters located at the
beginning of click2call.js file in js\click2call\ directory:
/** Customizations */
var call_button_text =
'Call'; // text
displayed on call button
var hangup_button_text =
'Hangup'; // text
displayed on hangup button
var call_button_color =
'#43b61b'; // call
button color
var hangup_button_color =
'#e83232'; // hangup
button color
var status_text_color =
'#ffffff'; // color of displayed
status messages
var button_width =
135; //
button width in pixels
var button_height =
42; // button
height in pixels
var button_radius =
5; // button
corner radius in pixels, higher values will result in a round button
var chatwindow_title =
'Chat'; // chat
window header-title; can be text or html
var
chatwindow_default_state = 0; //
default state of the chat window: 0=open, 1=collapsed
The styling can be further customized
from click2call.css located in css/click2call/ directory.
/**For floating button*/
var float_button =
false; // if
set to true the button will float over the content of the webpage
var float_distance_from_top
= -1; // distance in
pixels from the top of the page. -1 means disabled
var
float_distance_from_left = -1; // distance in pixels from the left of the page. -1 means disabled
var
float_distance_from_bottom = -1; // distance in pixels from the bottom of the page. -1 means disabled
var
float_distance_from_right = -1; // distance in pixels from the right of the page. -1 means disabled
Customize the behavior
The click to call example can further
be customized by editing the js\click2call\click2call.js Javascript file.
All the API functions found in
webphone_api.js can be used to achieve the desired functionality.
For example if you choose to add your
own custom incoming call popup, you can do this in click2call.js file using the
webphone_api.onCallStateChange() function
where you receive call events. For chat message events use the webphone_api.onChat() function. Find more details
about the API functions in the documentation and in webphone_api.js.
Use as a chat window
The click to call button can also be
used as a chat window. This is controlled by the autoaction
parameter (1 means call, 2 means chat).
The chat window can also be opened by
accessing the menu and selecting the Chat item.
The menu can be accessed by right
clicking or by long clicking on the button.
Floating button
This click to call button can also be
used as a floating button on a web page. The floating related configurations
can be found in click2call.js file located in js/click2call/ folder.
To enable floating, set the
"float_button" config to true and specify two direction coordinates
for the floating. For example to have a floating button on the top right corner
of your page, located from 100 pixels from the top and 10 pixels from the
right:
var float_button = true;
var
float_distance_from_top = 100; //
floating 100 pixels from the top of the page
var
float_distance_from_left = -1;
var
float_distance_from_bottom = -1;
var
float_distance_from_right = 10; //
floating 10 pixels from the right of the page
The floating parameters also apply to
the chat window in the same way as for the click to call button.
Note: If somehow your changes will not have effect in the web browser,
you just need to clear the cache.
Multiple instances
To add more than one click to call
button to a page, include the script part in the <head> section once, and
copy the container <div> increasing the id index number for every
instance.
ex:
<div
id="c2k_container_0" title="55555"></div>
<div id="c2k_container_1"
title="66666"></div>
<div
id="c2k_container_2" title="77777"></div>
<div
id="c2k_container_3" title="88888"></div>
These id indexes must be unique and
increasing.
The callto parameter can be set as the
title attribute of the <div> element.
Load on demand
You can also load the sip web phone on
demand as explained here.
Auto-call
If you wish to make a
call automatically, then just initialize the webphone as described above and
-either set also the “autoaction” parameter to 1
-or make the call with
the webphone_api.call(number) API from the onAppStateChange() callback “loaded” event or from the onRegStateChange
() callback “registered” event.
The autoaction API parameter controls the behavior of the click to
call button and can have the following values:
0: Nothing (default) - it
will display the click to call button and will place a call whet the user
clicks it.
1: Call - it will
immediately place a call, once page is loaded in which the click to call button
is integrated.
2: Chat - a chat window
will be displayed for the user
3: Video Call - it will
immediately place a video call, once page is loaded in which the click to call
button is integrated.
Note:
o Even if you initiate a call form the onAppStateChange
“loaded” event and the webphone is not yet registered -and it needs to
register-, then it will handle registration first then it will initialize the
call automatically.
o If your IP-PBX doesn’t require registrations, then just
set the “register” setting to 0.
More
details about the click to call functionality can be found here and in this wiki article.
The most common use case
for the webphone is a dialer (softphone user interface) or as a click to call
solution (simple click to call button user interface).
For these we got you
covered with ready to use solutions shipped with the webphone (see the
softphone.html and the click2call.html files).
However this doesn’t mean
that the webphone usage is restricted only for these. You can create any kind
of solution using the webphone. A few examples are listed here.
All you need is a little
HTML knowledge to create your desired user interface and some JavaScript
knowledge to use the webphone API from your HTML/JS.
You might implement your
solution by extending
the softphone skin or by creating a
new solution from scratch.
See the webphone development section for more details.
Integration with Web server side applications or
scripts
This section is mostly for
server side developers. If you have more JavaScript skills then we recommend to
just use the JavaScript
API directly as described in the development section.
First of all it is
important to mention that the webphone doesn’t have any server side framework
dependencies. You can host it on any webserver without any framework (.PHP,
.NET, Node.Js ot others installed).
The webphone is running
entirely on the client side (in the user browser as a browser sip plugin) and
can be easily manipulated via its JavaScript SIP API, however you can easily integrate the webphone with any
server side application (web applications or web service) or script, be it
.NET, PHP, Node.Js, J2EE or any other language or framework even if you don’t
have JavaScript experience. Just create
a HTTP API to catch events such as login/call start/disconnect and drive your
app logic accordingly.
The most basic things you
can do is to dynamically generate the webphone parameters per
session depending on your needs. For example if the user is already logged-in,
then you can pass its SIP username/password for the webphone (possibly encoded).
For this, just generate
the webphone_config.js dynamically or pass the parameters in the URI.
For a tighter integration
you will just have to call into your server from the webphone.
This can be done with simple
XMLHTTP /AJAX or
websocket requests against your server HTTP API, then process the events in
your server code according to your needs. The requests can be generated using
the built-in HTTP API events or you can just post them yourself from your
custom JavaScript code using websocket or ajax requests. Usually these requests
will be made from callback
events which are triggered on web
phone state machine changes, but you are free to place ajax request anywhere in
your code such as click on a button.
Example:
For example if you need
to save each call details (date, caller, called, duration, others) into a
server side database, then just define a “oncalldetails” or similarly named API
in your server side application which can be called via simple HTTP request in
one of the following ways:
1.
Using the built-in HTTP API integration capabilities:
Just
set the scurl_onincalldisconnected to your HTTP API. For example: https://mydomain.com/myapi/oncalldetails/ (or wherever your API can be called). This method
is very convenient if you are a server side developer with no JavaScript knowledge
as you don’t need to touch any JavaScript to implement this. See the details here.
2.
Using custom AJAX requests:
Use
the onCdr() API to setup a callback which will be
triggered after each call.
Send
an AJAX request (XMLHttpRequest or jQuery get or post) to your application
server with the CDR details.
(You
can pass the details in HTTP GET URL parameters or in HTTP POST body in your
preferred format such as clear text, json, xml or other).
You will need an API on
your web server to handle the websocket or AJAX HTTP GET/POST requests from the
webphone.
This can be done by
implementing a web service or a simple script in any server side framework on
language (such as .ASP .NET, PHP, Node.js or others).
You can push/request
anything from the webphone and do anything with the data (store in a database
such as MS SQL, MySQL or PostgreSQL) or answer with some content to be
displayed on the webphone user interface.
For example on incoming calls
(cached with the onCallStateChange callback or preset with the scurl_onincallsetup parameter) you might look-up the caller id (caller number) in your
database and return details about the caller (such as full name, interests,
etc).
You can do similar things
for all other important events such as on phone start, on chat, on call setup,
etc and perform various actions on your server side such as
processing/transforming/storing the data received by the webphone and/or
returning answers to be processed or displayed by the webphone.
Note: For
auto-provisioning from a server side application, you can create an API to
return all the webphone parameters (settings) and set the “scurl_setparameters”
setting to this API URL.
Custom HTTP
API integration
You can integrate the webphone with
your server code using your custom HTTP requests (AJAX/fetch) API URI’s. These
are called “Action URL’s”, so you can implement various server-side actions
when something happens on the SIP client (such as on incoming call, on call
finished, and others). You can implement these API’s in your existing
server-side framework, using any language or tools (ASP.NET, PHP or any
others).
Just set one or more of the
following settings to point to your server application HTTP API entries which
will be called automatically as the webphone state machine changes:
·
scurl_onstart: will be called when the webphone
is starting
·
scurl_onoutcallsetup: will be called on outgoing call
init
·
scurl_onoutcallringing: will be called on outgoing call
ring
·
scurl_onoutcallconnected: will be called on outgoing call
connect
·
scurl_onoutcalldisconnected: will be called on outgoing call
disconnect with call details (CDR)
·
scurl_onincallsetup: will be called on incoming call
·
scurl_onincallringing: will be called on incoming call
ring
·
scurl_onincallconnected: will be called on incoming call
connect
·
scurl_onincalldisconnected: will be called on incoming call
disconnect with call details (CDR)
·
scurl_oninchat: will be called on incoming instant
message
·
scurl_onoutchat: will be called on outgoing instant
message
·
scurl_setparameters: will be called after onAppStateChange
started event and can be used to provision the webphone from server API. The
answer should contain parameters as key/value pairs, ex:
username=xxx,password=yyy
·
scurl_displaypeerdetails: will be called at the beginning of
incoming and outgoing calls to return details about the peer from your server
API (like full name, address or other details from your CRM). It will be
displayed at the location specified by the “displaypeerdetails” parameter. You
can return any string as clear text or html which can be displayed as-is.
Special keywords will be replaced by
the webphone at runtime. The keywords are listed here.
For example: scurl_onoutcallsetup: https://mydomain.com/myapi/?user=USERNAME&called=CALLEDUMBER
(Your API will be called each time
the webphone user makes an outgoing call and the parameters in uppercase will
be replaced at runtime in the same way as described for the links setting)
For API request, the webphone will
try to use following techniques (first available): AJAX/XHTTP, CORS, JSONP and
websocket (if available).
Make sure that there is no any
cross-domain request restriction: you might need to set the Access-Control-Allow-Origin
HTTP header on your WEB server/service to * or to the target domain if you are
not hosting the webphone on the same domain.
You can achieve similar functionality by
just sending AJAX request from the onCallStateChange callback.
Using these scurl variables is just a
different approach to help users with little JavaScript knowledge.
Integration with third party systems and
CRM’s
Many custom callcenters are using the webphone as
their VoIP client module to implement voice/video call capabilities.
You can use the webphone SIP library to
implement your custom click-to-call solution, use one of the skin templates for
click to call or use the softphone.html as-is integrated into your CRM.
The VoIP web sip phone browser plugin
doesn’t depend on any framework and can be integrated with any system or CRM
with JavaScript binding support. Usually you just need to include the
webphone_api.js, set the basic parameters in the webphone_config.js (such as
serveraddress/username/password to be used, but these can be passed also by the
API) and just use the call() function to make an outgoing calls. Incoming calls
are handled automatically and with a few more API calls you can easily
implement features such as call transfer, conference, chat, dtmf or video call.
For example here is tutorial for Salesforce webphone integration in case if you are interested in this platform or
some details about VoIP callcenter integration.
Consult your CRM documentation to find
the details about integration third-party general modules (or even better if it
has an interface specific for third party phone integrations). Contact us
if you need help with any integration.
Using the webphone with various server side
frameworks
The webphone doesn’t require any server
side web framework however you are free to use your own favorite framework,
language and libraries to interact with the web phone such as PHP, ASP.NET,
J2EE, NodeJS, Perl, C++, Python, Ruby on Rails, Express.js, Django or any other
framework.
This is useful if you have a server
application and you need certain details from the webphone (such as call detail
records to be inserted into your database) or you wish to push some data to the
webphone (settings depending on the enduser, incoming caller details, etc).
By default the webphone has nothing to
do with server side framework (it is a pure client-side library) so you can
deploy it like any other javascript library.
Then you can add server side binding in
various ways:
·
if you don’t have any JavaScript
experience, just use the action URL’s mentioned above
·
otherwise you can interact with
your server side service with AJAX calls (for example you can notify your
server about phone state change by triggering an xhttp request
from the from the onCallStateChange callback) or send call the details after hangup from the onCdr callback.
·
you can use also any other technique
for the communication between the webphone and your server such as WebSocket,
HTTP polling or use a library such as Socket.IO
technique (These might be necessary only if you wish to exchange a lot’s of
data between the webphone and your server application. Otherwise simple HTTP
API requests are just fine)
In short: All you need to do is to
create some API’s in your server application to be called from the webphone,
usually via AJAX XHTTP requests.
Examples:
We don’t have too much framework
specific examples to show as the webphone is a client-side library and the
server side integration is just optional and the usage is really
straightforward as described above:
·
ASP.NET: a very basic example
from one of our customer can be downloaded from here
·
A basic demonstration/example
about using the webphone with PHP can be found here.
·
Integration with various
frameworks can be also done via WebView as described here.
Integration
with SIP server side applications or scripts
This is a more
straightforward topic then the previous Web application integration because
here we are restricted to the SIP protocol capabilities.
Actually the main purpose
of the whole webphone library is to interact with a SIP server.
For a tighter integration
you can take full advantage of the SIP
protocol using the following tools:
·
Your SIP server capabilities
(configure the webphone extensions like any other SIP endpoint, taking full
advantage of your softswitch (or proxy/gateway/other SIP device) capabilities
such as voicemail, server side call forward, call queue, etc
·
Webphone parameters: you can
fully customize the webphone behavior by changing the parameters
·
Webphone API: fully control the
interaction between the webphone and your SIP server using the webphone API. Beyond
basic functionality, you can find useful functions such as BLF, dtmf, presence
which can be used for specific interaction with your SIP server in a standard
way. For example, during a call you can exchange additional details with your
SIP server using SIP INFO, DTMF or even chat/presence/BLF notifications.
·
You can also consider
using a side-channel to exchange information with your server using alternative
methods such as HTTP API or websocket. For this you will need a server side
application and the details described in the previous chapter can be applied.
In case if you have some built-in
application or script then a preferred method to exchange information between
the server and the webphone is the usage of extra SIP headers (which can
be easily sent/extract on your SIP server and also by the webphone). For more
details see the customsipheader parameter
and the setsipheader/getsipheader
API’s.
Integration with the SIP server API is
also possible by using the links parameters. This is
useful for things like balance display, server side contact list, SMS, recharge and others.
This section
is for JavaScript developers. You can use this webphone also without any
JavaScript skills:
·
If you don’t have any programming
skills: customize and
use the included turn-key templates (for example the softphone.html or click2call.html)
on your website.
·
If you are a server-side developer
not comfortable with JS: take advantage of the server
integration capabilities
Developers can use the webphone as an
SDK (JavaScript SIP library) to create any custom VoIP solution,
standalone or integrated in any webpage or web application.
First of all you should download
and deploy the webphone on your webserver (copy the webphone folder to your web server).
You can also launch it from local file
system on your dev environment (works with some limitations), but the best is
if you use it from a secure (HTTPS) webserver.
Notes:
Requirements:
Basic HTML and JavaScript
knowledge is required to work with the webphone to create custom solutions.
You will also need a web server and a SIP account.
See more details here.
Settings:
Once you deployed the webphone, you
will have to adjust the settings. At least the “serveraddress”
parameter must be set.
The library parameters can be preconfigured in webphone_config.js, changed
runtime from JavaScript, passed by URL parameters or set dynamically by any
server side script such as PHP, .NET, java servlet, J2EE or Node.js.
Frameworks:
The webphone doesn’t require any extra
client or server side framework (it is a client side VoIP implementation which
can be used from simple JavaScript) however you are free to use your own
favorite framework or libraries to interact
with the web phone (for example use with jQuery on the client side or integrate
into your PHP/.ASP/.NET/J2EE/NodeJS or other server side framework or use it
straight without any frameworks involved).
Demo:
The downloadable demo version has some limitations to disable
commercial usage, however if your development/test process is affected by these
then you can request a
trial from mizutech with all demo limitation removed.
The public JavaScript API can be found
in "webphone_api.js" file, under global javascript namespace
"webphone_api".
Just include the "webphone_api.js" to your project or html
and start using the webphone API.
The API reference can be found here.
Make sure to call any API function only
after the webphone completely initializes itself (the onAppStateChange callback was fired with the “loaded” event).
Many functionalities can be controlled by both the parameters and by the API.
When you need some persistent global behavior then you might use the
parameters, otherwise use the API if you need more control (for example toggle
a function at runtime or apply it only in some circumstances such as for a
single call only or manage multiple simultaneous
calls differently). For example you can use the voicerecupload
parameter if you need all calls to be recorded or use the voicerecord() API to record only some
calls (or part of the calls). Another example is the customsipheader
parameter vs the setsipheader() API.
Follow these steps to get started:
1
Download and
deploy the webphone
3.
Include the webphone to your
project by adding/importing the webphone_api.js
to your project
For HTML add the following line: <script
src="webphone_api.js"></script>
4.
Create any user
interface in HTML/CSS (or any other
framework capable to bind to JavaScript) if you need something from scratch.
Otherwise you can use, modify or start with one of
the html included in the webphone package: the softphone.html, the click2call.html or the examples in the samples folder.
5.
Configure the webphone via its parameters. This can be done in multiple ways (but it is enough
if you use one method only):
a.
by using webphone_api.setparameter() API from JavaScript once the webphone is loaded
b.
by setting static parameters in
the webphone_config.js file
c.
other methods described here
6.
Use the webphone API from your user interface controls (such as webphone_api.register () from your CONNECT button or webphone_api.call () from your CALL button)
7.
Handle the webphone state machine
(call state) by using the onCallStateChange and other callbacks (modify your user interface based on the webphone
state, such as displaying “Connected” when the webphone is registered or
displaying a “Incoming call from X. Accept/Reject” message on incoming calls)
8.
Consult the parameters, the API, the examples in the samples folder and other parts of this documentation for more details
There are 3 basic things which you
have to do while working with the SIP SDK:
1.
Set parameters:
There is a long list of parameters that you can set to configure the
webphone after your needs (but only a few really important).These can be set
statically in the webphone_config.js files, dynamically from your code using
the setparameter API or with other methods as described at the beginning of the
parameters
chapter.
2.
Call API
functions: You can interact with the webphone by calling its API. For example you can initiate a
call with the call function.
3.
Process the
events: Handle the callback notifications according to your application logic. The most important
is the onCallStateChange callback from where can update your user interface
from there as required.
Note:
You can use the webphone also without point 2 and 3, bye just configuring a
html shipped with the webphone (for example the softphone.html).
Also even if you use point 2 (API), for very simple apps you might not need to
watch for events at all (For example to make blind calls to a destination).
A minimal
implementation (a simple VoIP call) can be achieved with less than 5 lines of
code on your website. See the minimal_example.html (found in the webphone
package samples folder).
Example:
<head>
<!-- Include the
webphone_api.js to your webpage -->
<script src="webphone_api.js"></script>
</head>
<body>
<script>
//Wait until the webphone
is loaded, before calling any API functions
webphone_api.onAppStateChange(function (state)
{
if (state ===
'loaded')
{
//Set parameters (Replace
upper case worlds with your settings)
//Alternatively these can
be also preset in your webphone_config.js file or passed as URL parameters
webphone_api.setparameter('serveraddress',
SERVERADDRESS);
webphone_api.setparameter('username',
USERNAME);
webphone_api.setparameter('password',
PASSWORD);
//See the “Parameters”
section below for more options
//Start the webphone
(optional but recommended)
webphone_api.start();
//These API calls below
actually should be placed behind separate functions (button clicks)
//Make a call (Usually
initiated by user action, such as click on a click to call button. Number can
be extension, SIP username, SIP URI or mobile/landline phone)
webphone_api.call(NUMBER);
//Hang-up (usually called
from “disconnect” button click)
webphone_api.hangup();
//Send
instant message (Number can be extension, SIP username. Usually called from a
“send chat” button)
webphone_api.sendchat(NUMBER,
MESSAGETEXT);
}
});
//You should also handle events from the webphone and change your GUI
accordingly (onXXX callbacks)
</script>
</body>
See the html files in the webphone/samples folder for more examples.
o a very simple but functional basic example can be
found in the webphone package: basic_example.html
o as a better example, see the tech demo page
(techdemo_example.html / techdemo_example.js) or the api_example.html
o click2call.html is a ready to use click to call
implementation
o softphone.html implements a fully features browser
softphone (this can be found in the webphone root folder, not in the samples
folder). You might choose to extend this skin instead of creating your own from scratch (in case if your goal is to
create a complex dialer based solution).
You can also try the same examples from
our online demo.
You are free to use/modify any of these
files and adjust it after your needs or create your own solution from scratch.
For beginners we would recommend to
start with the “basic_example.html “, “api_example.html “ or “techdemo_example”
and modify/improve it after your needs.
If you need something ready to use,
than just use the “softphone.html” (this can be also customized with the many
webphone parameters or by changing the html/css/js files)
Most of the traditional VoIP
functionalities (in/our calls, chat, call divert) can be handled very easily
with the webphone, however some advanced features might require special care if
you wish to interact with them.
Lots of things can be achieved by the
webphone parameters, without the need of any programming effort.
Here are some examples for advanced
usage:
o settings/auto-provisioning: it can be done easily
with the setparameter API but you
might have special needs which would require to pass the parameters in a
special way. See the beginning of the parameters section for the possibilities and some more in the FAQ.
o multiple lines: handled automatically but you might
handle it explicitly if required for your project
o low-level engine messages:
this is only for advanced users and rarely needed to intercept these messages.
You might use the onEvent
callback for this but it is recommended to use the other high level events such
as the onCallStateChange to handle
the web SIP state machine
o low-level interaction with the native engines: if
somehow you have some extra requirements which is not available with this
high-level API then you might use the low-level jvoip API with the NS and Java engines
o dtmf, call transfer, hold, forward: we took special
care to make these as simple to use as possible so all of these can be handled
by a single API call
o voice call recording: just set the voicerecupload parameter or use the voicerecord API from Java Script
o conference: handled automatically by default via a
single API call but optionally you might implement some specific user interface
to display all parties
o parameter encryption/obfuscation: usually not
required since you are working with them in the otherwise secure user session,
but if you wish to use it then it is described here
o video: you must provide a html element where the
video have to be displayed and manage this GUI accordingly: <div
id="video_container"></div>
o chat, sms: these also requires some extra user
interface to send the messages and display the call history
o manipulating SIP messages: requires some VoIP/SIP
skills if you need to interact this way with your VoIP server and you can use
the setsipheader/getsipheader
API’s
o create a native application by using the webphone
from a WebView
Note: all of these are also implemented
in the “softphone” skin which is included with the webphone so you
might use/modify this skin if you need a complete softphone like solution
instead to develop your own from scratch (if you don’t have specific
requirements which can’t be handled by customizing the softphone skin)
For more details regarding custom
development, see the “JavaScript API” section
below in this documentation.
The webphone parameters can be
used to fully customize the webphone behavior including SIP settings, media settings,
user interface settings, for example parameters like the SIP server domain,
authentication, called party number, autodial and many others.
Most of the settings are optional
except the "serveraddress" (but also this can be provided at
runtime via the API).
The other important parameters are the
SIP user credentials (username, password) and the called number (callto)
which you can also preset (for example if you wish to implement click to call)
however these are usually entered by user (and optionally can be saved in local
cookie for later reuse).
The webphone parameters can be set in
multiple ways (statically and dynamically)
to allow maximum flexibility and ease the usage for any work-flow.
Use one (or more) of the following methods for the webphone configuration:
·
Preset the settings in the "webphone_config.js" file. This should be used for parameters which
are expected to not change at runtime, such as the serveraddress parameter.
·
Use the setparameter() API call from JavaScript. For most parameters the setparameter function
must be called from the onAppStateChange callback “loaded” event. Never
sooner (API functions, including the setparameter, works only after the
“loaded” event was triggered in onAppStateChange).
·
Changing the parameters by using
the webphone_api.parameters['paramname'] = 'value'
format is NOT recommended because parameters changed in this way can’t be
overwritten later by the setparameter() API.
·
Webpage URL query string (The webphone will look at the
embedding document URL at startup. Prefix
all keys with “wp_”. For example &wp_username=x or any other parameter
specified in this documentation)
·
Via the scurl_setparameters settings which can load the parameters from your
server side application (This will be
called after the onAppStateChange “started” event and can be used to provision
the webphone from server API. The answer should contain parameters as key/value
pairs, ex: username=xxx,password=yyy)
·
Cookies (prefix
all keys with “wp_”. For example wp_username)
·
Web session
variables (PHP example)
·
SIP signaling
(sent from server) with the x-mparam header (or x-mparamp if need to persist).
Example: x-mparam=loglevel=5;aec=0
·
Auto-provisioning: the browser
phone is also capable to download it’s settings from a config file based on
user entered OP CODE (although this way of configuration is a little bit
redundant for a web app, since you can easily create different versions of the
app –for example by deploying it in different folders- already preconfigured
for your customers, providing a direct link to the desired version instead of
asking the users to enter an additional OPCODE)
·
User input: You can let the user
to modify the settings. For example to enter username/password for SIP
authentication (For example using the softphone skin most of the settings can
be specified by the users at login/settings screens, which might overwrite
server side settings loaded from the webphone_config.js file if any)
·
Also see here and here
Any of these methods can be used or
they can be even mixed.
The quick and easiest way to start
is to just set all the required parameters in the webphone_config.js file. For
example:
webphone_api.parameters = {
serveraddress: 'voip.mizu-voip.com', //your
SIP server domain:port or IP:port
username: 'webphonetest1', //the
username is usually specified by the enduser and not need to be set globally
here
password: 'webphonetest1', //the
password is usually specified by the enduser and not need to be set globally
here
displayname: 'John
Smith', //optional display name, usually specified by
the enduser and not need to be set globally here
brandname: 'BestPhone', //your
brand name
rejectonbusy: true, //will
reject incoming call if user already in call
ringtimeout: 50000,
//disconnect the call after 50 sec on no answer
loglevel: 5 //enable
detailed logs
//no comma is needed after the
last parameter
};
Usually you might set some parameters in the above webphone_config.js
file (the common static/global parameters applicable for all users which
doesn’t need to be changes such as the serveraddress or proxy address), then
you might use one of the other methods to specify instance specific parameters
(for example ask the user credentials at login screen and set it as the
username/password parameters with the setparameter API).
Note:
·
For a basic usage you will have
to set only your VoIP server ip or domain name (“serveraddress” parameter).
The SIP username/password
are asked from the user with the default skins if not preconfigured.
The rest of the
parameters are optional and should be changed only if you have a good reason
for it.
·
Some parameters
(username/password, displayname) are usually set by the user via some user
interface (using the setparameter() API), however in some situation you might
hardcode them on the server side webphone_config.js file. For example if you
have some static IVR service and the caller user identity doesn’t matter.
·
All parameters can be passed as
strings and will be converted to the proper type internally by the webphone
browser plugin.
·
Most parameters are saved by the
webphone (in web storage and cookies) and reused at next sessions (but you can
always overwrite already stored settings or clear them by setting the value to
'NULL' or use different profiles).
·
Don’t remove or comment out
already set parameters because the old value might be already cached by the
browser webphone. Instead of this you should just set to 'NULL'/ 'DEF' or
its default value. Details here.
·
If you have changed
the parameters in the webphone_config.js then you might change its
jscodeversion parameter where you include it in your project, to avoid any caching and force a re-download by the browser.
For example: <script
src="webphone_config.js?jscodeversion=1234"></script>
·
Prefix parameter name with
“ucfg_” if it should prefer client side settings (otherwise server side settings
defined in the webphone_config.js will overwrite the client settings). Example:
ucfg_aec: 2
·
You can also clear the settings
with the delsettings API or force the webphone to forget old settings
with the resetsettings parameter. Details here.
·
Parameters can be also encrypted
or obfuscated. See the “Parameter security” section for the details.
The most important parameters are
the followings:
·
serveraddress (your SIP server domain or IP:port, usually set statically
in the webphone_config.js)
·
username/password (SIP account details, usually
entered by the endusers and passed to the webphone with the setparameter
API or by URL)
Other important parameters you might
need to set are the followings:
·
sipusername (sometimes required for authentication or for Caller-ID
purposes)
If your SIP server
requires a different auth vs user id, then you can set the user id with the username
parameter and the authorization username with the sipusername. You can also use
it to configure a Caller ID (different from the auth user name) if your SIP server
accepts a different username/sipusername.
With other words:
o The username will be used as user id
(extension number / Caller–ID)
o The sipusername parameter will be used
as the authentication username
o If only one is set, then it will be
used for both the above purposes
·
displayname
(usually from user input –enduser full name)
·
proxyaddress (only if you have an outbound proxy different from your SIP
server address)
·
register
(you might set it to 0 if no registration is not required)
·
other sip
account related settings (change any only if needed for your goals)
·
engine priority (only if you prefer a specific engine for some special
reason, otherwise the “best” possible engine will be used automatically)
·
webrtcserveraddress (if you have your own WebRTC gateway or your softswitch has built-in
WebRTC capabilities, set this to your websocket listener URL)
·
codec and prefcodec (no any changes are recommended for
these since the webphone is capable to auto negotiate the “best”
possible codec to
use, but you might change it if you have some special needs)
·
other engine
related settings
(change any only if needed for your goals)
·
callto and autoaction (in case if you wish to make an
action at startup which otherwise can be done also with the API)
·
other call divert
related settings
such as autoaccept,
callforwardonbusy and others (you might use the API instead for these tasks)
·
user interface related settings if you use the softphone
skin (the
softphone.html, included with the webphone)
There is no need to any “fine-tuning” of
the parameters.
The webphone has a long list of configurable settings (listed below)
for maximum flexibility, however it is not recommended to change any parameter
unless strictly required to achieve your project goals. All parameters has
meaningful optimal value by default or it is auto-negotiated regarding
server/network/environment and unnecessarily altering the settings might result
in sub-optimal behavior.
Credentials and other basic SIP
parameters:
(string)
The address of your SIP server
(domain or IP + port), usually the same with your SIP domain.
It can be specified as IP address or
as A or SRV domain name.
Specify also the port if your server
is not using the default 5060; in this case append the port after the address
separated by colon.
Examples:
mydomain.com (this will use the default SIP port 5060)
sip.mydomain.com:5062
10.20.30.40:5065
10.20.30.40 (this will use the default SIP port 5060)
This is the single most important
parameter for the webphone (along with the username/password but those can be
also entered by the user).
Default value is empty.
Note:
·
Sometime you might have to set
also the SIP
proxy address and the transport parameters (depending on your server side
requirements). Read here for
more details.
·
If you are using a (sub)domain as
your SIP server address, then we recommend to always set it’s DNS A record also
(not just the SRV record) for full WebRTC compatibility, since browsers might not
ask for SRV records.
·
If your server address is
different from your SIP domain, then you might set the SIP domain as the realm parameter.
·
If you SIP server doesn’t allow
UDP for the SIP signaling then set the transport
parameter accordingly.
(string)
This is the SIP account user name
(User ID / Extension ID).
Default value is empty.
Note:
o Technically speaking, this is the user
part of the Address of Record (AOR), sent in the “From” and “Contact” SIP
headers.
It is used for authentication (if no sipusername parameter is set) and as A
number/Caller-ID for the outgoing calls. Other users can make call to this
endpoint by dialing this value. Some SIP service providers use a globally
routable telephone number (DID) as the SIP username.
o The username/password parameters are
usually supplied by the user (via some user interface and then calling the
setparameter API), however in some cases you might just set it statically in
the webphone_config.js file (when caller user credentials doesn’t matter). See
more here.
In case if you set it “statically” in the webpone_api.js and you are using the
softphone skin (softphone.html) the username will not be asked from the enduser
at login.
o Even if you don’t need a username
and/or your server accepts all calls without authentication, you must set the
username to some value: the “anonymous” username might be used in this case.
o If you set the username setting to
“Anonymous” then the username input box will be hidden on the “softphone” skin
settings and login screens.
o If you wish to set a separate
caller-id you can use this parameter to specify it and then use the sipusername parameter to specify the username used for authentication as
specified in SIP standards. However please note that most SIP server can treat
also the below mentioned “displayname” parameter as the caller-id so the usage
of separate username/sipusername is usually not necessary and confusing. See
more details here.
o If the showusername parameter is set
to 2 then both the username and the caller-id input will be displayed on the
softphone skin login page.
o For maximum compatibility with
third-party software and services, avoid using special and non-ASCII
characters.
(string)
This is the username used for SIP
digest authentication (Auth User Name or Authorization Name).
It is an optional setting which
should be set only if your SIP server requires a different username for
authentication.
If your SIP user name and auth user
name are different, the proceed like this:
·
Set the webphone username to the SIP user name (also known as
extension number or the user part of the AOR)
·
Set the webphone sipusername parameter to the Auth user name (also
known as Auth ID or PIN in some systems)
If only one of the above are set
(username or sipusername) then the same will be used for both purposes (both as
user id and authorization user name)
You need to set this if only the username parameter is not the same with the auth
user name (when you need to use a different caller id and username for
authentication).
o If this is not set, then the username parameter will be used for both the
caller-id (public-identity sent with the From
SIP header) and authorization (private identity sent with the Authorization SIP header).
o If this is set, then this parameter
will be used for authorization and the username parameter will be used for caller ID.
o If you expect the @ character (full
SIP URI) in the sipusername, then set the handleusernameuri parameter to 0 to
prevent extracting the domain from it on the softphone skin
Default value is empty.
See more details here and here.
(string)
This is the SIP account password
used for authentication.
Default value is empty.
Note:
o Make sure to never hardcode the
password in html or set it via insecure http. See more details here about
security.
o You can use the webphone also without
password (if not using via server or your server doesn’t authenticate the
users). In this case you can set the password to any value since it is supposed
that it will not be required for calls or registrations.
o Usually you ask the password from the
endusers and set it at runtime with the setparameters API. In case if you set
it “statically” in the webpone_api.js and you are using the softphone skin
(softphone.html) the password will not be asked from the enduser at login.
o For the softphone user interface you
can also set hidepassword and pwdautocomplete parameters.
o If your IP-PBX accept blind
registrations and/or calls then the value of the password doesn’t matter (it
will not be used anyway)
o If you set the password setting to
“nopassword” then the password input box will be hidden on the “softphone” skin
settings and login screens.
o If your IP-PBX doesn’t require
registrations or you are not using any server then you should set the “register” setting to 0.
o SIP passwords are always case sensitive.
(string)
Optional SIP display name.
Specify default display name used in
“from” or “contact” SIP headers.
This is often sent to peer as Caller
ID when placing a call (if not overwritten on the server side).
Default value is empty (which means that only the “username” field will be
sent to the peers).
Note:
This has nothing to do with the text displayed by the
webphone skin. This is a SIP parameter to specify the display name sent to the
others with call setup.
See more details here.
(string)
Optional parameter to set the SIP
realm (logical SIP domain) if not the same with the serveraddress.
Rarely required. (Only if your VoIP
server has different realm setting as its domain and it strictly enforces that
realm for authentication)
Default value is empty. (By default the serveraddress will be used without
the port number)
(string)
Outbound SIP proxy address
(Examples: mydomain.com, proxy.mydomain.com:5065,
10.20.30.40:5065)
Leave it empty if you don’t have a
stateless proxy. (Use only the serveraddress parameter)
Default value is empty.
Note:
Set to “NULL” if you already set it before (to a wrong value) and wish to clear
it.
If the showproxyaddress parameter is
set to 2 then the proxy address input will be displayed on the softphone skin
login page.
(number)
With this parameter you can set
whether the softphone should register (connect) to the sip server.
0: no (the webphone will not send
REGISTER requests)
1: auto guess (yes if
username/password are preset, otherwise no)
2: yes (and must be registered
before to make calls)
Default value is 1.
Related
parameters: autostart
(start webphone with page load), appengine_startat (native engine launch),
startsipstack (NS engine specific), autologin (softphone skin specific),
mustconnect (if set to true the webphone will not allow any calls before
registered; default is false), regtimeout (register no answer timeout for the
WebRTC engine in milliseconds; default is 6000; 0 means no retry).
(number)
Registration interval in seconds (used
by the re-registration expires timer).
Default value is 120 or 300 depending
on the circumstances.
This is important for SIP servers to find out unexpected termination of
the webphone application or webpage such as killing the browser, power loss or
others (so the server will know that the client is no longer alive if this time
is expired, but no new re-registration were received from the client).
Note: we don’t recommend to set the re-register interval below 30
seconds (it just causes unnecessary server load; below 30 seconds most of the
SIP servers will not decide anyway and some servers doesn’t accept such short
re-registration periods). Also you should not set it longer than 3600 (one
hour).
Library, engine, transport, SIP,
media, DTMF, presence and BLF related settings:
By default the webphone will choose
the “best” suitable engines automatically based on OS/browser/server support.
This algorithm is optimized for all OS and all browsers so you can be sure that
your users will have the best experience with default settings, however, if you
wish, you can influence this engine selection algorithm by setting one or more
of the following parameters:
·
enginepriority_java
·
enginepriority_webrtc
·
enginepriority_ns
·
enginepriority_flash
·
enginepriority_app
·
enginepriority_p2p
·
enginepriority_accessnum
·
enginepriority_nativedial
·
enginepriority_otherbrowser
Possible values:
0: Disabled (never
use this engine)
1: Lower (decrease
the engine priority)
2: Normal (default)
3: Higher (will boost
engine priority)
4: Highest (will use
this engine whenever possible)
5: Force (only this
engine will be used)
Example:
-if you wish to prioritize the NS
engine, just set: enginepriority_ns: 3
-if you wish to prioritize the
WebRTC engine, just set: enginepriority_webrtc: 3
-if you wish to avoid WebRTC engine,
just set: enginepriority_webrtc: 1
-if you wish to force the WebRTC
engine only, just set: enginepriority_webrtc: 5
Best practices:
-You should not change
the engine priorities unless you have a good reason (one of the main strength
of the webphone is automatic optimal engine selection based on circumstances, so there should be
rare cases when you might need to adjust this manually)
-Even if you have a
favorite engine, you should not force it or disable the others. Just set your
favorite engine priority to 3 or 4. This way even endusers which doesn’t have a
chance to run your favorite engine might be able to make calls with other
engines.
-Even if for some reason
you don’t like an engine, don’t entirely disable it, just lower its priority
(set its enginepriority to 1 instead of 0). This means that the webphone will
pickup the engine only if there is no -any other alternatives and having the
webphone working with an unwanted engine is much better then not working at all
-It is recommended to
set engine priority from static settings (for example in the webphone_config.js
file) and not at runtime. In case if you have to change the engine priorities
at runtime using the setparameter() API, then you must do it only from the
onAppStateChange “loaded” event, not sooner or later.
The engines also have a
built-in default priority number assigned, which can range from 0 to 100 and
can be changed with the enginedefpriority_ENGINENAME settings.
Default values:
enginedefpriority_java:
32
enginedefpriority_webrtc: 20
enginedefpriority_flash: 13
enginedefpriority_ns: 30
enginedefpriority_app: 10
enginedefpriority_p2p: 5
enginedefpriority_callback: 5
enginedefpriority_nativedial: 3
You should not touch these
values!
Note:
o
You can disable
the NS engine for linux by setting the linnsengine
parameter to false.
o
You can disable
the NS engine for MacOS by setting the macnsengine
parameter to false.
o
You can disable
the linux NS engine for windows by setting the winlinmacnsengine
parameter to false (this is for test only
and defaults to false).
o
You can disable
the NS engine for Windows only if you completely disable the NS engine by
setting enginepriority_ns to 0.
(string)
WebSocket server URL for WebRTC.
Optional setting to indicate the
domain name or IP address of your websocket service used for WebRTC if any
(your server address and websocket listen port).
The following URI format can be
used:
protocol:address:port/path
Where:
The protocol can be ws
(unsecure websocket) or wss (secure
websocket)
The address can be an IP address or a (sub)domain name
The port is where the websocket is listening and it
must be specified if not 80
The path part must be set if your server require it
(For example Asterisk requires the “ws” path). Check your server documentation
for the exact format.
Examples:
ws://mydomain.com
ws://10.20.30.40:5065
wss://subdomain.mydomain.com/anypath
wss://asterisk.mydomain.com:8089/ws
wss://sip.mydomain.com:8080
Default value is empty (which means
auto service discovery and if no webrtc service found then the mizu webrtc
service can be used if accessible).
Note:
o
You can verify
if the address you have set is correct by trying a simple websocket connect
with some tool.
o
Latest browsers
require secure websocket (wss), otherwise media (call recording) permissions
will be denied. You will need to install an SSL certificate for your WebRTC server
for this and set this parameter with the domain name (not IP address). This is
needed only if your VoIP server is WebRTC capable or you have your own WebRTC
to SIP gateway. Otherwise no changes are required.
o
Multiple servers
can be set separating the addresses by comma. In this case the webphone will
use the closest by default (with fastest response time) and it is capable to
failover to other server/gateway
o
By default the
webphone might use our WebRTC-SIP service if your SIP server has a public IP
(accessible over the internet) AND the webphone auto selects the WebRTC
engine AND you haven’t set your own websocket listener for webrtc. This
is a free service tier offer by us for your convenience, but its usage is
optional and the webphone works also without this service.
More details about
webrtc can be found in the FAQ: here and here.
(string)
Optional setting to indicate the
address (domain name or IP address + port number) of your flash service if any
(flash media + RTMP) which might improve the SIP availability in some exotic or
outdated browsers where the other engines such as WebRTC, Java or NS are not
available.
If not set, then the mizu flash to
sip service might be used (rarely used in normal circumstances and it can be
also disabled if for some reason you always wish to avoid it).
Format: yourdomain.com:rtmpport
Example: 10.20.30.40:5678
Default value is empty.
(string)
STUN server address in address:port
format (RFC 5389)
You can set to “NULL” to completely
disable STUN. Usually STUN is not required at all, however in some
circumstances (mostly depending on your SIP server and outbound trunk
capabilities) it might help to avoid unnecessary RTP routing (direct peer to
peer RTP routing bypassing your server).
Examples:
11.22.33.44:3478
mystunserver.com:3478
NULL
By default (if you leave this
setting unchanged) the webphone will use the Mizutech STUN servers (unlimited
free service for all webphone customers). You can change this to your own STUN
server or use any public server if you wish.
Note:
If you set an incorrect STUN server, then the symptoms
are extra delays at call setup (up to “icetimeout”).
Instead of using the stunserveraddress parameter, you
might use the ice parameter to configure both stun and turn together.
(string)
TURN server address in address:port
format (RFC 5766)
You can set to “NULL” to completely
disable TURN.
Examples:
11.22.33.44:80
mystunserver.com:80
NULL
If your server is capable to route
the RTP, then TURN is usually not required at all.
TURN is used mostly only with WebRTC
and might be useful only if the webphone cannot send the media directly to the
peer (which is usually your VoIP server) and your server doesn’t support TCP
candidates. For example if all UDP is blocked or only TCP 80 is allowed or you
need peer to peer media via TURN relay.
By default (if you leave this
setting unchanged) the webphone can use the Mizutech TURN servers. If you wish,
you can deploy your own TURN server using the popular open source coturn server. The MizuTech WebRTC to SIP gateway also has its own built-in TURN
server and there is no
need to set this parameter.
Note: Instead of using the turnserveraddress
parameter, you might use the ice parameter to configure both stun and turn
together.
(string)
Any TURN URI parameter. Required only if the turnserveraddress is set.
Example: transport=tcp
(string)
Username for turn authentication. Required only if the turnserveraddress is set.
(string)
Password for turn authentication. Required only if the turnserveraddress is set.
Note: in case if you are using the mizu server or
gateway then don’t bother securing the turn password as the server will use
also other mechanisms to reject unauthorized TURN requests.
(string)
Instead of using the above STUN and
TURN parameters, you can use this ice parameter in the following format:
ice: ' [{
url:"stun:stun.l.google.com:19302"}, { url: "turn:user@myturnserver.com",
credential: "myTurnPassword"}] '
or
ice: ' [{
url:"stun:stun.l.google.com:19302"}, { url: "turn:myturnserver.com:PORT",
username: "myTurnUsername", credential: "myTurnPassword"}] '
In case if you don’t use WebRTC or
you are using mizutech WebRTC-SIP gateway (MRTC) then there is no need to set
any ice/stun/turn parameter as they are discovered automatically (service
provided by the gateway). Otherwise the default in this case is:
ice: '[{
url:"stun:rtc.mizu-voip.com:8090"}, {
url:"turn:rtc.mizu-voip.com:80?transport=tcp","username":"mzturnusr","credential":"***"}]'
In case if you configured the
webrtcserveraddress parameter to point to your WebRTC server or gateway
websocket listener, then you might reconfigure this ice parameter if you also
have stun/turn service (you might use the coturn).
You might also configure any other
stun service. A list of public stun servers can be found here or here.
There are no public free turn
servers (as turn is routing the media also and not cheap to host).
You can also set multiple STUN and
TURN servers if you wish.
(number)
Timeout for ICE address gathering
(STUN/TURN/others) in milliseconds.
Default is 2000 (2 seconds).
You might increase in special
circumstances if you are using some slow STUN/TURN server or decrease if peer
address is public (like if your SIP or WebRTC server is on public IP always
routing the media, so calls will work also without STUN).
(number)
STUN/TURN usage on local LAN. This
setting helps to avoid unnecessary STUN/TURN connections, negotiations and call
setup delay.
Possible values:
0: no (will set the TURN and STUN
servers to null, regardless of user settings and configurations)
1: STUN only (keep using STUN, but
no TURN)
2: use both STUN and TURN (use STUN
and TURN also with local servers)
Default: 1
(number)
Check rport in SIP signaling
(requested and received from the SIP server by the VIA header)
0=don’t ask (rtport request will not
be added to the VIA header)
1=use only for symmetric NAT (only
when it is sure that the public address will be correct)
2=always (always request and use the
returned value except if already on public ip)
3=request even on public IP
(meaningless in most cases)
9=request with the signaling, but
don’t use the returned value (good If you want to keep the local IP and for
peer to peer calls)
Change to 0 or 2 only if you have
NAT issues (depending on your server type and settings)
(You might adjust also the
use_fast_stun parameter if you change the use_rport)
Default is 1
(number)
Fast stun request on startup.
-1=force private address (if the client
has both private and public IP, than the private IP will be sent in the
signaling)
0=no
1=use only for stable symmetric NAT
2=use only if both tests match even if
not symmetric (recommended)
3=use for symmetric NAT even if only
one match
4=always
5=use even on public IP
Change if you have NAT issues
(depending on your server type and settings)
(You might adjust also the use_rport
parameter if use_fast_stun is changed)
Default is 2
(number)
Specify to enable or disable peer to
peer signaling routing feature.
Possible values:
o 0: no (direct user to user routing
fully disabled forcing the call to travel via upper SIP server –will also add
X-P2P: no header)
o 1: yes (full p2p direct signaling
enabled when possible)
o 2: proxy (might go over proxy socket
processing. Actually this is a special option between no and yes where the
signaling might be forwarded by proxy but might not sent directly or via upper
server –will also add X-P2P: proxy header)
o 3: process (might go over proxy with
full endpoint processing. Actually this is a special option between no and yes
where the signaling might get fully processed by proxy but might not travel via
upper server –will also add X-P2P: process header)
Default is 1.
You might set to 0 (disable) in case if the call
signaling has to reach your server (for example if you are using ring groups to
fork the calls, or you wish to record the calls on your SIP server or if for
billing purposes it is important that your server see also the enduser to
enduser calls).
Otherwise with the default 1 value the webphone might
contact directly the other party or the WebRTC gateway (in case of the WebRTC
engine) might route the call directly between endusers, thus saving your server
resources and shortening the network path.
Note: this might add a X-P2P: no/process/proxy/yes
header to the SIP signaling notifying the gateway/server if routing have to be
forced/ignored.
(number)
Fast ICE negotiations (for p2p rtp
routing):
-1: suggest server side media
routing (X-P2PM: 1)
0: no (set to 0 only if your server
needs to always route the media)
1: auto
2: yes
3: always (not recommended)
Default is 1
Note:
If set to 1 or 2 then stun should not be disabled
Old parameter name was p2prtp.
Specify to enable (1,2) or disable (0,-1) peer to peer
media routing feature (direct RTP routing). You might set to -1 (disable) in
case if the call media (RTP) must be routed through your SIP server (for
example if you wish to voice record the calls on your server). Otherwise the
webphone might route the media directly between webphone instances thus saving
your server resources and shortening the network path. Please note that the
media might be routed directly between the endpoint even if this parameter is
set to 0, according the SDP and ICE negotiation (this can be influenced by your
SIP server configuration by the usual NAT and RTP related settings globally or
by extension).
Default is 1 (p2p for media enabled routing encrypted
RTP directly between the endpoints when possible).
(number)
Try to auto-detect webrtc address if
not set (if the active SIP server has built-in WebRTC capabilities)
0: no
1: yes
Default is 1.
(number)
Specify how to launch the app engine
(native dialer / native softphone) if the rare events when it might be required
(if no any other engine can be used).
1: at start
2: auto (default)
3: at call attempt
(string)
Android native softphone download
URL if any. (Optional setting to allow alternative softphone offer on Google
Play).
Note: Android browsers has support
also for WebRTC so this might be selected only with old phones or if you
disable WebRTC.
Default is empty (which means the
default app).
(string)
iOS native softphone download URL if
any. (Optional setting to allow alternative softphone offer on Apple App
Store).
Old Safari browsers (up to v.11)
under iOS doesn’t offer any plugin for VoIP so the webphone can use its native
softphone (will be auto provisioned from your webphone settings).
Default is empty (which means the
default app).
(string)
Specify the URI handler to be
registered to launch native apps if needed.
The defaults are: sip, tel, webphone
You might reconfigure it if you use
some other third-party app that is triggered for other protocol. For example: app_protocol: “myapp”
(string)
Set this if your IP-PBX has an
access number where users can call into from PSTN and it can forward their call
on VoIP (IVR asking for the target number).
This can be used when no other
engines are working (no suitable environment, no internet connection).
Default is empty.
(string)
Set this if your server has a
callback access number where users can ring into and will receive a call from
your server (possibly with an IVR which might offer the possibility to specify
the destination number via DTMF).
This can be used when no other
engines are working (no suitable environment, no internet connection) and it is
very useful in situation where call from the server is cheaper than user call
to server.
Default is empty.
(string)
This will overwrite the default
User-Agent setting.
Do not set this when used with mizu
VoIP servers because the server detects extra capabilities by reading this
header.
Default is empty.
(string)
Set a custom sip header (a line in
the SIP signaling) that will be sent with all messages. Can be used for various
integration purposes and usually has a key:val format. For example: myheader:myvalue.
Default is empty.
Note:
Custom SIP headers should begin with
“X-“ to be able to bypass servers, gateways and proxies (For example: X-MyHeader: 47).
You can add more than one header,
separated by semicolon or “CRLF” in case if you must use semicolon in the value
(For example: customsipheader: 'x-key1:
val1;x-key2: val2',).
You can also use the setsipheader API call at runtime. It can be used
instead of this parameter or you can use both together (both this parameter and
the API)
(string)
Set custom SIP Contact URI
parameters for REGISTER and INVITE requests.
Default is empty.
Set to 'NULL' to clear.
Example:
If the original contact line looks like Contact:
<sips:1111@any.invalid;transport=wss>;expires=180
and you set the contact_uri_parameters
to 'a=1;b=2',
then the contact will be modified to: Contact:
<sips:1111@any.invalid;transport=wss;a=1;b=2>;expires=180
(string)
Set custom SIP Contact parameters
for REGISTER and INVITE requests.
Default is empty.
Set to 'NULL' to clear.
Example:
If the original contact line looks like Contact:
<sips:1111@any.invalid;transport=wss>;expires=180
and you set the contact_parameters
to 'x=1;y=2',
then the contact will be modified to: Contact: <sips:1111@any.invalid;transport=wss>;x=1;y=2;expires=180
(number)
Specify whether the settings have to
be downloaded from a central config server.
Possible values:
0: no
1: auto (if not ip or domain was entered)
2: yes
(number)
Specify whether calls should fail or
succeed also without a microphone device.
-1: disable microphone recording
(call will use only playback from remote)
0: no (calls with be allowed even if
client doesn’t have any microphone audio device)
1: with warning (call will be
allowed but a warning message might be displayed for the user; sdp might be
fixed; call might be reloaded with audio only)
2: yes (calls might fail if user
doesn’t have a microphone device)
3: same as 1 but if incoming video
call then it will retry with audio only
Default is 1.
If your device doesn’t have
microphone or doesn’t need microphone recording at all, you should also set the
useaudiodevicerecord parameter to false. Old parameter name was checkmicrophone.
(number)
Use VoIP optimizations on windows
(WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE). This will also enable audio ducking
(audio focus: auto lowering the volume for other processes while the webphone
is in call).
0: No
1: Yes
2: Force
Default value is 1.
Set to 0 if you encounter audio
volume issues, especially for multi-calls.
(number)
Check if audio device is muted or
volume settings are too low (and un-mute and/or increase volume if necessary).
0: no
1: at first run
2: always
Default value is 1
(number)
Enable background call listener.
If the WebRTC engine is used, this
means push notifications.
If you are using the NS engine on
Windows, your webpage can be started automatically on incoming calls if you set
this parameter to true.
When background calls is turned on,
the NS engine will listen continuously for incoming call and chat notifications
and will launch your website with the incoming session details if your page is
not already started by the user. This will enable incoming SIP calls even if
the browser is closed.
Possible values:
-1: auto
0: disable all incoming calls
1: enable incoming calls (while app
is running; no background listener)
2: enable also background calls
(WebRTC push or NS engine or android service)
Default is -1.
Note:
·
This has nothing
to do with the HTML5 notification support which can be configured with the incomingcallpopup parameter.
·
In case if you
need only NS engine background calls but not push notifications, then you might
set the enablepush parameter to 0 (possible values: -1: auto, 0: no, 1: yes).
·
The old
parameter was named backgroundcalls and it
is still supported as-is
Here you can read more details about
VoIP push notifications.
(number)
Transport protocol for the SIP
signaling.
-1: Auto detect
0: UDP (User Datagram Protocol. The
most commonly used transport for SIP)
1: TCP (signaling via TCP. RTP will
remain on UDP)
2: TLS (SIPS encrypted signaling)
3: HTTP tunneling (both signaling
and media. Supported only by mizu server or mizu tunnel)
4: HTTP proxy connect (requires
tunnel gateway or server)
5: Auto tunnel (automatic failover
from UDP to HTTP as needed if tunnel gateway or server is used)
Default is -1.
TLS related notes:
o To encrypt also the media, set the mediaencryption parameter to 2.
o When using TLS, you might need to
change the port in the serveraddress parameter (from the default 5060) to 5061.
For example: serveraddress: ‘yourdomain.com:5061’)
o WebRTC always uses full encryption.
When using WebRTC this parameter will mean the SIP transport protocol to be
used with your server as for WebRTC itself the transport is controlled by the
browser: http/https, websocket/secure websocket (ws/wss) and always encrypted
media (DTLS/SRTP).
(String)
Specify local IP address to be used.
This should be used only on devices
with multiple ethernet interface to force the specified IP.
Default is empty (autodetect)
Note: This setting is not applicable
for WebRTC (In case of WebRTC this is handled entirely by the browser internal
WebRTC stack)
(number)
Specify local SIP signaling port to
use.
Default is 0 (a stable port which is
selected randomly at the first usage)
Note: This is not the port of your
server where the messages should be sent. This is the local port of the
signaling socket (Usually UDP if you don’t explicitly set the transport to TCP)
Note: This setting is not applicable
for WebRTC (In case of WebRTC this is handled entirely by the browser internal
WebRTC stack)
(number)
Specify local RTP port base.
Default is 0 (which means
signalingport + 2)
Note: If not specified, then VoIP
engine will choose signalingport + 2 which is then remembered at the first
successful call and reused next time (stable rtp port). If there are multiple
simultaneous calls then it will choose the next even number.
Note: This setting
is not applicable for WebRTC (In case of WebRTC this is handled entirely by the
browser internal WebRTC stack)
(number)
NAT keep-alive packet send interval in
milliseconds.
Set to 0 to disable.
Default value is 28000 (28 sec)
(number)
Keep-alive interval for the WebRTC
websocket in milliseconds.
Set to 0 to disable.
Default value is 30000 (30 sec)
(boolean)
Send rtp even if muted (zeroed
packets)
Set to true only if your server is
malfunctioning when no RTP is received.
Default value is false.
(number)
Media encryption method
-1: auto guess
0: not encrypted
1: auto (will encrypt if initiated
by other party)
2: SRTP
Default is -1 which auto set to 1 if TLS transport is used, otherwise
will use 0/not encrypted
Note:
o With SRTP it is recommended to also
set the signaling transport to TLS.
o This parameter will not have effect
with the WebRTC engine since WebRTC calls are always secured using DTLS/SRTP
encryption for the media streams.
(number)
DTMF send method
0=disabled
1=SIP INFO method (out-of-band in SIP
signaling INFO messages)
2=auto (auto guess from peer advertised
capabilities)
3=INFO + NTE (not
recommended)
4=NTE (Named Telephone Events as
specified in RFC 2833 and RFC 4733)
5=In-Band (DTMF audio tones in the RTP
stream)
6=INFO + InBand (not
recommended)
Default is 2.
Note:
o When more than one method is used
(dtmfmode 3 or 6), the receiver might receive duplicated dtmf digits
o Received DTMF are recognized by
default in both INFO or RFC2833/ RFC4733
formats (no In-Band DTMF processing)
o DTMF messages can be sent from the
existing skin templates or using the dtmf API. Incoming dtmf messages are displayed
automatically on skins or can be cached with the onDTMF callback.
o
DTMF messages can be
also sent by adding it to the called number after a comma. For example if you
make a call to 123,456 then it will call 123 and then it will send dtmf 456
once the call is connected.
o If DTMF doesn’t work by default with
Asterisk, then we recommend to set the dtmfmode=info
configuration for the extensions used by the webphone
o WebRTC doesn’t support InBand DTMF
o If you are using the mizu WebRTC-SIP
gateway, you can set dtmf type for both inbound and outbound globally with the fs_dtmf_type_intern and fs_dtmf_type_extern
server side settings and also per user with the inbounddtmf
and outbounddtmf webphone parameters. The
out-bound is also handled automatically after the dtmfmode
setting (defaults to SIP info) and for in-bound both info and rfc2833 are
accepted by default.
o If gateway side WebRTC DTMF conversion
is required, you might also set the use_fast_ice
parameter to -1.
(number)
Specify whether the webphone should
generate local DTMF tone when DTMF is sent.
0=no
1=if one digit
2=always (also when multiple digits
are sent at once)
Default is 1.
(number)
Start to send media when session
progress is received.
0: no
1: reserved
2: auto (will early open audio if
wideband is enabled to check if supported)
3: just early open the audio
4: null packets only when sdp
received (NS only)
5: yes when sdp received
6: always forced yes
Default is 2.
(string)
Set your preferred audio codec. Will
accept one of the followings: pcmu,
pcma, g.711 (for both PCMU and PCMA), g.729, gsm, ilbc, speex, speexwb,
speexuwb, opus, opusnb, opuswb, opusuwb, opusswb
Default is empty which means the
built-in optimal prioritization.
By default the
engine will present the codec list optimized regarding the circumstances (the
combination of the followings):
·
available
client codec set (not all engines supports all codecs)
·
server
codec list (depending on your server, peer device or carrier)
·
internal/external
call: for IP to IP calls will prioritize wideband codecs if possible, while for
outbound calls usually G.729 will be selected if available
·
network
quality (bandwidth, delay, packet-loss, jitter): for example iLBC is more
tolerant to network problems if supported
·
device
CPU: some old mobile devices might not be able to handle high-complexity
codec’s such as opus or G.729. G711 and GSM has low computational costs
You can also
fine-tune the codec settings with the use_xxx settings where xxx is the codec
name as described in JVoIP documentation.
(string)
List of allowed audio codec’s
separated by comma.
By default the webphone will
automatically choose the best codec depending on available codec’s,
circumstances (network/device) and peer capabilities.
Set this parameter only if you have
some special requirements such as forcing a specific codec, regardless of the
circumstances.
Example: Opus,G.729,PCMU
(This will disable Speex, GSM, iLBC, GSM and PCMA).
Default: empty (which means auto
detection and negotiation)
Recommended value: leave it empty
Under normal circumstances, the
following is the built-in codec priority:
I.
Wideband Speex
and Opus (These are set with top priority as they have the best quality. Likely
used for VoIP to VoIP calls if the peer also has support for wideband)
II.
G.729 (Usually
the preferred codec for VoIP trunks used for mobile/landline calls because it’s
excellent compression/quality ratio for narrowband)
III.
iLBC, GSM (If
G.729 is not supported then these are good alternatives. iLBC has better
characteristics and GSM is better supported by legacy hardware)
IV.
G.711: PCMU and
PCMA (Requires more bandwidth, but has the best narrowband quality. Preferred
from WebRTC if Opus is not supported as these are present in almost any WebRTC
and SIP endpoints and servers)
With the NS and Java engines you can
also use the use codecname settings to disable/enable codec. Possible values:
0=never,1=don’t offer,2=yes with low priority,3=yes with high priority. For
example to disable all codec except PCMU you can use the following settings:
use_pcmu: 3, use_pcma: 0, use_g729: 0,
use_gsm: 0, use_speex: 0, use_speexwb: 0, use_speexuwb: 0, use_opusnb: 0,
use_opuswb: 0, use_opusuwb: 0, use_opusswb: 0, use_ilbc: 0,
alwaysallowlowcodec: 0
(string)
List of allowed video codec’s
separated by comma.
You might use this parameter to
exclude some codec from the offer list.
For example if you don’t wish to use
VP8, then set this to: “H264, H263”
Default: empty (which means auto
detection and negotiation)
More details here.
(string)
Set preferred video codec.
(number)
Enable/disable video.
-1: auto (default)
0: disable
1: enable
2: force always
More details about video
calls can be found here.
(number)
Max bandwidth for audio in kbits.
It will be sent also with SDP “b:AS”
attribute.
Default is 0 which means auto
negotiated via RTCP and congestion control.
(number)
Max bandwidth for video in kbits for
WebRTC video.
It will be sent also with SDP “b:AS”
attribute.
Default is 0 which means auto
negotiated via RTCP and congestion control.
(number)
You can suggest the size of the
video (in pixels) with the following parameters:
·
video_width
·
video_height
·
video_min_width
(WebRTC only)
·
video_min_height
(WebRTC only)
·
video_max_width
(WebRTC only)
·
video_max_height
(WebRTC only)
You might set all of these to 0 to
not set any constrains. Otherwise some default values might be applied.
(string)
Will set the facingMode WebRTC video
parameter:
Possible parameters:
·
"no":
will not set the facingMode at all (default)
·
"user":
The video source is facing toward the user; this includes, for example, the
front-facing camera on a smartphone.
·
"environment":
The video source is facing away from the user, thereby viewing their
environment. This is the back camera on a smartphone.
·
"left":
The video source is facing toward the user but to their left, such as a camera
aimed toward the user but over their left shoulder.
·
"right":
The video source is facing toward the user but to their right, such as a camera
aimed toward the user but over their right shoulder.
(number)
Enable/disable screen sharing:
0=No (default)
1=Auto (if supported by the
platform)
2=Yes (always force)
Default is: 1
Note:
Softphone skin users: If the
screensharing is set, a screen share button will appear on the softphone user
interface.
Enable extension:
o
Screen sharing was
a long term experimental feature in WebRTC standards and you might need a
browser extension to enable it.
o
You might also
need the followings:
o
Chrome: start the
browser with --enable-usermedia-screen-capturing flag
o
Firefox: in the
config create a media.getusermedia.screensharing.enabled key and set its
value to true and in media.getusermedia.screensharing.allowed_domains append
the IP address of your server
The latest webphone will try to
resolve screensharing without the need for any extensions in latest browsers.
(number)
Number of
payloads in one UDP packet (frames per packet). This will directly influence
RTP packet time (packetization interval) and packet size as shown here.
o By default it is set to 0 which means 2 frames for
G729 and 1 frame for all other codec.
This usually means 20 msec rtp packetization interval
for all codec’s and it is the most optimal setting, compatible with all
SIP/media stack implementations.
o In case if you wish to minimize delay, then you might
set the codecframecount to 1. This usually will result in 10 msec packetization
interval and will increase the required bandwidth by 40% due to high
header/data ratio.
o In case if you wish to minimize bandwidth, then you
might set the codecframecount to 4.
Note: with the WebRTC engine the codec
frame count is controlled by the browser WebRTC media stack and can’t be
changed. Usually it will be 20 msec frame time.
(number)
Specify how to handle conference,
especially for the WebRTC engine as other engines has built-in local RTP mixer.
0: disabled
1: auto
2: native only with local rtp mixer
(on WebRTC will force the NS or java engine)
3: server side conference mixing
controlled by DTMF
4: 3-way SIP conference
5: conference rooms via SIP MESSAGE
and REFER
6: conference rooms via SIP MESSAGE
7: conference rooms via SIP REFER
Default is 1.
Old parameter name was conferenceroom, which is
deprecated now.
For server side DTMF conference, you should also set
the use_fast_ice parameter to -1.
For more details see here.
(boolean)
Enable/disable packet loss concealment
Default is true (enabled)
(number)
Enable/disable voice activity
detection.
0: auto
1: no
2: yes for player (will help the
jitter)
3: yes for recorder
4: yes for both
Default is 2.
Notes:
-This parameter is supported only by
the NS and Java engines (not for WebRTC. For WebRTC you might use the
getrtcpeerconnection API as described here)
-The vad parameter is automatically set
to 4 by default if the aec2 algorithm is used.
-If you wish to use VAD related
statistics in your application, you might have to also set the “vadstat”
parameter after your needs. Possible values: 0=no,1=auto (default),2=detect no
mic audio,3=send statistics. See the VAD notification for more details.
-If you want to disable audio related
notifications for the NS and Java engines (microphone warning on no signal
detected) then set the “enablenomicvoicewarning” parameter to 0
(number)
Enable/disable acoustic echo
cancellation
0=no
1=yes except if headset is guessed
2=yes if supported
3=forced yes even if not supported
(might result in unexpected errors)
Default is 1.
(number)
Secondary AEC algorithm.
0=no
1=auto
2=yes
3: yes with extra (this might be too
much under normal circumstances)
Default is 1
Note: for maximum echo cancellation you can set the aec to 1,2 or 3 and
aec2 to 2 or 3.
(number)
Automatic gain control.
0=Disabled
1=For recording only
2=Both for playback and recording
3=Guess
Default value is 3
(number)
Enable/disable silence suppression
Usually not recommended unless your
bandwidth is really bad and expensive.
-1=auto
0=no (disabled)
1=yes
Default is -1 (which means no,
except mobile devices with low bandwidth)
(number)
Noise suppression.
0=Disabled
1=For recording only
2=Both for playback and recording
3=Auto guess
Default value is 3
(number)
Although the jitter size is
calculated dynamically, you can modify its behavior with this setting.
0=no jitter,1=extra
small,2=small,3=normal,4=big,5=extra big,6=max
Default is 3
(number)
Enable/disable presence.
Possible values:
-1: auto
0: disable presence
1: auto (if presence capabilities
detected)
2: always enable / force
Default is 1.
More details here.
(string)
List of users separated by comma to
request presence state from (the webphone will SUBSCRIBE to their presence
state and will accept NOTIFY reports).
You can also use the checkpresence() API for this.
(number)
Enable/disable BLF (busy lamp
field).
Possible values:
0:
disable BLF
1:
auto (from here it will auto switch to 0 or 2 regarding the circumstances
–whether BLF was initiated and succeed/failed)
2:
enable BLF
3:
force always (if you set to 3 then it can’t be switched off later and will use
BLF even after failure)
Default is 1.
Note: If BLF is an important feature for you, then we
recommend the usage of the NS or Java engines as this is unreliable with WebRTC
(set the enginepriority_ns and enginepriority_java to 4)
More details here.
(string)
List of users separated by comma to
request call state from (the webphone will SUBSCRIBE to their call state and
will accept NOTIFY reports).
You can also use the checkblf() API for this.
(number)
Specify the minimum accepted NS
engine version.
This is applicable only if the NS
engine is used and the webphone will ask the user to upgrade if the installed
NS plugin version is lower than this number (one click installer).
By default this is handled
automatically by the webphone and you should change it only if you need to
enforce a specific NS engine version for some reason.
Special values:
-2: disable asking for upgrades
regardless of the NS engine version
-3: completely disable asking for
all kind of ns engine install and upgrades
Default value: depends on the
webphone version
Note:
o The NS service plugin version for v.3.6.22061 engine
executable which was shipped with webphone v.3.6 is 55 (so you might set the “minserviceversion” setting to 55 to force the
latest version for all users)
o Upgrades for very old (outdated/incompatible) NS
engines are handled automatically by the webphone (with a reasonable default
“minserviceversion” settings in new webphone versions)
o Never set this to a higher value then the latest NS
plugin version (will result in continuously asking to upgrade)
o (Developer info: this value is loaded from the NS
engine MAPPVERSION define)
More details about NS engine
upgrades can be found here
(number)
Set how/when to upgrade the NS
engine.
-1: never (not recommended. Use the
0 option instead which might trigger an upgrade only on user interaction or if
there are no other options)
0: delayed background install only
(the new version will be downloaded and applied silently in the background with
no user interaction)
1: background or ask for user
(default behavior to handle the upgrade. Might be delayed especially if the
enduser doesn’t actively using the NS engine)
2: immediate install (will ask the
enduser immediately to download and install new versions)
Default: 1
Note: To completely disable all NS engine upgrades
(which is not recommended), you should set the nsupgrademode to 0 or -1 and the
autoupgrade to 6.
(string)
Use this setting for multi-account
registration.
You can specify multiple SIP accounts
in the following format:
IP,usr,pwd,t,proxy,realm;IP2,usr2,pwd2,t2,proxy2,realm2;
IP3,usr3,pwd3,t3,proxy3,realm3;
Account parameters:
·
IP: is the SIP server IP or
domain name
·
usr: is the SIP username
·
pwd: is the SIP password
·
t: is the register timeout in
seconds (optional)
·
proxy: SIP proxy (optional)
·
realm: SIP realm (optional)
·
authusr: auth (optional. Use only
if separate extension id and authorization username have to be used)
Most of the parameters are optional.
The parameters have to be separated by
comma (,) and the accounts have to be separated by semicolon (;).
All have to be passed in a single line
which should look like this: server,usr,pwd,ival;server2,usr2,pwd2,ival2;
Example:
sip1.mydomain,com,1111,xxx,300;sip2.mydomain.com,2222,xxx;
For more details read here.
(number)
Specify whether the webphone stack
should be started automatically on page load.
Possible values:
0: no (webphone will not start
automatically and you might need to call the start() API)
1: yes (webphone will start once
loaded if previous session was not failed)
2: always (webphone will always auto
start, regardless of previous success)
Default is 1.
If set to 0 or 1, then the start()
method needs to be called manually in order for the webphone to start. Also the
webphone will be started automatically on some other method calls such as
register() or call().
You might set this parameter to 0 to
prevent the auto initialization of the webphone, so you might delay the start()
until actually the user wish to interact with your phone UI (such as pushing
your click to call button).
Related
parameters: register
(auto register after start), appengine_startat (native engine launch),
startsipstack (NS engine specific), autologin (softphone skin specific)
forcereregister
(number)
Specify whether you wish to
disable/force reregistrations.
Please note that this is not about the
normal SIP re-registrations enforced by the expires interval (That is handled
automatically regardless of this settings).
This setting is considered when the sip
stack unregisters unexpectedly due to error response, no response, no network
or other reasons.
Possible values:
0: never auto reregister
1: try auto reregister if it was
already registered successfully before
2: always force reregister regardless
of the error (for example this will attempt to reregister even if user supplied
wrong username/password and server rejected the registration because of the
wrong credentials)
Default value is 1.
(boolean)
Set to false to prevent unregister
messages to be sent (for example to prevent unregister on web page reload).
Default is true.
(number)
Set to 1 to unregister all endpoints
for the users, not only the current one.
Will send Contact: * with the
unregister requests (REGISTER with Expires: 0).
Default is 0.
(number)
Unregister on idle (seconds).
If set to a positive value then the
webphone will automatically unregister when the user doesn’t user the browser
anymore for the specified seconds (no click, mouse move, etc on the browser
window).
The webphone will automatically
re-register again on user activity.
If you set it to 1 then it will be
treated specially by the NS engine only, unregistering immediately on idle. If
you wish to check the browser activity instead, then you should set it to 2 or
higher.
Default is 0.
(number)
Specify what type of web storage should
the webphone use.
Possible values:
-1=Auto(default)
0=None (no persistent storage)
1=IndexedDB
2=localStorage
3=WebSQL
The webphone might need to store various
things for proper functionality. For example: remember old user settings so the
user don’t have to type it again, remember old decisions (for example the VoIP
engine to use) so it will not spend time next time to lookup or to remember if
certain notifications was already showed for the user.
It is highly recommended to keep this
value at -1 (auto) as each browser has different capabilities which is handled
automatically if the preferred_storage is -1.
Note:
o
It will use other storage method,
if the preferred one is not supported by the browser.
o
This parameter can be set in the webphone_config.js only and not passed via the setparameter() API.
o
Storage can also failback to cookie
(only for the most important settings).
This can be enabled/disabled with the storagecookiefailback
parameter: 0 means no,1 means yes (default 1)
(boolean)
Set to true to clear all previously
stored or cached settings on startup.
This will reset all settings at
every start. You might use the configversion parameter instead if you wish to
reset only once (for example when you made some major changes).
Warning: this will forget all settings, even those that should be
remembered between sessions, such as “Have we already asked X from the
enduser?”. To deal with different settings we recommend using the profiles instead or just set unneeded settings to NULL.
More details can be found here.
Default is false.
(number)
Set to a positive value if you wish
to reset the config (clear old cached config) on webphone start on
configversion change.
This will reset the settings only
once (not at every startup).
If already set and you wish to reset
the settings again, then just increment the number.
Warning: this will forget all settings, even those that should be
remembered between sessions, such as “Have we already asked X from the
enduser?”. To deal with different settings we recommend using the profiles instead or just set unneeded settings to NULL.
More details can be found here.
Default is false.
(string)
By default all settings are
remembered by the webphone depending on your html document full URI (full
path).
However if you specify a value for
this profile parameter, then the settings will be stored in a storage named
root path + profile name.
For example if you deploy a webphone
to https://domain.com/path1 and a separate webphone to https://domain.com/path2
then the settings of these two webphones will be stored separately.
If you set the profile parameter to
“myprofile1” for both webphones, then they will use the same settings storage
(at domain.com_myprofile1).
You can also switch the settings
with this parameter. For example if your webphone is hosted at
https://domain.com/pathX then you might create two separate profile. Sometime
you might set the profile to “profileA” and sometime to “profileB”. This way
you can use the webphone with unrelated settings and you can be sure that the
settings will never mismatch.
Default value is empty (which means
settings bound to the webphone path or as specified by the usepathinfilenames
parameter).
(number)
Specify where to save the internal settings
and cache.
0: don't use any path
1: bind settings just to domain
2: bind settings to whole path
3: just path without domain
(default)
Note: this parameter can be set only
in the webphone_config.js and can’t be changed by the API at runtime.
Among the mentioned ice/turn/stun
related settings, you can now specify the following additional webrtc options
for the peer connection object:
·
bundlePolicy
·
iceCandidatePoolSize
·
iceTransportPolicy
·
rtcpMuxPolicy.
More details can be found here.
(number)
Trace/debug level. Values from 1 to
5.
Log level 5
means a full log including SIP signaling. Higher log levels should be avoided,
because they can slow down the softphone.
Loglevel above 9 is meant only for Mizutech developers and might
slow down the webphone (includes also RTP packets).
Do not set to 0 because that will disable also the important
notifications presented for the users.
Recommended values:
·
1: minimal logs for production
·
5: detailed logs for tests
More details about logs can be found
here.
There is also a maxloglevel parameter which you can use to prevent
users to set the log level above this predefined value.
By default the demo and trial versions might ship with
loglevel 5 and the licensed versions with loglevel 1 (which you can overwrite
with this parameter).
(boolean)
Specify whether to send logs to
console.
true: will output all logs to console
(default)
false: will output only level 1
(important events also displayed for the user)
The amount of logs depends on the
“loglevel” parameter.
Default is: true
NS and Java extra settings
With the NS and Java engines you can
also use any parameters supported by the Mizu JVoIP SDK as listed in the JVoIP documentation.
(Unrecognized parameters will be
skipped if the WebRTC engine is used)
Call divert and
other settings
These parameters are used for call
auto-answer, forward, transfer, voicemail, number rewrite and similar tasks:
(string)
The webphone can initiate call on
startup if this is set. It can be used to implement click to call or similar
functionality.
Can be any phone number, username,
extension number or full SIP URI acceptable by your VoIP server.
Default value is empty.
(number)
Useful for click-to-call to specify
what to do if you pass the “callto” parameter
0: Nothing (do nothing,
just preset the destination number; the user will have to initiate the
call/chat)
1: call (default. Will auto start the call to “callto”
–auto-call)
2: chat (will show the chat user interface presenting a chat
session with “callto”)
3: video call (will auto start a vide call)
Default is 0.
Note:
·
You can achieve
the same (and more flexible) behavior also via the API. For example just
initiate a call (by using the Call function) once the webphone is registered.
·
Some more advanced
SIP settings can be found in the “Engine related settings” below (such as
dtmfmode, transport or codec).
(string)
Specify the voicemail number (which the
user can call to hear its own voicemails) if any.
Most PBX servers will automatically
send the voicemail access number so usually this is detected automatically.
Default value is empty (auto-detect).
(number)
Normalize called telephone numbers.
If the dialed number looks like a
phone number (at least 5 number digits and no a-z, A-Z or @ characters and
length between 5 and 20) then will drop all special characters leaving only
valid digits (numbers, *, # and + at the beginning).
Possible values:
-1: auto (usually defaults to 1 yes, except if our username also contains
special characters)
0: no, don’t normalize
1: yes, normalize (default)
Default is -1
(string)
Add any prefix for the called
numbers.
Default is empty.
(string)
Called number prefix rewrite.
In case if you need to rewrite
numbers after your dial plan on the client side, you can use the numpxrewrite
parameter (although these kind of number rewrite are usually done after server
side dial plan):
You can set multiple rules separated
by semicolon.
Each rule has 4 parameters,
separated by comma: prefix to rewrite, rewrite to, min length, max length
For example:
‘74,004074,8,10;+,001,7,14;',
This will rewrite the 74
prefix in all numbers to 004074 if the number length is between 8 and 10.
Also it will rewrite the
+ prefix in all numbers to 001 if the number length is between 7 and 14.
Note: this parameter is same with
numrewriterules or the old filters parameter
(string)
Block incoming communication (call,
chat and others) from these users. (username/numbers/extensions separated by
comma).
Default value is empty.
(string)
Specify a number where incoming
calls should be forwarded when the user is already in a call. (Otherwise the
new call alert will be displayed for the user or a message will be sent on the
JS API)
Default is empty.
(string)
Forward incoming calls to this number
if not accepted or rejected within 15 seconds. You can modify this default 15
second timeout with the callforwardonnoanswertimeout
setting.
Default is empty.
(string)
Specify a number where ALL incoming
calls should be forwarded.
Default is empty.
(string)
Specify a number where ALL incoming
calls should be transferred to.
This might be used if your server
doesn’t support call forward (302 answers) otherwise better to set this on
server side because the call will not reach the webphone when it is
offline/closed, so no chance for it to forward the call.
Default is empty.
(number)
Set to ignore all incoming calls.
0: don’t ignore
1: silently ignore
2: reject
Default value is 0.
(boolean)
Set to true to automatically accept
all incoming calls (auto answer / auto connect).
Default value is false.
Note:
You can also auto-answer calls by using the accept API function.
The calls are also auto accepted if the received
INVITE contains the “x-p-auto-answer: normal"
or "x-answer-mode: auto” SIP header and
the enableautoaccept parameter is set to 2.
These are useful if only certain calls have to be auto
accepted and you wish to control which one from your JS code or from your SIP
server side.
With the WebRTC engine some user interaction (such as
a button click) might be required before the webphone will be capable to auto
answer incoming calls as new browser versions doesn’t allow auto-play without
user interaction.
(number)
Specify if to enable auto-answer
suggestions from peers for the incoming calls.
Possible values:
0: never
1: enable only if the autoacceptheader is set and it has a match in the
incoming call INVITE message
2: enable also for server-side
initiated auto answer (if headers such as Call-Info,
Alert-Info, Answer-Mode
or Auto-Answer are received with the
incoming INVITE)
3: force auto answer: auto connect all
incoming calls (works the same way like autoaccept
set to true)
Default is 1.
(number)
Specify whether to auto accept
incoming calls when the user clicks to enable device sharing for WebRTC (the
audio device permission browser popup) on media permission accepted.
Possible values:
0: no (Do nothing. The user will
have to click the “Accept” button to accept the incoming call or you must call
the accept() API)
1: auto (guess when to auto accept)
2: always (Always accept webrtc call
on browser share device click)
Default is 1.
(number)
Will play a short sound on incoming
calls.
0: No
1: Yes
Default value is 0
Note: this is not the ringtone.
(number)
Will play a short sound when calls
are connected
0: Disabled
1: For auto accepted incoming calls
2: For incoming calls
3: For outgoing calls
4: For all calls
Default value is 0
(number)
Retry the call on failure or no
response.
0: no
1: yes
Default value is 1.
(boolean)
Set to true to automatically reject
(disconnect) incoming call if a call is already in progress.
Default value is false.
(number)
Set to 1 to auto-redial on 301/302
call forward.
Set to 0 to disable auto call forward.
Default value is 1.
(number)
Specify how the call hold function
should work:
-2=no (will ignore hold requests)
-1=auto (defaults to 2)
0=no
1=not used
2=hold (standard hold by sending
“a=sendonly”)
3=other party hold (will send “a=recvonly”)
4=both in hold (will send “a=inactive”)
Default is -1
(number)
Default mute direction:
0: both
1: mute out (speakers)
2: mute in (microphone)
3: both
4: both
5: disable mute
Default: 0 or 2
(number)
Auto Mute/Hold all call legs on
conference calls.
0=no
1=yes
Default is 0.
(number)
Specify if other lines will be muted
on new call.
0=no (default)
1=on incoming call
2=on outgoing call
3=on incoming and outgoing calls
4= on line change (with setline or
with other line button click if you are using the softphone user interface)
5=on outgoing call and on line
change (like 2+4)
6=on any call and on line change
(like 3+4)
Default is 0
(number)
Specify if other lines will be put
on hold on new call.
0=no (default)
1=on incoming call
2=on outgoing call
3=on incoming and outgoing calls
4=on line change (with setline or
with other line button click if you are using the softphone user interface)
5=on outgoing call and on line
change (like 2+4)
6=on any call and on line change
(like 3+4)
Default is 0
(number)
Specify hold-mute workaround for the
WebRTC engine with multiple simultaneous calls.
With the WebRTC engine the webphone might
use mute instead of hold with multiple lines as a workaround for some
multi-line hold related WebRTC issues in some browsers.
-1: always use mute instead of hold
(even if there are no multiple calls)
0: use mute instead of hold with
multiple calls
1: usually use mute with multiple
calls
2: use mute instead only in some
cases for multi-line calls
3: never use mute instead of hold
Default is 2
(string)
Audio device name for recording
(microphone). Set to a valid device name or “Default” which would select the
system default audio device.
Note: this is usually set at run-time
from the API or from an audio device select control presented to the users
(already implemented by the softphone skin). If not set, then the webphone will
use the OS default recording device.
(string)
Audio device name for playback
(speaker). Set to a valid device name or “Default” which would select the
system default audio device.
Note: this is usually set at run-time
from the API or from an audio device select control presented to the users
(already implemented by the softphone skin). If not set, then the webphone will
use the OS default playback device.
(string)
Audio device name for ringtone. Set
to a valid device name or “Default” which would select the system default audio
device. You can also set it to “All” to have the ringtone played on all
devices.
Note: this is usually set at run-time
from the API or from an audio device select control presented to the users
(already implemented by the softphone skin). If not set, then the webphone will
use the OS default playback device. Separate ringer device selection is not
available with the WebRTC engine.
(number)
Default microphone volume in percent
from 0 to 100. 0 means muted. 100 means maximum volume.
This is the audio input volume which
are going to be streamed to the other end.
Default is 50% (not changed)
Note:
·
The default
volume level is determined by the OS volume setting. The webphone volume
changes will be only relative to the OS settings
·
The result
volume level might be affected by the AGC if it is enabled.
·
Some browsers
doesn’t expose volume change functionality if you are using the WebRTC engine
(number)
Default speaker volume in percent
from 0 to 100. 0 means muted. 100 means maximum volume.
This is the audio output volume
heard by the local user from the incoming audio stream sent by the other party.
Default is 50% (not changed)
Note:
·
The default
volume level is determined by the OS volume setting. The webphone volume
changes will be only relative to the OS settings
·
The result
volume level might be affected by the AGC if it is enabled.
·
Some browsers
doesn’t expose volume change functionality if you are using the WebRTC engine
(number)
Default ringback volume in percent
from 0 to 100. 0 means muted. 100 means maximum volume, 0 is muted.
Default is 50% (not changed)
Note: the ring volume can’t be changed
for the WebRTC engine (use the OS volume settings)
(number)
Control the default playback device
on Android phones and tablets.
-2: ignore (don’t make any changes)
-1: auto guess (prefer loudspeaker
for video call, otherwise speakerphone)
0: default (most Android smartphones
will use the loudspeaker by default as the playback device)
1: switch to speakerphone before the
first call
2: switch to speakerphone after
first call
3: switch to speakerphone at start
Default: -1
Note:
You can also use the setloudspeaker API to change it at runtime.
There is no similar setting for iOS, because changing
an audio device requires "setSinkId()" which is not supported even by
the latest versions of Safari.
(number)
Specify transfer mode for native
SIP.
-1: default transfer type
0: call transfer is disabled
1: transfer immediately and
disconnect with the A user when the Transf button is pressed and the number
entered (unattended/blind transfer)
2: transfer the call only when the
second party is disconnected (attended transfer)
3: transfer the call when the VoIP
phone is disconnected from the second party (attended transfer)
4: transfer the call when any party
is disconnected except when the original caller was initiated the disconnect
(attended transfer)
5: transfer the call when the VoIP
phone is disconnected from the second party. Put the caller on hold during the
call transfer (standard attended transfer)
6: transfer the call immediately
with hold and watch for notifications (unattended transfer)
7: transfer with no hold and no
disconnect (simple unattended transfer)
8: transfer with conference (will put the
parties to conference on transfer; will mute or hold the old party by default)
Default is -1 (which is the same as
6 or 7)
Note:
·
Unattended means simple immediate
transfer (just a REFER message sent)
·
Attended transfer means that there
will be a consultation call first. The softphone skin has its own attended
transfer control options.
·
It is also possible to create an
attended transfer by initiating a simple call to the transfer target and on
hangup an unattended call-transfer (transfertype 1, 6 or 7)
·
If you have any incompatibility
issue, then set to 7 (unattended is the simplest way to transfer a call and all
sip server and device should support it correctly)
·
More details can
be found here
(number)
Specify if replace
should be used with transfer requests, so the old call (dialog) is not
disconnected but just replaced.
This way the transferee
and the transfer-target parties are not disconnected, just the other party is
changed at runtime.
The feature is
implemented by adding a Replaces= for the Contact header in the REFER request
as described in RFC 5589 and RFC 5359.
The transferee (the
party which receives the REFER transfer request) or the SIP server must be able
to handle replaces for this to work.
Possible values:
-1: auto (if
transfertype is -1 (default), 6 or 7; server/peer has replaces support; we are
connected with the transfer target)
0: no
1: yes
2: force (use replaces
even if peer doesn’t have replaces support or there is no session with the
target)
Default is -1
Note: some SIP servers doesn’t announce
replace capabilities ("replace" tag into the Supported or Require SIP
headers). In this can you will have to set the transfwithreplace parameter to
2.
(number)
Specify how to handle
incoming call transfer with replaces requests (How to handle the Replaces=
Contact tag in incoming REFER requests)
-1: auto (defaults to
1)
0: disable
1: standard (sending
the Replaces header in the new call INVITE request as described in RFC 3891)
2: in place (might be
useful with servers without replaces support; not supported by the WebRTC
engine)
Default is -1
(number)
If to treat session progress (183)
responses as ringing (180). This is useful because some servers never sends the
ringing message, only a session progress and might not start to send in-band
ringing (or some announcement). In this circumstances the webphone can generate
local ringback.
The following values are defined:
0: do nothing (no ringback on
session progress message)
Will not call
startRingbackTone() on 183 (only for 180)
1: change status to ring
2: start local ring if needed and be
ready to accept media (which is usually a ringtone or announcement and will
stop the locally generated ringback once media received)
Will call
startRingbackTone() on 180 and 183 but stop on early media receive.
3: start media receive and playback
(and media recording if the “earlymedia” parameter is set)
4: change status to ringing and
start media receive and playback (and media recording if the “earlymedia”
parameter is set to true)
5: play early ringback and don’t
stop even if incoming early media starts
Will call
startRingbackTone() on 180 and 183 and do NOT stop on early media receive.
Default value is 2.
*Note: on ringing status the web phone
is able to generate local ringback tone. However with the default settings this
locally generated ringtone playback is stopped immediately when media is
started to be received from the server (allowing the user to hear the server
ringback tone or announcements)
(number)
Maximum ring time allowed in
millisecond.
Default is 90000 (90 second)
You can also set separate ring
timeout for incoming and outgoing calls with the “ringtimeoutin” and
“ringtimeoutout” settings.
(number)
Maximum speech time allowed in
millisecond.
Default is 10800000 (3 hours)
(number)
RTP timeout in seconds to protect
again dead sessions.
Calls will be disconnected if no
media packet is sent and received for this interval.
You might increase the value if you
expect long call hold or one way audio periods.
Set to 0 to disable call cut off on
no media.
Default value is 300 (5 minute).
At the beginning of the calls, the
half of the mediatimeout value is applied (2.5 minute by default if there was
no incoming audio at all).
(string)
Voice record upload URL (FTP or
HTTP).
With this setting you can setup VoIP
call recording (voice recording).
Default value is empty (no voice
call recording).
If set then calls will be recorded
and uploaded to the specified ftp or http address in pcm/wave, gsm, mp3 or ogg
format.
Note: mp3 support is not included by
default in the NS engine to minimize the package size. Contact Mizutech to
include this in your build if you need mp3 recording also from the NS engine (build option voicerecformat=3;)
The files can be uploaded to
·
your FTP server
(any FTP server with specified user login credentials)
·
or to your HTTP
server using HTTP PUT or multipart/form-data POST (in this case you need a
server side script to save the uploaded data to file)
The following keywords can be used
in the file name as these will be replaced automatically at runtime to their
respective values:
·
DATETIME: will
be replaced to current date-time
·
DATE: will be
replaced to current date (year/month/day)
·
TIME: will be
replaced to current time (hour/min/sec)
·
CALLID: will be
replaced to sip call-id
·
USER: will be
replaced to local user name
·
CALLER: will be
replaced to caller party name (caller id)
·
CALLED: will be
replaced to callee party name
·
SERVER: the
domain or IP of the SIP server
·
COUNTER: an auto-increasing
number
If you set a HTTP URI, then the
following headers will be also set in the HTTP PUT or POST: X-type, X-filename,
X-user, X-caller, X-called, X-callid and X-server.
We recommend to use FTP first (or
try this first) as this is very easy to configure and doesn’t require any
server side script.
If you need unique file names then we recommend using
the SIP Cal-ID (CALLID keyword), so you can associate your call detail records
(CDR’s obtained from your VoIP server) with the recorded files. You can also
access the SIP Call-ID from the webphone in many ways: use the onCallStateChange
or onCdr callbacks or use the linetocallid function to get the call-id of a call.
FTP Example:
ftp://user01:pass1234@ftp.foo.com/voice_DATETIME_CALLER_CALLED
You can also suggest a particular
file format by appending its extension to the file name (for example .wav or
.mp3).
For example: ftp://user01:pass1234@ftp.foo.com/voice_DATETIME_CALLER_CALLED.wav
Since the username:password
is part of the URI here, no special characters are allowed in the file path
(don’t use ftp accounts with characters like @ ; ‘ “ / \ in the username or in
the password).
HTTP Example:
http://www.foo.com/myfilehandler.php/filename=callrecord_CALLID
You can also suggest a particular
file format by appending its extension to the file name (for example .wav or
.mp3).
For example: http://www.foo.com/myfilehandler.php?filename=callrecord_DATETIME_USER.wav
You can also set just a path,
without any URL query parameter, like this:
For example: http://www.foo.com/myfilehandler.php/rec_DATETIME_CALLID
Example HTTP POST header packet if
you set the url to “http://yourdomain.com/myapi/voicerecord/anyentry?filename=callrecord_DATE_CALLID.mp3”:
POST /myapi/voicerecord/anyentry?filename=callrecord_2024_04_04_xxx.mp3
HTTP/1.1
Host: yourdomain.com
User-Agent: webphone
Accept: */*
X-type: fileupload
X-filename:
callrecord_2024_04_04_xxx.mp3
X-user: local_username
X-caller: caller_party
X-called: called_party
X-callid: sip_callid
X-server:
your_sip_server_address
Content-Length: 18623
Expect: 100-continue
Content-Type:
multipart/form-data; boundary=------------------------fde9999399e1b8eb
--------------------------fde9999399e1b8eb
Content-Disposition:
form-data; name="file";
filename="callrecord_2024_04_04_xxx.mp3"
Content-Type:
application/octet-stream
.....
You will receive “file” as the form
name parameter and the name of the file as the form data “filename” parameter.
(So you will receive the file name
as both the “filename” form parameter and also in the X-filename HTTP header).
The content type can be
application/octet-stream, audio/x-wav, audio/mpeg, audio/x-gsm or audio/ogg.
(Regardless of the suggested file
name, you can save the files on your server with any name, this is your
choice).
A working example for PHP can be
downloaded from here.
More details about handling HTTP
file upload: C#, ASP.NET, PHP, PHP (2), NodeJS, Java.
More details about voice recording
can be found here.
Note:
·
You can also use the voicerecord API to turn on/off the voice recording at runtime (if
not all calls have to be recorded)
·
The voicerecord API should be
called before the call you wish to record as changing the recording state
during the calls might not be supported
·
With the NS or Java engine you can
also record to local file. For this, you need to set the voicerecording
parameter which has the following values defined: 0=no, 1=record to local file
system, 2=remote http/ftp only, 3=both local and remote
·
If you are using the WebRTC engine
with FTP voice file storage, avoid using special characters in the ftp
username/password
·
Ogg/vorbis format can be also used
with NS or Java engines (this is not supported by WebRTC)
·
With the NS and Java engines the
call recording is performed on the client side by the webphone. With the WebRTC
engine the call recording is performed on the gateway or server side (but the
voicerecupload parameter is still handled correctly, passing it to the server)
·
If you are using the NS engine
with built-in JVM then HTTPS upload might not work (old tiny version of the JVM
might not implement the latest TLS protocols). In this case you can still use
HTTP or FTP storage (not HTTPS) or notify Mizutech to build with a new full JVM
(will increase the size).
User
interface related settings
Most of these apply only to the
Softphone user interface which is shipped with the webphone to further
customize the web softphone user interface and behavior (Softphone.html)
(string)
Brand name of the softphone to be
displayed as the title and at various other places such as SIP headers such as
the User-Agent.
Default is empty.
Note: purchased webphones always comes with a
predefined brand name as you communicated to Mizutech. This brand must be a
short unique name, with no special characters. You can overwrite the default
with this setting if needed.
(string)
Your company name to be displayed in
the about box and various other places.
Default is empty.
(string)
Displayed on login page.
Can be text or an image name, ex:
"logo.png" (image must be stored in images/folder)
Default is empty.
Note: if you set a logo, then this
will be placed on the softphone skin (softphone.html), taking up some space of
its user interface.
The useloginpage might be also set
to 1 or 2 to show the logo.
Since the webphone is usually
embedded in webpages, you might consider to place logo on other places of your
website and not into the softphone skin itself as in this case it would just
take precious space inside the app.
Otherwise, you also have all the
html in your hand so you can edit the user interface as you wish, placing any
image at any location after your like.
(number)
You can easily change the skin of
the supplied user interfaces with this setting (softphone, click to call).
Possible values:
1.
Default
2.
Light
Blue
3.
Light
Green
4.
Light
Orange
5.
Light
Purple
6.
Dark
Red
7.
Yellow
8.
Blue
9.
Purple
10.
Turquoise
11.
Light
Skin
12. Green Orange
Default is 0.
More
details about design changes.
Set the language for the user
interface.
This is usually a two character
language code (for example en for English or
pt for Portuguese) or for specific
accents/countries you can use the long format such as en-US.
If this parameter is not set, then
by default the webphone will auto detect the browser language and will use it
if there is a good translation for that language. This behavior can be turned
off by setting the languageautodetect
parameter to 0 (will always default to
original/English in this case).
Before you preset any language, make
sure that the webphone has a good quality built-in translation for it.
Otherwise, you might need to add the
translation yourself or improve the existing translation.
See the details here.
(number)
User interface complexity level.
0=minimal
5=reduced
10=full (default)
15=more (for tech user)
You might set to 5 for novice users
or if only basic call features have to be used.
Default is 10.
(number)
This can be used to hide the server
address setting from the user if you already preconfigured the server address
in the webphone_config.js
(“serveraddress” config option), so the enduser have to type only their
username/password to use the softphone.
Possible values:
0: no (will hide the server input
setting for the endusers)
1: auto (default)
2: yes (will shot the server input
setting for the endusers)
(number)
Specify if to show proxy server
input on the softphone user interface login page.
Possible values:
0: no
1: if set
2: yes
Default is 1
(number)
Specify if to show the username
(caller id) input on the softphone user interface login page.
Possible values:
0: no
1: if set
2: yes
Default is 1
(number)
Specify how to handle if the user
type a full SIP URI as the username input.
Possible values:
0: always ignore (will ignore also
for the username; not recommended)
1: ignore for the sipusername (auth
username)
2: extract username only in basic
settings
3: config as serveraddress if
missing in basic settings
4: config as serveraddress if
missing
5: config as serveraddress always
6: config as proxyaddress always
Default is 3
(number)
Specify how to handle if the user
type a full SIP URI as the sipusername input.
-1: auto (keep it as-is but might
retry the auth with the user part only if rejected)
0: keep it as-is (the sip auth
username can have user@domain format)
1: remove the domain part and keep
only the SIP URI
Default is -1.
This parameter might be ignored if
the handleusernameuri is set to 0.
If you (your VoIP server) are using
sip auth username in user@domain format, then you might set this parameter to 0
(to avoid unneccessary auth retry with the default -1).
Otherwise (if you don't use
user@domain format for sip authnetication), then you might set it to 1 (to fix
the user@domain user input and keep only the user part for SIP auth).
Note: the old allowsipuriasusername
parameter was deprecated by this new one.
(number)
Whether to use a simplified login
page with username/password in the middle (instead of list style settings; old
haveloginpage).
Possible values:
-1: auto (will auto set to 1 if
featureset is Minimal, otherwise 0)
0: no
1: only at first login
2: always
Default is: -1
autologin
(number)
Specify when to skip the login page.
Possible values:
-1=Auto
0=No
1=Yes
Default is: -1
More details can be found here.
(number)
Specify if to hide the password
string on the softphone user interface (login page / settings).
Whether to use a simplified login
page with username/password in the middle (instead of list style settings; old
haveloginpage).
Possible values:
0: don’t hide
1: replace text element with *****
if the password is already set
2: use password input element if the
password is already set (instead of text)
3: always use password input element
(instead of text)
4: always use password input element
(instead of text) and disable password reveal if the password was already set
Default is 4.
Note: When set to 2 or 3, the password string can be
revealed by double-click.
(number)
Enable/disable password autocomplete
on the softphone user interface (login page / settings)
Possible values:
-1: don’t set any flag (use browser
default)
0: disable (off)
1: enable (on)
Default is -1
quick_access_list
(number)
Enable/disable recent important
contact list on the main page.
Possible values:
0: disable (show only the dial pad)
1: enable
Default is: 1
(number)
Specify text messaging mode
(IM/chat/SMS/API)
-1: auto guess or ask (default)
0: disable all
1: disable incoming messages and
auto guess outgoing mode
2: disable message sending and auto
guess incoming mode
3: API (if SMS API URI have been
defined)
4: reserved
5: VoIP SMS (will send the X-Sms:
yes SIP header. More details here)
6: VoIP IM/chat (SIP MESSAGE)
Note: the old haschat and chatsms parameters are
deprecated now but still supported
(number)
Define how to handle incoming chat
messages.
0: open/show chat window if not in
call
1: just set a notification
Default is 0.
(string)
Can be used to add call park and
call pickup (will be sent as DTMF for call park and user need to call to pickup
number to later reload the call from the same or other device).
If set, then it will be displayed on
the call page as an extra option.
(boolean)
Enable/disable the time counter
during ring-time.
(boolean)
Set to true to enable file transfer.
(string)
HTTP URI used for file transfer. By
default Mizutech service is used which is provided for free with the web
softphone.
(number)
Show notifications in phone
notification bar (usually on the top corner of your phone).
0:No
1:Yes (display missed call and
missed chat notifications)
Default is 1.
(boolean)
Always display volume controls when
in call.
Default is false.
Old/deprecated parameter name was
“hasvolume”.
(boolean)
Always display audio device when in
call.
Default is false.
Display video preview window on
video device select:
Possible values: 0 mean No
(default), 1 means Yes
When set to 1, then a video preview
will appear when you select a video device on the device form or via the
devicepopup() API. This preview window can be closed by the user or it will be
closed automatically after 10 seconds once the device form is closed.
(string)
Specify where to display the
information returned by scurl_displaypeerdetails.
It can be used display details about
the peers from your CRM such as full name, address or other details.
(Useful in call-centers and for
similar usage)
Possible values:
0: show on call page (instead of
contact picture)
1: on new page
div id: display on the specified DIV
element
(number)
Whether to (automatically) add new
called numbers to your contact list.
0:No
1:Ask
2:Yes (will not ask for a contact
name)
Default is 1.
(string)
Display custom popup for user once.
Default is empty.
(boolean)
Enable/disable hint popups.
Possible values:
true: show all toasts (default)
false: don't show toasts and popup
messages
(number)
Whether to display a popup about
incoming calls (uses the HTML5 notification API for WebRTC or native popup for
NS/Java).
Possible values:
0.
No
1.
Auto (show only
if browser window is not in foreground/focused)
2.
Yes
3.
Always force
from all engines
Default is 1.
Set to 0 to disable (in this case
make sure that you handle the incoming call alert from your HTML/JS if
required).
Set the callreceiver parameter to 2 to catch incoming
calls even when the webphone is not running.
Note: The old name of this parameter
name was hasincomingcallpopup and hasincomingcall
The incoming call HTML5 popup can be
optionally customized with the following parameters:
·
callnot_title
(string) – the title of the notification. By default this is the brand name of
the webphone.
·
callnot_body
(string) – the body text of the notification. By default this is: “Incoming
call from: PEERNAME”
·
callnot_icon
(string) – URL of the notification icon. By default this is:
“notification_icon.png” from “images” directory.
·
callnot_image
(string) – URL of the notification image. By default this is empty.
(number)
Specify when to ask for permissions
if HTML5 notifications are required:
-1: auto
0: never
1: when required
2: when required and on startup/call
if failed
3: on start and on call (always)
(number)
The call page will remain active
after successful call hangup for this amount of time in milliseconds, after
which it will close automatically.
Set to 0 to disable.
Default is 3000 (3 sec)
(number)
The call page will remain active
after failed call hangup for this amount of time in milliseconds, after which
it will close automatically.
Set to 0 to disable.
Default is 8000 (8 sec)
(string)
Header text displayed for users on
top of softphone windows.
Default is empty.
(string)
Footer text displayed for users on
the bottom of softphone windows.
Default is empty.
(string)
Version number displayed for users.
Default is empty (will load the
built-in version number)
(number)
This is to allow contact
synchronization between mobile and desktop.
-1=don't show
0=show Sync option in menu and
Contacts page (if no contacts available)
1=show in menu only
Default is 1
(string)
Set one or more contacts to be
displayed by default in the contact list.
Contact fields: name, number, email,
address, notes, website
Fields must be separated by comma
and contacts separated by semicolon:
Example: defcontacts:
'John Doe,12121;Jill Doe,231231,jill@g.com'
Note: Contacts can be added also at runtime using the addcontact API.
(string)
List of settings options and
features to be disabled or hidden.
To disable entire features, use the
upper case keywords such as CHAT,VIDEO,VOICEMAIL,CONFERENCE.
To disable settings, use
the setting label or name such as Audio device, Call forward.
Example: disableoptions:
'theme,email,Call forward,callforwardonbusy,callforwardonnoanswer,callforwardalways,VIDEO'
Other examples:
"chatsms,textmessaging,disablewbforpstn,audiorecorder,audioplayer,speakerphoneplayer,useroutingapi,callback_mode,transfertype,transfwithreplace,balance_uri,rating_uri,creditrequest,ratingrequest,p2p_uri,p2p,callback_uri,callback,sms_uri,sms, disablecontactmenu";
You can also disable
main pages:
PAGE_MAIN, PAGE_CONTACTS, PAGE_HISTORY, RECENTS
(string)
Custom parameters can be set in a
key-value pair list, separated by semicolon Ex: displayname=John;
Default is empty.
(number)
Specify allowed actions on the logs
page.
0: no options (users will still be
able to copy-paste the logs)
1: upload (default)
2: email launch (the email address
set by the “supportmail” parameter or support@mizu-voip.com if not set)
(strings)
The webphone GUI can load additional
information from your web server application or display some content from your
website internally in a WebView or frame. You can integrate the included
softphone user interface with your website and/or VoIP server HTTP API (if any)
by using the following parameters:
·
advertisement:
Advertisement URL,
displayed on bottom of the softphone windows.
·
supportmail: Company support email address.
·
supporturl: Company support URL.
·
newuser: New user registration http request
OR link (if API then suffix with star *)
·
forgotpasswordurl:
Will be displayed
on login page if set.
·
homepage: Company home page link.
·
accounturi: Company user account page link.
·
recharge: Recharge http request (pin code must
be sent) or link.
·
p2p: Phone to phone http request or link.
·
callback: Callback http request or link (For
example: *https://yourdomain.com/callback?user=USERNAME)
·
sms: SMS http request.
·
creditrequest:
Balance http
request, result displayed to user. (For example: *https://yourdomain.com/balance?user=USERNAME)
·
ratingrequest:
Rating http
request, result displayed for user on call page. (For example: *http://yourdomain.com/rating?destination=CALLEDNUMBER)
·
helpurl: Company help link.
·
licenseurl: License agreement link.
·
extramenuurl:
Link specifying
custom menu entry. Will be added to main page (dialpad) menu.
·
extramenutxt:
Title of custom
menu entry. Will be added to main page (dialpad) menu.
·
serveraddressbook_url:
address book URL or
API (details here)
Parameters can be treated as API
requests (specially interpreted) or links (to be opened in built-in
webview). For http API request the value must begin with asterisk character:
"*http://domain.com/...." For example if the "newuser" is a
link, then it will be opened in a browser page; if it's an API http request
(begins with *), then a form will be opened in the softphone with fields to be
completed.
o
The followings
are always treated as API request: creditrequest, ratingrequest
o
The followings
can be links OR API http requests: newuser, recharge, p2p, callback, sms
o
The rest will be
treated always as links (opened in built-in webview or separate browser tab)
You can also use keywords in these
settings strings which will be replaced automatically by the web softphone. The
following keywords are recognized:
o DEVICEID: unique identifier for the
client device or browser
o SESSIONID: session identifier
o USERNAME: sip account username.
preconfigured or entered by the user
o PASSWORD: sip account password
o CALLEDNUMBER: dialed number
o PEERNUM: other party phone number or
SIP uri
o PEERDETAILS: other party display
name and other available details
o DIRECTION: 1=outgoing call,
2=incoming call
o CALLBACKNR,PHONE1,PHONE2: reserved
o PINCODE: reserved. will be used in
some kind of requests such as recharge
o TEXT: such as chat message
o STATUS: status messages: onAppStateChange,
onRegStateChange, onCallStateChange, inChat, outChat
o MD5SIMPLE: md5 (pUser +
":" + pPassword)
o MD5NORMAL: md5 (pUser +
":" + pPassword+":"+randomSalt)
o MD5SALT: random salt
Example credit http request:
https://domain.com/balance/?user= USERNAME
(Where “USERNAME” will be
dynamically replaced with the currently logged in username)
Note: Ensure that you have proper authentication for
payable functions such as callback, p2p or sms. Some other functions can also
affect user privacy, such as creditrequest.
From security perspective the webphone
can be treated as any other regular SIP endpoint: make sure to not reveal the
password of your SIP accounts and your app will be secure.
Webphone parameters are safe by default
since they are used only in the user http session. This means that the enduser
can discover its own settings including the password, but other users
–including users for the same browser or middle-men such as the ISP- will not
be able to see the sensitive parameters if you are using secure http (HTTPS)
and don’t statically set a SIP account password in your HTML, which could be
discovered from your webpage source.
The only sensitive parameter is the SIP
account “password”! This is sent only as digest hash in signaling, but make
sure to never display or log from your code.
The easiest way to maintain maximum
security is to allow the endusers to type their SIP password as needed, instead
of hardcoding or provisioning.
You should not hardcode the password
into your website (It should not be found if you check the source of your
webpage in the browser. The only exception would be if you offer some free to
call service which is not routed to outside paid trunks/carriers). If the
password has to be preconfigured then load it via an ajax call or similar
method; just make sure to use HTTPS in this case because otherwise all the
communication is in clear text between the browser and your server if the page
is running on unsecure HTTP. Otherwise just let the endusers to enter their
password on a login/settings form and pass it to the webphone with the
setsipheader() API call.
If the password needs to be passed
dynamically then:
·
make sure to use HTTPS if it is
sent from the server (for example via an AJAX or other API request)
·
if you pass it from JavaScript,
then you might encrypt or obfuscate it with your preferred method
Please note that even if you pass the
password around in clear text, you are still protected if your page is in
secured (on HTTPS). Only the enduser might be able to found its own password
from the browser in this case, but this is usually not a problem since the
users should know their own password anyway (Or if somehow you don’t wish the
enduser to known its own password then you can implement your own custom
encryption or obfuscation in JavaScript)
There is no much reason to try to
obfuscate or hide other parameters.
For example the “serveraddress” can be
discovered anyway by analyzing the low level network traffic and this is
perfectly normal. Most of the other parameters are completely irrelevant. Some
sensitive information’s are also managed by the webphone (such as the user
contact list) however these are stored only locally in the browser secure web
storage or secure cookie by default (on HTTPS) and further encrypted or
obfuscated by the webphone.
The following methods can be used to
further secure the webphone usage:
·
set the loglevel to 1 (with
loglevel 5 the password might be written in the logs)
·
use strong passwords for all your
SIP extensions or trunks
·
don’t hardcode the password if
possible (let the users to enter it) or if you must hardcode it then use
encryption and/or obfuscation
·
restrict the account on the VoIP
server (for example if the webphone is used as a support access, then allow to
call only your support numbers and disable outbound calls)
·
set a maximum simultaneous call
limit and rate limiter for your SIP accounts
·
instead of preconfigured
parameters you can use the javascript VoIP api (setparameter)
·
use HTTPS (secure http / TLS)
·
encrypt/obfuscate the password in
JavaScript code if you wish to hide it even from its owner or if you need to
use a preconfigured account for your app
·
for parameter encoding (encryption/obfuscation) you can use XOR + base64 with your built-in
key (ask passphrase from Mizutech), prefixed with the “encrypted__3__” string
(you can verify your encryption with this tool
selecting XOR Base64 Encrypt)
·
you can quickly encrypt any
parameter using this link:
https://mnt.mizu-voip.com/mmexreqvitserverjrsktt/xwencode?wkey=YOURKEY&wstring=YOURSTRING&wversion=3
Replace YOURKEY with your webphone key provided by mizutech.
The key in the demo version is h39idbfqw7116ghh
Replace YOURSTRING with a parameter value (for example the password parameter).
URI encode if contains special characters such as spaces.
More details can be found here.
·
secure your VoIP server (account
limits, rate-limits, balance limits, fraud detection) and follow the VoIP
security best practices. For example here you
can find details about mizu VoIP server security.
You can use the webphone javascript SIP
library in multiple ways for many purposes:
·
create your own web dialer
·
add click to call functionality to
your webpage
·
add VoIP capability to your
existing web project or website
·
integrate with any CRM,
callcenter client or other projects
·
modify one of the existing
projects to achieve your goal (see the included softphone and click to call
examples) or create yours from scratch
·
and many others
The public JavaScript API can be found
in "webphone_api.js" file, under global javascript namespace
"webphone_api".
To be able to use the webphone as a
javascript VoIP library, just copy the webphone folder to your web project and
add the webphone_api.js to your page.
The API functions should not throw
exceptions and should not return null or undefined values (will return
empty/false/0/minus/'ERROR' values on failure, depending on the context).
In case if you have to manage multiple
simultaneous calls explicitly, then you might call the setline() API to specify
the line before the other API calls.
For example to mute a call on line 2
first set the line to 2 (webphone_api.setline(2);)
then call the mute function (webphone_api.mute();)
More details about multi line
management can be found here.
<head>
<!-- Include the
webphone_api.js to your webpage -->
<script src="webphone_api.js"></script>
</head>
<body>
<script>
//Wait until the webphone
is loaded, before calling any API functions
webphone_api.onAppStateChange (function (state)
{
if (state === 'loaded')
{
//Set parameters (Replace
upper case worlds with your settings)
webphone_api.setparameter('serveraddress',
SERVERADDRESS);
webphone_api.setparameter('username',
USERNAME);
webphone_api.setparameter('password',
PASSWORD);
webphone_api.setparameter(‘other’,
MYCUSTOMSETTING);
//See the “Parameters”
section below for more options
//Start the webphone
(optional but recommended)
webphone_api.start();
//Make a call (Usually
initiated by user action, such as click on a click to call button. Number can
be extension, SIP username, SIP URI or mobile/landline phone)
webphone_api.call(NUMBER);
//Hang-up (usually called
from “disconnect” button click)
webphone_api.hangup();
//Send
instant message (Number can be extension, SIP username. Usually called from a
“send chat” button)
webphone_api.sendchat(NUMBER,
MESSAGETEXT);
}
});
//You should also handle events from the webphone and change your GUI
accordingly (onXXX callbacks)
</script>
</body>
See the webphone
package for more examples. You should check especially the tech demo
(techdemo_example.html / techdemo_example.js).
Note: If you don’t have JavaScript/web
development experience, you can still fully control and customize the webphone:
·
by its numerous configuration
options which can be passed also as URL parameters
·
from server side as described here
·
we can also send ready to use fully
customized web softphone with preconfigured settings, branding and integration
with your web and VoIP server
More details can be found here.
Use the following API calls to control
the webphone:
setparameter
(param, value)
You can use this function to set the
webphone parameters (the various settings which are described in the Parameters chapter) dynamically (at run-time) from JavaScript.
(Alternatively you can just hardcode
the parameters in the webphone_config.js or pass by URL query parameters)
Example:
setparameter('username ', 'john'); //this will set the SIP username to be used for upcoming
registration or call
Note:
All parameters are saved/cached by the
webphone so they will persist (except if you clear the browser storage and/or
cookies).
This function also has a third optional
allowempty parameter. If set to false then empty values are ignored and you
should use 'NULL' instead to clear the previous/cached setting if any. Its
default value is true.
You can clear previously set values using
the delsettings () API or by using the setparameter with an empty or 'NULL’
value. Example: setparameter('displayname', 'NULL');
Return type: string
Will return value of a parameter if
exists, otherwise will return empty string.
Example:
var mystringvariable =
getparameter('displayname '); //this
will return the display name if it was set previously
Optionally you can "start"
the phone, before making any other action.
In some circumstances the
initialization procedure might take a few seconds (depending on usable engines)
so you can prepare the webphone with this method to avoid any delay when the
user really needs to use by pressing the call button for example.
Set the “autostart”
parameter to 0 if
you wish to use this function. Otherwise the webphone will start automatically
on your page load.
If the serveraddress/username/password
is already set and auto register is not
disabled (not 0), then the webphone will
also register (connect) to the SIP server upon start.
If start()
is not called, then the webphone will initialize itself the first time when you
call some other function such as register()
or call().
The webphone parameters should be set
before you call this method (preset in the js file or by using the setparameter() function). See the “Parameters” section for details.
Optionally you can "stop" the
webphone engine (but this is done automatically on browser close or refresh, so
usually not required).
Calling the stop() API will also unregister.
Optionally you can "register"
if your SIP server has also registrar roles (most of them have this). This will
"connect" to the SIP server by sending a REGISTER request and will
authenticate if requested by the server (by sending a second REGISTER with the
digest authorization details).
Note:
o If the serveraddress/username/password
is already set and auto register is not
disabled (not 0), then the webphone will
register (connect) to the SIP server upon start, so no need to use this
function in these circumstances.
o There is no need to call the register() multiple times
as the webphone will automatically manage the re-registrations (based on the registerinterval parameter)
You can use this function to register
with multiple SIP accounts (multi-account feature).
The accounts
are passed as string in the following format: server,usr,pwd,ival,proxy,realm,authuser;server2,usr2,pwd2,ival2,proxy2,realm2,authuser2
For more details read here.
Un-register from your SIP server (will
send a REGISTER with Expire header set to 0, which means de-registration).
Unregister is called also automatically
at browser close so usually there is no need to call this explicitly.
Initiate call to a number, extension,
sip username or SIP URI.
Perhaps this is the most important
function in the whole webphone API.
It will automatically handle all the
details required for call setup (network discover, ICE/STUN/TURN when needed,
audio device open and call setup signaling).
With this function you can make calls via
your SIP server or SIP service provider:
·
to any SIP endpoint (such as
softphone or IP phone)
·
to any WebRTC endpoint
·
to pstn/mobile/landline (if your
server allows outbound calls. If you have a SIP subscription then most probably
you need a positive balance to be able to make pstn calls)
·
to any SIP server (including IVR or
callback access numbers)
You can also send dtmf messages once the
call connected by appending it to the number after a comma. For example if you make a call to 123,456 then it will call
123 and then it will send dtmf 456 once the call is connected.
For video chat use the videocall function mentioned below.
Call disconnect (disconnect the current
call or the call on the active line)
For incoming not yet connected call, hangup acts like reject.
Notes about line-management (in case if
you are implementing a multi-line user interface, otherwise you don’t need to
deal with line numbers):
o
If the line is set to -2 it will
disconnect all active calls.
o
If line is set to -1, then it will
disconnect the call on the current line (default behavior).
o
Otherwise it will disconnect the
call on the specified line.
o
More details here
Connect incoming call.
Disconnect incoming call.
(You can also use the hangup() function for this)
Silently ignore incoming call.
Forward incoming call to the specified number (phone number, username or extension).
For call forward to work, your SIP
server and/or the caller endpoint must support the 301 and 302 response codes
(Moved Temporarily/Permanently).
Forward should be used for incoming
calls only when the call is not connected yet. Otherwise use transfer() to
redirect connected calls.
Hold current call. This will issue an
UPDATE or a reinvite with the hold state flag in the SDP (sendrecv, sendonly,
recvonly and inactive).
Set state to true
to put the call on hold or false to un-hold.
Mute current call.
Pass true for the state to mute or
false to un-mute.
The direction
can have the following values:
0: mute in and out
1: mute out (speakers)
2: mute in
(microphone)
Disable/enable video(stream) during a
video call.
Pass true for the state to mute the
video or false to un-mute.
The direction
can have the following values:
0: mute in and out
1: mute remote
2: mute local
Transfer current call to number which
is usually a phone number or a SIP username. (Will use the REFER method after
SIP standards).
If the number parameter is empty string
and there are two calls in progress, then it will transfer line A to line B.
You can set the mode of the transfer
with the transfertype parameter.
For call transfer to work, your SIP
server and/or the caller endpoint must support the SIP REFER message (the
standard SIP call transfer as specified in RFC 3515 and RFC 5589).
Transfer should be used for connected
calls only. For not connected incoming calls you should use the forward()
function to redirect the call.
More details can be found here.
Add/remove people to conference.
Parameters:
-number: the peer username/number or
line number
-add: true if to add, false to remove
If number is empty than will mix the
currently running calls (interconnect existing calls if there is more than one
call in progress).
If number is a number between 1 and 9
then it will mean the line number.
Otherwise it will call the new number
(usually a phone number or a SIP user name) and once connected will join with
the current session.
Example:
call('999'); //normal call to 999
conference('1234'); //will call 1234 and add
to conference (conference between local user + 999 + 1234)
conference('2',false); //remove line 2 from
conference
conference(''); //add all current calls to
conference
conference('',false); //destroy conference (but
keep the calls on individual lines)
setline(3); //select the third line
hangup(); //will disconnect the third line
setline(-2); //select all lines
hangup(); //will disconnect all lines
Note:
o
if number is empty and there are
less than 2 active calls, then the conference function can’t be used (you can’t
put one single active call into a conference)
o
NS and Java engines also has a
local conference mixer thus they are more reliable for conferencing and doesn’t
depend on any server/gateway/proxy side conference support. If your main
use-case is conferencing then we recommend to force one of these engines
instead of WebRTC.
o
you can also use the webphone with
your server conference rooms/conference bridge. In this way, there is no need
to call this function (just make a normal call to your server conference
bridge/room access number)
o
the conference method can be
changed with the conferencetype parameter
o
more details here
Send DTMF message by SIP INFO or
RFC2833 method (depending on the "dtmfmode"
parameter).
This is often used for on key press
events or keypad events when to send the pressed number to the server or to the
peer for IVR or voicemail inputs.
Please note that the msg parameter is a
string. This means that multiple dtmf characters can be passed at once and the
webphone will streamline them properly.
The dtmf messages are sent with the
protocol specified with the “dtmfmode” parameter.
Use the space character to insert
delays between the digits.
Valid dtmf characters in the passed
string are the followings: 0,1,2,3,4,5,6,7,8,9,*,#,A,B,C,D,space.
Example:
dtmf("1");
dtmf("
12 345 #");
Note: dtmf messages can be
also sent by adding it to the called number after a comma. For example if you
make a call to 123,456 then it will call 123 and then it will send dtmf 456
once the call is connected.
Send a chat message via SIP MESSAGE
method as specified in RFC 3428.
Number can be a phone number or SIP
username/extension number (or whatever is accepted by your server).
The message can be clear ASCII or UTF-8
text or html encoded.
In order for IM to work your SIP server
needs to support SIP
MESSAGE. More details can be found here.
Send a SMS message if your
provider/server has support for SMS.
The number parameter can be any mobile
number.
The msg is the SMS text.
The from is the local user phone number
and it is optional.
SMS can be handled on your server by:
-converting normal chat message to SMS
automatically if the destination is a mobile number
-or via an HTTP API (you can specify
this to the webphone as the “sms” parameter)
More details can be found here.
play (start, file,
looping, toremotepeer)
Play sound file.
At least wave (.wav) files (raw linear
PCM) are supported in the following format: PCM SIGNED 8000.0 Hz (8 kHz) 16 bit
mono (2 bytes/frame) in little-endian (128 kbits).
Parameters:
o start: (number) 1 for start or 0 to stop the playback
o file: (string) file name or full path
o looping: (number) 1 to repeat, 0 to play once
o toremotepeer: (boolean) stream the playback to the
connected peer
Start/stop voice recording at runtime.
Set the start parameter to true for
start or false to stop.
The url is the address where the
recorded voice file will be uploaded as described by the voicerecupload setting.
Note:
You can also just set the “voicerecupload” parameter to have all calls
recorded.
More details about voice recording can be found here.
Initiate a video call to a number,
extension, sip username or SIP URI.
More details about video
calls can be found here.
Initiate a screen sharing session with
the user specified by the number parameter.
Parameters:
·
number: the peer number,
username, extension or SIP URI
·
screenid: optional parameter to
pass the screen id (It might be useful for some special use-case when you
acquire the screen-id via external tools such as the Chrome OS desktop capture
API)
Special
permissions might be needed. See also the screensharing
parameter for details. More details
about video calls can be found here.
Stop screen sharing.
setvideodisplaysize
(type,width, height)
Use this function to control the video
display size (both for remote and local video).
Accepted parameters:
·
type: 1=for remote video
container, 2=for local video container
·
width: integer value of width in
pixels
·
height: integer value of height
in pixels; this parameter can be left empty or null, and the height will be set
depending on the video's aspect ratio
More details can be found in
webphone_api.js and video.css file respectively (You can also set the size in
the video.css file).
Open audio/video device selector dialog
(built-in user interface)
getdevicelist(dev, callback)
Call this function and pass a callback,
to receive a list of all available audio devices.
For the dev parameter pass 0 for
recording device names list, 1 for the playback or ringer devices or 3 for
video camera devices.
The callback will be called
with a string parameter which will contain the audio device names in separate lines (separated by CRLF).
Note:
o
With the Java or NS engine it might
be possible that you receive only the first 31 characters from the device name.
This is a limitation coming from the OS audio API but it should not cause any
problem, as you can pass it as-is for the other audio device related functions
and it will be accepted and recognized.
o
Some browsers requires HTTPS or
file hosting to list the audio devices (might not work from localhost) if you
are using the WebRTC engine.
Call this function and pass a callback,
to receive the currently set audio device.
For the “dev” parameter one of the
followings are expected:
0: for recording
device
1: for the playback
device
2: for ringer device
3: for video camera
The callback will be called with a string parameter, which will contain
the currently selected audio device.
setdevice(dev, devicename, immediate)
Select an audio or video device. The devicename should be a valid audio or video device
name which can be listed with the getdevicelist()
call.
For the “dev”
parameter pass:
0: for recording
device
1: for the playback
device
2: for ringer device
3: for video camera
The "immediate"
parameter can have the following values:
0: default
1: next call only
2: immediately for active calls
Note:
o Before
calling this function, you might call the getdevice function first to obtain
the available devices. Then pass one of them with this setdevice API.
o When
using the NS winapi audio engine, the device names might be truncated to the
first 31 characters due to the wave audio API limitations. You can pass the
same back to the webphone and it will select the audio device correctly.
o The ring
device cannot be changed at runtime (the immediate flag will not have any
effect if you call this function while the webphone is already ringing).
o For the
WebRTC engine the ringtone playback needs user interaction. No ringtone will be
played for incoming calls if the user doesn’t interact with the webphone before
the call arrives due to browser media permission / auto-play policy as
described here.
Call this function, passing a callback
and will return the volume (percent) for the selected device.
The dev
parameter can have the following values:
0 for the recording (microphone) audio device
1 for the playback (speaker) audio device
2 for the ringback (speaker) audio device
The callback will be called with the volume parameter
which will be 0 (muted), 50 (default volume) or other positive number.
Note: the reason why this needs a callback (and doesn’t
just returns the volume as the function return value is because for some
engines the volume will be requested in an asynchronous way so it might take
some time to complete).
Set volume
(percent for the selected device).
0% means muted, 100% means maximum volume.
Default value is 50%, which means no change.
The dev
parameter can have the following values:
0 for the recording (microphone) audio device
1 for the playback (speaker) audio device
2 for the ringback (speaker) audio device
WebRTC limitations:
-Changing the recording volume level for WebRTC at run-time will take
effect only for the next call. You can also use the volumein
parameter to change the default volume.
-Some browsers doesn’t support changing the volume with WebRTC. It is
expected that the user will control the volume with the OS volume settings.
-A separate volume for ring is not supported on WebRTC
Call this function with boolean
parameter "true" to set the default playback device to loudspeaker on
supported devices such as Android phones and tablets.
The speakerphone will be restored if
called with “false”.
Note: You can also use the androidspeaker
parameter to preconfigure.
Set a custom sip header (a line in the
SIP signaling) that will be sent with all messages.
Can be used for various integration
purposes (for example for sending the http session id or any custom data).
For example: setsipheader('X-MyExtra:
whatever');
You can also set extra SIP headers with
the customsipheader parameter (setting this parameter is the easiest way
if you have some parameter which have to be sent always, regardless of the
circumstances)
Note:
·
It is recommended to prefix
customer headers with X- so it will bypass SIP proxies.
·
Multiple lines can be separated by
semicolon ; Example: setsipheader('X-MyExtra1: aaa; X-MyExtra2: bbb');
If you must use semicolon in the string, then use the
CRLF separator even if you have to set only one SIP header (in this case just
append it at the end)
·
Multiple lines can be also set by
calling this function multiple times with different keys.
·
There are two kinds of headers that
you can set:
o
Global (set for all lines including
the registrar endpoint): if the line is -2 or there is no current call on the
selected line (for example if you set it at startup, before any calls or with
line set to -2)
o
Per line: if the current line is
set and there is an active call on that line.
Note that you cannot set it for not already existing
lines (lines which doesn’t have calls on it yet. For the upcoming call you
should set it globally)
·
You can remove all the previously
passed headers (per line or global) by calling this function with an empty
string. Example: setsipheader(‘’);
·
You can remove a previously set
header by calling this function with an empty key for that header. Example:
setsipheader('X-MyExtra:');
getsipheader(header, callback, must)
Call this function passing a callback.
Example: getsipheader("Contact",
mycallback); //will call mycallback with the
Contact header from the incoming message
The passed callback function will be
called with one parameter, which will be the string value of the requested sip
header from the received SIP messages (received from your server of from the
other peer). If no such header is found or some other error occurs, then the
returned string begins with “ERROR” (for example: “ERROR:
no such header”) so you might ignore these.
The must parameter is optional and
defaults to false. If set to true, then the webphone might try to return the
header from any line (not just the current active line).
Note:
-The reason why this needs a callback
(and doesn’t just returns the last seen header values is because for some
engines the signaling messages have to be requested in an asynchronous way so
it might take a little time –usually only a few milliseconds- to complete the
request).
-The getsipheader() will send you the
headers from the incoming SIP messages (not the headers previously set by the
setsipheader() function call)
-If you are using the WebRTC engine with
a WebRTC-SIP gateway, then you should prefix the extra headers with X- to have
to forwarded by the gateway. For example instead of Alert-Info: URN your SIP
server should send X-Alert-Info: URN.
getsipmessage(dir,
type, callback, must)
Will return the last SIP signaling
message as specified by the current line and the dir/type parameters.
Call this function passing a callback.
Example: getsipmessage(0,
3, mycallback); //will call mycallback with
the incoming INVITE message text on the current line
The passed callback function will be
called with one parameter, which will be the string value of the requested sip
message as raw text.
If no such message is found or some
other error occurs, then the returned string begins with “ERROR” (for example:
“ERROR: SIP message not found”) so you might
ignore these.
The following parameters are defined:
dir:
-1: any
0: in
(incoming/received message)
1: out (outgoing/sent
message)
type:
0: any
1: SIP request (such as
INVITE, BYE)
2: SIP answer (such as
200 OK, 401 Unauthorized and other response codes)
3: INVITE (the last
INVITE received or sent)
4: the last 200 OK
(call connect, ok for register or other)
callback:
The callback function
must:
Optional boolean value.
Defaults to false.
If set to true, then
the webphone might try to return a SIP message from any line (not just the
current active line).
You can use this function if you have
good SIP knowledge and wish to parse the SIP messages yourself from JavaScript
for some reason (for example to extract some part of it to be processed for
other purposes).
Example to return the last received
INVITE message about an incoming call: getsipmessage(0,3,mysipmsgrecvcallback)
Note: just as other functions, this will
take in consideration the active line (set by setline() or auto set on in/out
call setup). You can set the active line to “all” [with setline(-2)] to get
the last message regardless of the line.
getlastrecinvite
(callback)
Get last received SIP INVITE message.
This is a simplified version of the
getsipmessage function if you are interested only in the last received INVITE
request.
Call this function passing a callback.
The passed callback function will be
called with one String parameter, which will be the last incoming call's SIP
INVITE message.
This is a helper function which might
be useful to get the whole INVITE message on call setup.
getlastsentinvite
(callback)
Get last sent SIP INVITE message.
This is a simplified version of the
getsipmessage function if you are interested only in the last sent INVITE
request.
Call this function passing a callback.
The passed callback function will be
called with one String parameter, which will be the last outgoing call's SIP
INVITE message.
This is a helper function which might
be useful to get the whole INVITE message on call setup.
Will return the state and various
parameters of an endpoint as a string in the following format:
LINEDETAILS,line,state,callid,remoteusername,localusername,type,localaddress,serveraddress,mute,hold,remotefullname
Basically, the parameters here are very
similar with the STATUS parameters described here.
Returns an unstructured string with
details about the previously disconnected call.
You should call this function after the
call is actually finished. For example after the onCdr callback have been fired.
For example in case of the NS engine,
this might return something like:
Line: 1 , Direction:
outgoing
Local Username: CALLER
, AuthUsername: CALLER
Peer Username: CALLED ,
Name: CALLED Called: CALLED
Server: SERVERDDRESS
Connectime: X msec
Duration: X msec
Disc By: Local ,
Reason: User Hung Up
AEC_SETT: 1, AEC_FULL:
2, AEC_FAST: 2, no, AEC_VOL: 1, AGC: 2, Denoise: 2, mediaench: aec: 2, denoise:
2, agc: 2, silencesupress: 0
Payload: X CODEC, pf:
1, network: fast
CPU: speed: 3500, load:
0.0, reccpuhigh: false, subshigh: 0, highdetected: no, meassured: 0 0
Audio: Record: count:
254 ival: 20 last: 5 0 Playback: count: 257 ival: 20 last: 5 0 issues: 2 500 16
Queue: 1 0 2 4 0
getcallerdisplayfull (callback)
Call this function and pass a callback,
to receive the incoming detailed caller id (might return two lines: caller id
\n caller name)
Note: If you just need the caller id,
you should just use the onCallStateChange peer name instead of this function.
The callback will be called with a
string parameter which will contain the incoming detailed caller id.
See the Caller-ID FAQ point for more details.
Returns a string with the reason about
failed connect/registration.
Deprecated! Use the onRegStateChange callback “unregistered” event instead!
This function can be used for explicit
line/channel management and it will set the current active channel.
For the line
parameter you can pass one of the followings:
-line number: -2 (all),
-1 (current/best), 0 (invalid), 1 (first channel), 2 (second channel) …. 100
-call id (so the active
line will be set to the line number of the endpoint with this SIP Call-ID)
-peer username (so the
active line will be set to the line number of the endpoint where the peer is
this user)
Use this function only if you present
line selection for the users. Otherwise you don’t have to take care about the
lines as it is managed automatically (with each call on the first “free” line)
Note:
o You can set the line to -2 and -1 only for a short
period. After some time the getline() will
report the real active line or “best” line.
o The internal state machine might automatically change
the active line after 300 milliseconds (this means that you must perform the
operation on the selected line quickly after this setline API call)
o Using the setline function will not mute the other
lines if there are multiple simultaneous calls. It will just select the line
for any further operation. For example if you wish to mute line 2, then you
have to call setline(2); and then mute(true);
More details about multi-line can be
found in the FAQ.
Return type: number
Will return the current active line
number. This should be the line which you have set previously except after
incoming and outgoing calls (the webphone will automatically switch the active
line to a new free line for these if the current active line is already
occupied by a call).
More details about multi-line can be
found in the FAQ.
linetocallid (line, callback)
Utility function to get the SIP Call-ID
for a line number. Might be useful in some circumstances.
The passed callback function will be
called with one parameter, which will be the SIP Call-ID for the passed line
number.
If not found then an empty string will
be returned in the callback.
callidtoline
(callid, callback)
Utility function to get the line number
for a SIP Call-ID. Might be useful in some circumstances.
The passed callback function will be
called with one parameter, which will be the line number for the passed SIP
Call-ID.
If not found then a negative line
number will be returned.
Set/get the SIP Call-ID used for the
first upcoming new SIP session.
This function might be used if you need
the SIP Call-ID before the call for some reason. For example you can use it
before the call function to set/get the SIP
Call-ID of the new call. Otherwise the webphone will automatically generate an
unique SIP Call-ID for each new session which you can query using the linetocallid function or receive it with the onCallStateChanged or onCdr
callbacks.
If this function is called without the
callid parameter or the callid as an empty string then the webphone will
generate and return a random call-id.
The return value is the new SIP Call-ID
as string.
Return type: boolean
Return true if the webphone is
registered ("connected") to the SIP server.
Note: you can track the phone state
machine also with the events
callbacks or check this FAQ.
Return type: boolean
Return true if the webphone is in call,
otherwise false.
Note: you can track the phone state
machine also with the events callbacks.
Return type: boolean
Return true if the call is muted,
otherwise will return false.
Return type: boolean
Return true if the call is on hold,
otherwise will return false.
Check if communication channel is
encrypted: -1=unknown, 0=no, 1=partially, 2=yes, 3=always
Subscribe to call state of
other extensions to receive call state change information as BLF notifications
by triggering the onBlfStateChange callback.
Userlist: list of sip account username separated by comma.
In order for BLF (busy
lamp field) to work, make sure that your server and peer(s) has support for BLF
subscribe/notify with dialog event package as described in RFC 3265 and RFC
4235.
Note:
If BLF is an important feature for you, then we recommend
the usage of the NS or Java engines as this is unreliable with WebRTC (set the
enginepriority_ns and enginepriority_java to 4)
More details here.
Will receive presence information
PRESENCE notifications and will trigger the onPresenceStateChange callback.
Userlist: list of sip account username separated by comma.
In order for presence to work, make
sure that your server has support for subscribe/notify. More details here.
setpresencestatus
(status)
Function call to change the user online
status with one of the followings strings: Online, Away, DND, Invisible,
Offline (case sensitive).
Returns the currently used engine name
as string: "java", "webrtc", "ns",
"app", "flash", "p2p", "nativedial".
Can return empty string if engine
selection is in progress.
Might be used to detect the
capabilities at runtime (for example whether you can use the jvoip function or
not)
This function will return a String
containing the whole call history list. If there are no entries in call
history, it will return null.
Call history entries will be separated
by "carriage return new line": \r\n
Call history fields will be
separated by "tabs": \t
The order of fields and their meaning:
o
type: int - 0=Outgoing call,
1=Incoming call, 2=Missed call
o
name: String - can be a name, can
be the same as the number or can be empty String
o
number: String - the phone
number/SIP URI
o
date: int - timestamp date of
call
o
duration: int - duration of the
call in milliseconds
o
discreason: String - call
disconnnect reason
Example: 1 \t Name \t Number \t Date
\t Duration \t Discreason
This function will return a String
containing the whole contact list. If there are no contacts, it will return
null.
Set the all parameter to true to
receive also virtual contacts as well, like voicenumber, etc...
Contacts will be separated by
"carriage return new line": \r\n
Contact fields will be
separated by "tabs": \t
A contact can have more than
one phone numbers or SIP URIs, so these will be separated by Pipe(Vertical
bar): |
See example below:
The order of fields and their meaning:
name: String - the name of the contact
number: array of String - the
number(s)/SIP URI(s) of the contact
favorite: int - 0=No, 1=Yes
email: String - email address of the
contact
address: String - the address of the
contact
notes: String - notes attached to this
contact
website: String: web site attached to
this contact
types: array of String –the type of the
above number(s)
Example: Name \t Number1|Number2 \t
Favorite \t Email \t Address \t Notes \t Website \t Type1| Type2 \r\n
addcontact
(fullname, number, email, address, notes, website, type, favorite)
Add a contact to the contact list.
This is useful only with the softphone
skin (otherwise most probably you don’t need a contact list or you manage it
yourself on a custom user interface after your needs).
The number and the type can be a list (strings separated by | ).
For the type you can set any string, but on the softphone skin only the
following are handled: phone, home, mobile, work, other, fax_home, fax_work,
pager, sip.
Examples:
webphone_api.addcontact('Kate',
'1111'); //add a simple
contact with name: Kate, number: 1111
webphone_api.addcontact('John
Smith', '2222|3333'); //add
contact with name: John Smith and two numbers
webphone_api.addcontact('James
Oliver', '+40741234567’, 'james@gmail.com', 'Victoria street', 'hi',
'www.example.com', 'mobile', '1'); //add a favorite contact with all parameters set
webphone_api.addcontact('James
Oliver', 444444|555, 'james@gmail.com', 'Victoria street', 'hi',
'www.example.com', 'phone|sip', '0'); //add contact with multiple numbers and all parameters set
Note:
Contacts can be prepopulated also by using the defcontacts
parameter.
If the normalize_contact parameter
is set to 1, then the webphone will
“normalize” the contact details. Set to 0 if
you wish to disable this.
getcontact
(name, number)
Call this function passing the name
and/or number of the contact.
Will return a String with the following
parameters separated by "tabs": \t if found:
·
name: String - the name of the
contact
·
number: String - number(s)/SIP
URI(s) of the contact separated by Pipe(Vertical bar): |
·
favorite: int - 0=No, 1=Yes
·
email: String - email address of
the contact
·
address: String - the address of
the contact
·
notes: String - notes attached to
this contact
·
website: String: web site
attached to this contact
·
type: the type of the above
number(s)
If contact is not found, then it will
return null.
delcontact
(name, number)
Delete contact from the contact list
where the name or the number match.
This is useful only with the softphone
skin (otherwise most probably you don’t need a contact list or you manage it
yourself on a custom user interface after your needs).
Use the delallcontacts()
API if you wish to delete all contacts.
Returns the working directory for the
NS and Java engines (not applicable for WebRTC and Flash).
The working directory is the folder
which is used to save any files (configurations, logs, voice recordings).
Delete stored data (from cookie, config
file and local-storage).
For the level parameters is optional
and it can be set to one of the followings:
·
0: delete the settings only if it
was not already cleared (default)
·
1: delete the settings
·
2: force all (delete everything:
settings, contacts, call history, messages and all other data)
·
3: delete also library cache
Warning: this will delete all settings, even those that should be
remembered between sessions, such as “Have we already asked X from the
enduser?”. To deal with different settings we recommend using the profiles instead of using this API or just set unneeded
settings to NULL. More details can be found here.
This API might stop or restart the SIP engine.
You should call this on logout (not at start) if for some reason you
wish to delete the stored phone settings.
Returns a string containing all the
accumulated logs by the webphone (the logs are limited on size, so old logs
will be lost after long run).
More details about logs can be found
here.
Returns the webphone global status. The
possible returned texts are the same like for getEvenetsnotifications.
You might use the events described
below instead of polling this function.
We have listed all the important and
commonly used API’s in this documentation, however, there are some other
advanced/deprecated/internal API’s that can be accessed.
Advanced functions
There are a few additional not so
important functions provided in the webphone_api.js.
Inspect the webphone_api.js file for the details.
Helper functions
There are a few helper/internal/not so
important functions that can be accessed from \js\lib\api_helper.js.
WebRTC internals
When using the WebRTC engine, you can
access the WebRTC browser API via the following functions:
webphone_api.getrtcsocket() -Returns a reference to the WebRTC engine socket object.
Returned value can be null or the reference to the WebSocket object.
webphone_api.getcallsession (line,
destnr, callid) -Returns a reference to the internal
call session object. Returned value can be null or the reference to the call
session object. You might pass one or more parameters to specify the required
call session: line, destination number, Call-ID. If no parameters are
specified, then it will return the default/current session if any.
webphone_api.getrtcpeerconnection(line,
destnr, callid) -Returns a reference to the
current/last WebRTC RTCPeerconnection object or null if no RTCPeerconnection
exists.
Deprecated functions
The webphone is fully backward and
forward compatible and we never remove old functions. All the old deprecated
functions can be still used as-is, without the need to change your code. These
functions are declared in the webphone_api.js or moved to \js\lib\api_helper.js
(they are still available via the webphone_api object).
The major deprecated functions are the
followings:
·
onLoaded, onStart, onStop
(replaced with onAppStateChange)
·
onRegistered, onRegisterFailed,
onUnRegistered (replaced with onRegStateChange)
·
callSetup, callRinging,
callConnected, callDisconnected (replaced with onCallStateChange
setup/ringing/connected/disconnected events)
·
onDisplay, onLog, onEvents
(replaced with onEvent)
The call state events strings was also
changed from callSetup/callRinging/callConnected/callDisconnected to
setup/ringing/connected/disconnected. You can restore the old behavior by
setting the apibehaviour to 0. For the new behavior you can set the
apibehaviour parameter to 1. New webphone build are set with this by default.
For old customers the default value is -1 which means reporting strings both in
old and new format.
Internal engines
If engine is Java or the NS Service
plugin, then you can access the full low-level API as described in the JVoIP SDK documentation.
This can be done with the jvoip function call:
jvoip(name, jargs)
Parameters:
Name: name of the function
Jargs: array of arguments passed to the
called function. Must be an array, if API function has parameters. If API
function has no parameters, then it can be an empty array, null, or omitted
altogether.
For example the low level API function:
API_Call(number) can be called like this: webphone_api.jvoip('API_Call',
line, number);
The below callback functions can be
used to receive events from the webphone such as the phone state machine status
(registered/call init/call connected/disconnected) and other important events
and notifications.
Note: passing null as the callback
parameter for these functions will remove all previously set callbacks (clear
the internal callback functions array).
onAppStateChange (callback)
You can use this function to track app
state changes.
The passed callback function will be
called on every webphone app state change. The callback function has a state string parameter containing the new state of
the application.
The states are the followings:
·
"loaded"
- the webphone library is completely loaded so you can start the usage (call
any other API functions only after this state is received!).
·
"started"
- the VoIP engine has successfully started (ready to register or make calls).
Note: you can initiate calls also from the “loaded” event and it will be queued
to be executed after started.
·
"stopped"
- the VoIP engine has stopped (all endpoints unregistered/disconnected and the
sipstack was destroyed). Usually triggered at page unload.
Example:
webphone_api.onAppStateChange(function
(state) //watch
for webphone state changes
{
if (state === 'loaded') //webphone library loaded
{
webphone_api.setparameter("name",
"value"); //set any parameters
webphone_api.start(); //start if not started
automatically (for example if the autostart parameter is set to 0)
//setup call state machine
watcher
webphone_api.onCallStateChange(function
(event, direction, peername, peerdisplayname, line, callid)
{
//handle
any call events here. For example to catch the call connect events:
if
(event === 'connected')
{
alert("Call
connected with " + peername);
}
//else if (event === ' disconnected') …
});
}
else if (state ===
'started') //sip
stack started
{
webphone_api.call('NUMBER');
//make a call
immediately once started
}
});
Note: the onAppStateChange deprecated to old onLoaded, onStart and
onStop functions but these are still available and you don’t need to change any
old code.
onRegStateChange
(callback)
You can use this function to track
register state changes.
The REGISTER method in SIP is used to
“connect” to the SIP server, so the server can learn the device location to be
used to route incoming calls and other messages.
The passed callback function will be
called on every register state change with a state string parameter.
The states are the followings:
·
"registered"
– registered successfully to the SIP server
·
"unregistered"
– unregistered from the SIP server (if user closes the webpage, then you might
not have enough time to catch this event)
·
"failed"
– register failed. You can receive the cause of the failure in a second reason
string parameter.
onCallStateChange
(callback)
You can use this function to track call
state changes.
The passed callback function will be
called on every call state change (triggered when the webphone is in call).
Parameters:
·
event: can have following string
values: setup, ringing,
connected, disconnected (other events such as "midcall" can be ignored)
·
direction: 1 (for outgoing call), 2 (for
incoming call)
·
peername: is the other party
username (or phone number or extension)
·
peerdisplayname: is the other
party display name if any
·
line: channel number (this might
be important only if you wish to handle multi-line management explicitly)
·
callid: SIP Call-ID
A simple usage example can be found here.
Note:
o the call might
change from setup state directly into disconnected state if it was connected
o ringing
state is optional (it is not a definitive answer for the INVITE transaction so
it is not mandatory in SIP)
o you might
receive other event strings which can be just safely ignored
onPresenceStateChange
(callback)
You can use this function to track
presence changes.
The passed callback function will be
called on every presence (online/offline/others) state change (of the remote
users).
To initiate presence requests, you can
use the checkpresence() API or the presenceuserlist parameter.
Parameters:
·
peername: is the other party
username (or phone number or extension)
·
presence: can have following
values: CallMe,Available,Pending,Other,CallForward,Speaking,Busy,Idle,DoNotDisturb,Unknown,Away,Offline,Exists,NotExists,Unknown
·
displayname: optional peer
display name if sent as part of presence
·
email: optional peer email
address if sent as part of presence
onBLFStateChange
(callback)
You can use this function to track BLF
changes.
The passed callback function will be
called on every call state change (of the remote users) which might be used as
BLF (busy lamp field)
To initiate presence requests, you can
use the checkblf() API or the blfuserlist parameter.
Parameters:
·
peername: is the other party
username (or phone number or extension)
·
direction: can have one of
following values: undefined, initiator (outgoing call) or receiver (incoming
call)
o
undefined (not for calls or no announced by the peer)
o
initiator (outgoing call)
o
receiver (incoming call)
·
state: can have one of following
values: trying , proceeding, early, comfirmed, terminated, unknown or failed
o
trying (call connect initiated)
o
proceeding (call connecting)
o
early (ringing or session progress)
o
confirmed (call connected)
o
terminated (call disconnected)
o unknown (unrecognized call state received)
o
failed (BLF subscribe or notify failed)
·
callid: optional SIP call-id of
the call (if reported by the BLF notify)
The passed callback function will be
called when chat message is received.
Parameters:
·
from: username, phone number or
SIP URI of the sender
·
msg: the content of the text
message
·
line number
·
group: group name; the name of
the group if it's group chat, otherwise it will be an empty string or “null”
(“null” might be received if other endpoint has group chat support but this
message is not part of a group chat
The passed callback function will be
called when an SMS message is received.
Might be triggered only if the server
has VoIP SMS support or SMS API implemented.
Parameters:
·
from: username, phone number or
SIP URI of the sender
·
msg: the content of the text
message
The passed callback function will be
called when a DTMF digit is received.
Parameters:
·
dtmf: received DTMF character as
string
·
line: channel number
Supported DTMF receive method with all engines is INFO SIP messages.
The NS and Java engines has support also for RFC 2833 in RTP.
The passed callback function will be
called at each call disconnect. You will receive a CDR (call detail record).
Parameters:
·
caller: the caller party username
(or number or sip uri)
·
called: called party username (or number
or sip uri)
·
connect time: milliseconds
elapsed between call initiation and call connect/reject/cancel (includes the
call setup time + the ring time)
·
duration: milliseconds elapsed
between call connect and hangup (0 for not connected calls, otherwise you might
add 400 and divide by 1000 to obtain rounded seconds)
·
direction: 1 (outgoing call), 2
(incoming call)
·
peerdisplayname: is the other
party display name if any
·
reason: disconnect reason as
string
·
line: channel number
·
callid: SIP Call-ID
Note:
Missing values are empty or set to “NA”.
You can get some more details about the
call by using the getlastcalldetails() function.
Every SIP server is capable to store CDR
records, however if somehow you have some special requirement, then you can
also submit the CDR from this callback to your web service API (for example if
the SIP server is not owned by you or if you need any extra or special
processing).
More details here.
You might use this function to receive
internal events, logs and messages that might be processed or displayed to
users.
This should be used only if for some
reason you need more than the above described onCallStateChange and other callbacks.
Call this function once and pass a
callback, to receive important events, which should be displayed for the user
and/or parsed to perform other actions after your software custom logic. You
will also receive all log messages depending on the value of
"loglevel" parameter.
For the included softphone these are
already handled, so no need to use this, except if you need some extra custom
actions or functionality which depends on the notifications.
Parameters:
·
type: the type of the message. This can have the
following values:
o event: low level notifications which can be parsed as string.
Example: STATUS,1,Ringing,2222,1111,2,Katie,[callid]
Instead of parsing these low level string
notifications, you should use the callback functions instead such as
onAppStateChange, onCallStateChange, onChat and the other onXXX functions.
See the “Notifications”
section below for all possible strings.
o log:
log messages
Usually you don't need to check for the logs.
You might watch for this only if you wish to collect
the logs for some purpose or you have to watch for a log string to be
triggered.
It can be used for debugging or for log redirection
if the other
possibilities don’t fit your needs.
o display: important messages to be displayed for the user.
If you wish to handle the popups yourself, then
disable popups by settings showtoasts
parameter to "false". From here on you will be responsible for
presenting these messages to the user.
If type is "display", then the
"message" parameter will be composed of a "title" until the
first comma and a "text".
The title can be an empty string, in which case the
message begins with a comma.
·
message: the text of the event/log/display
webphone_api.onEvent(
function (type, message)
{
//
For example the following status means that there is an incoming call ringing
from 2222 on the first line:
//
STATUS,1,Ringing,2222,1111,2,Katie,[callid]
//
You can find more detailed explanation about events in the documentation
"Notifications" section.
//
example for detecting incoming call:
if
(type === 'event')
{
var
evtarray = message.split(','); //parameters are separated by comma (,)
if
(evtarray[0] === 'STATUS' && evtarray[2] === 'Ringing')
{
if
(evtarray[5] === '1') // 1 means it is an outgoing call
{
//add any custom logic
here, for example you might lookup the caller from a database
alert('Incoming
call from: '+evtarray[3] + ' ' + evtarray[6]); //of course, instead of alert you should
use some better html display
}
}
}
// example for handling
displayable messages
else
if (type === 'display')
{
var
position = message.indexOf(',');
var
title = message.substring(0, position); // NOTE: title can be empty string
var
text = message.substring(position + 1);
alert(title+'\r\n'+text);
//of course,
instead of alert you should use some better html display
//NOTE: If you wish to
handle the popups yourself, then disable popups by settings
"showtoasts" parameter to "false".
}
});
Notes:
o This is a new function in v.3.0 to replace the old
onDisplay, onLog and onEvents callback.
o It is possible to use this function to catch all the
event notifications to track all state machine changes instead of the
onAppStateChange, onCallStateChange, onChat and the other onXXX functions.
However, we recommend to use the high level callback functions instead of error
prone string parsing from this onEvent function.
o You might also check the basic_example.html included
in the package regarding the onEvent function usage.
o display type events:
With the display messages you can receive important
events and notifications (as strings) that should be displayed to the user.
For example:
o "Invalid phone
number or SIP URI or username" (displayed if user is trying to call
an invalid peer)
o "Waiting for
permission. Please push the Allow/Share button in your browser..." (when waiting for WebRTC browser permission)
o “Check your microphone!
No audio record detected.” (which is displayed after 6 seconds in calls
if the VAD doesn’t report any activity).
The text of the message is language dependent,
meaning if the language of the webphone is changed, the message/title language
is also changed.
Engine selection related popups are always handled by
the webphone (However these are presented only when really necessary and can be
suppressed by forcing the webphone to a single engine)
Notifications
will be displayed as auto-hiding popups if not disabled with the showtoasts parameter
“Notifications” means simple string
messages received from the webphone which you can parse from the onEvent(callback) to receive notifications and events from
the sip web phone about its state machine, calls states and important events.
Skip this section if you are not using
the onEvent() function catching the “event” messages. (You can use the functions
such as onRegStateChange/onCallStateChange/others to catch the important events
in which you are interested in and completely skip this section about the
low-level notification strings handling).
If you are using the onEvent() function then you can parse the received
event strings from your java script code. Each notification is received in a
separate line (separated by CRLF). Parameters are separated by comma ‘,’. For
the included softphone and click to call these are already handled, so no need
to change, except if you need some extra custom actions or functionality.
The following messages are defined:
STATUS,line,statustext,peername,localname,endpointtype
You will receive STATUS notifications
when the SIP session state is changed (SIP session state machine changes) or
periodically even if there was no any change.
A typical status strings looks like
this:
STATUS,line,statustext,peername,localname,endpointtype,peerdisplayname,[callid],online,registered,incall,mute,hold,encrypted,isvideo
The line parameter can be -1 for
general status or a positive value for the different lines.
General status means the status for the
“best” endpoint.
This means that you will usually see
the same status twice (or more). Once for general sip client status and once
for line status.
For example you can receive the
following two messages consecutively: STATUS,-1,Connected,…
You might decide to parse only general
status messages (where the line is -1), messages for specific line (where line
is zero or positive) or both.
Status notifications are sent on state
change but also at a regular interval (so you can see the same notification
again and again even if there was no state change).
The following statustext values
are defined for general status (line set to -1):
o Initializing
o Ready
o Register…
o Registering…
o Register Failed
o Registered
o Accept
o Starting Call
o Call
o Call Initiated
o Calling…
o Ringing…
o Incoming…
o In Call (xxx sec)
o Hangup
o Call Finished
o Chat
Note: general status means the “best” status among all lines. For example
if one line is speaking, then the general status will be “In Call”.
The following statustext values
are defined for individual lines (line set to a positive value
representing the channel number starting with 1):
o Unknown (you should not receive this)
o Init (started)
o Ready (sip stack started)
o Outband (notify/options/etc. you should skip this)
o Register
(from register endpoints)
o Subscribe (presence or BLF)
o Chat (IM)
o CallSetup
(one time event: call begin)
o Setup (call init)
o InProgress (call init)
o Routed (call init)
o Ringing (SIP 180 received or similar)
o CallConnect
(one time event: call was just connected)
o InCall (call is connected)
o Muted (connected call in muted status)
o Hold (connected call in hold status)
o Transfer
o Conference
o Speaking (call is connected)
o Midcall (might be received for transfer,
conference, etc. you should treat it like the Speaking status)
o CallDisconnect (one time event: call was just disconnected)
o Finishing (call is about to be finished. Disconnect
message sent: BYE, CANCEL or 400-600 code)
o Finished (call is finished. ACK or 200 OK was
received or timeout)
o Deletable (endpoint is about to be destroyed. You
should skip this)
o Error (you should not receive this)
You will usually have to display the
call status for the user, and when a call arrives you might have to display an
accept/reject button.
For simplified call management, you can
just check for the one-time events (CallSetup, CallConnect, CallDisconnect)
Peername is the other party username (if any)
Localname is the local user name (or username).
Endpointtype is 1 from client endpoints and 2 from server
endpoints.
Peerdisplayname is the other party display name if any
Optional values (you might not always
receive these):
CallID: SIP session id
Online: network status. 0 if no network or internet
connection, 1 if connectivity detected (always the global status)
Registered: registration state. 0=unknown,1=not
needed,2=yes,3=working yes,4=working unknown,5=working no,6=unregistered, 7+
=no (failed) (always the global status)
InCall: phone/line is in call. 0=no,1=setup or
ringing,2=speaking
Mute: is muted status. 0=no,1=undefined,2=hold,3=other
party hold,4=both in hold (or if you wish to simplify: 0 means no, others means
yes)
Hold: is on hold status: 0=no,1= undefined,2=hold,3=other
party hold,4=both in hold (or if you wish to simplify: 0 means no, others
means yes)
Encrypted: encryption status: -1: unknown,
0=no,1=partially/weak yes,2=yes,3=always strong (or if you wish to simplify: 0
and -1 means no, others means yes)
Isvideo: set to 1 for video calls (with video media offer).
Otherwise 0.
For example the following status means
that there is an incoming call ringing from 2222 on the first line:
STATUS,1,Ringing,2222,1111,2,Katie,[callid]
The following status means an outgoing
call in progress to 2222 on the second line:
STATUS,2,Speaking,2222,1111,1,[callid]
To display the “global” phone status,
you will have to do the followings:
1.
Parse the received string (parameters
separated by comma)
2.
If the first parameter is
“STATUS” then continue
3.
Check the second parameter. It
“-1” continue otherwise nothing to do
4.
Display the third parameter (Set
the caption of a custom html control)
5.
Depending on the status, you
might need to do some other action. For example display your “Hangup” button if
the status is between “Setup” and “Finishing” or popup a new window on
“Ringing” status if the endpointtype is “2” (for incoming calls only; not for
outgoing)
If the “jsscripstats” is on (set to a
value higher than 0) then you will receive extended status messages containing
also media parameters at the end of each call:
STATUS,1,Connected,peername,localname,endpointtype,peerdisplayname,rtpsent,rtprec,rtploss,rtplosspercet,serverstats_if_received,[callid]
REGISTER,line,state,text,main,fcm,user,reason
This notification is received for
register state changes from registrar endpoints.
The notification is sent only from the
NS and Java engines (not from WebRTC).
line: channel number (should be always 0 for
register)
state: 0: in progress,
1: success, 2: failed, 3: unregistered
text: register state as text
main: true for primary account, false for secondary
registrations (if you are using multiple
accounts)
fcm: not used (ignore)
user: local username (useful if you are using
multiple accounts)
reason: failure reason text if any
Note: This notification can be disabled
by setting the sendregisternotifications parameter
to 0 (for compatibility reasons with old
versions).
PRESENCE,peername,state,details,displayname,email
This notification is received for
incoming chat messages.
Line: used phone line
Peername: username of the peer
State and details: presence status string; one of the
followings:
CallMe,Available,Open,Pending,Other,CallForward,Speaking,Busy,Idle,DoNotDisturb,DND,Unknown,Away,Offline,Closed,Close,Unreacheable, Unregistered,Invisible,Exists,NotExists,Unknown,Not
Set
Displayname: peer full name (it can be empty)
Email: peer email address (it can be empty)
Notes for the state and details fields:
One of these fields might be empty in some
circumstances and might not be a string in the above list (especially the
details).
The details field
will provide a more exact description (for example “Unreachable”) while the state field will provide a more exact one (for
example “Close”). For this reason if you have a presence control to be
changed, check the details string first and
if you can’t recognize its content, then check the state
string. For displaying the state as text, you should display the details field (and display the state field only if the details
string is empty).
BLF,peername,direction,state,callid
These notifications are received as an
answer for a previous checkblf() request or
if the blfuserlist was set and it represents
the call state of the peer.
Peername: username of the peer extension
direction: undefined, initiator or receiver
state: trying, proceeding, early, confirmed,
terminated, unknown or failed
callid: option sip call-id of the call
This notification is received for
incoming chat messages.
Line: used phone line
Peername: username of the sender
Text: the chat message body
This notification might be received
when the other peer start/stop typing (RFC 3994):
Line: used phone line
Peername: username of the sender
Composing: 0=idle, 1=typing
This notification is received for the
last outgoing chat message to report success/fail:
Line: used phone line
Peername: username of the sender
Status: 0=unknown,1=sending,2=successfully
sent,3=failed to send
Text: failure reason (if Status is 3)
After each call, you will receive a CDR
(call detail record) with the following parameters:
Line: used phone line
Peername: other party username, phone number or SIP
URI
Caller: the caller party name (our username in case
when we are initiated the call, otherwise the remote username, displayname,
phone number or URI)
Called: called party name (our username in case when
we are receiving the call, otherwise the remote username, phone number or URI)
Peeraddress: other endpoint address (usually the VoIP
server IP or domain name)
Connecttime: milliseconds elapsed between call
initiation and call connect
Duration: milliseconds elapsed between call connect
and hangup (0 for not connected calls. Divide by 1000 to obtain seconds.)
Discparty: the party which was initiated the
disconnect: 0=not set, 1=local, 2=peer, 3=undefined
Disconnect reason: a text about the reason of the
call disconnect (SIP disconnect code, CANCEL, BYE or some other error text)
DTMF,line,peername,status,text
Incoming DTMF notification
(the digit is passed in the msg parameter)
VREC,line,stage,type,path,reason
Voice upload status (for voice recording / call
recording).
line: channel number (note: with stage 3 and 4 it
will always report -1 or -2 means default/not specified)
stage: 0:disabled, 1:call record begin,2:upload
begin, 3: upload success, 4: upload fail (note: stage 0 might not be reported)
type: upload method: 0: unknown, 1: local file, 2:
ftp, 3: http, 4: server
path: upload path/file (note: if stage is 1 then
type and path is not reported yet)
reason: failure reason (if stage is 4)
Note: this is sent only from the NS and Java engines. There
is no client side feedback about WebRTC call recording
This message is sent immediately after
startup (so from here you can also know that the SIP engine was started
successfully).
The what parameter can have the
following values:
“api” -api is ready to use
“sip” –sipstack was started
Important events which should be displayed
for the user.
The following TYPE are defined: EVENT,
WARNING, ERROR
This means that you might receive
messages like this:
WPNOTIFICATION,EVENT,EVENT,any
text NEOL \r\n
Should be displayed for the users in
some way.
Various custom messages. Ignore.
Detailed logs (may include SIP
signaling).
The following TYPE are defined: EVENT,
WARNING, ERROR
Voice activity (only for the NS or Java
engine. Not for WebRTC)
This is sent in around every 2000 milliseconds
(2 seconds) by default from java and NS engines (configurable with the
vadstat_ival parameter in milliseconds) if you set the “vadstat” parameter to 3
or it can be requested by API_VAD via the internal engine. Also make sure that
the “vad” parameter is set to at least “2”.
This notification can be used to detect
speaking/silence or to display a visual voice activity indicator.
Format:
VAD,local_vad: ON
local_avg: 0 local_max: 0 local_speaking: no remote_vad: ON remote_avg: 0
remote_max: 0 remote_speaking: no
Parameters:
local_vad: whether VAD is measured for
microphone: ON or OFF
local_avg: average signal level from
microphone
local_max: maximum signal level from
microphone
local_speaking: local user speak
detected: yes or no
remote_vad: whether VAD is measured
from peer to speaker out: ON or OFF
remote_avg: average signal level from
peer to speaker out
remote_max: maximum signal level from
peer to speaker out
remote_speaking: peer user speak
detected: yes or no
RTPSTAT,quality,sent,rec,issues,lost
Media quality reports sent by the NS
and Java engines (not by WebRTC) if you set the rtpstat
parameter to -1 or to a positive value.
Possible values for rtpstat:
o
-1: auto (will trigger RTPSTAT
events in every 6-7 seconds and more frequently at the beginning of the calls)
o
0: disabled (default)
o
Positive value: seconds to
generate RTPSTAT events.
RTPSTAT notification parameters:
o
quality: number between 0 (worst)
and 5 (best). The calculations considers many factors such as RTP issues, RTCP
reports, codec problems, packet loss, packet delay, jitter and processing
delay.
o
sent: RTP packets sent
o
rec: RTP packets received and
played
o
issues: number of issues (any
issues are counted, such as sequence number mismatch or packet drop)
o
lost: lost packets
More details here.
Format: messageheader, messagetext. The
followings are defined:
“CREDIT” messages are received with the user
balance status if the server is sending such messages.
“RATING” messages are received on call setup
with the current call cost (tariff) or maximum call duration if the server is
sending such messages.
“MWI” messages are received on new voicemail
notifications if you have enabled voicemail and there are pending new messages
“SERVERCONTACTS” contact found at local VoIP
server
“NEWUSER” new user request
“ANSWER” answer for previous request (usually
http requests)
How to get my own webphone?
1.
Try from your desktop or webserver by downloading the webphone package or try the online demo.
2.
If you like it, we can send your
own licensed copy within one workday on your payment.
Before to purchase, make sure that all the features which are critical to your
use-case is working correctly.
You can find the pricing and order from here. For
the payment we can accept PayPal, credit card or wire transfer.
3.
Once we receive the notification
about your payment, we might contact you for your company details required for
accounting/invoicing, the address of your server(s) and other customization
details then will send your licensed copy by email/download link within maximum
one work-day (usually it takes only around two hours in business hours).
In case if you deployed the demo/trial version
before, then you will just have to overwrite
your old copy to continue the usage with your licensed version, which will
remove the demo/trial limitations.
We offer support and maintenance upgrades to all our
customers. Guaranteed supports hours depend on the purchased license plan and
are included in the price.
Email to webphone@mizu-voip.com with
any issue you might have.
Please include the followings with your message:
·
exact issue description
·
screenshot if applicable
·
detailed
logs
·
optionally a description about
how we can reproduce the problem with valid sip test account(s)
If the included support period with your license is expired, it can be
increased by 2 years for around $600 (Note: This is completely optional. There
is no need for any support plan to operate your webphone). For gold partners we
also offer priority, phone and 24/7 emergency support.
Note:
·
We can’t guarantee that all the
listed features will work correctly in your environment (your SIP servers /
integrated with your software / hosted on your Web server). Please test the
demo/trial version before purchase to make sure that all the functionality
critical to your use-case works correctly.
·
Our support answer time is
usually up to one work-day for issues related to core functionality (such as
connect/register and voice calls). We are trying to resolve all such issues as
soon as possible. Issues affecting non-core features (such as call hold or
presence) might be handled only in the upcoming new releases.
·
Direct support is provided for
the common features (voice calls, chat, dtmf and others) and common OS/browsers
(Windows/Linux/Android/MAC OS, IE/Firefox/Chrome/Safari/Opera) and not for
extra features (such as presence, fax or webrtc conference) and exotic
OS/Browsers (such as FreeBSD, Konqueror). The webphone should work also with
other OS/browsers, but we are not testing every release against all exotic
platforms.
·
Direct support is not provided
for the issues described in the known limitations section. If you have some
special must-to-have requirement, we recommend to test with the demo
version before purchasing your license.
·
While video and screen-share
should work via WebRTC on all supported platforms, we recommend testing it
first in your environment before to purchase if this feature is important for
you. Some SIP servers and devices doesn’t handle the video features correctly
and this is very difficult to debug (We can’t offer support for extra video
features. It either works or not works in your environment depending on your
SIP server and SIP peers capabilities).
·
Mizutech doesn’t provide direct
server side support. Although the webphone is known to work well with all
common SIP servers (including Asterisk, FreeSWITCH and many others), your
servers have to be managed by you and we are not responsible for proper configuration
of your servers.
·
We are highly specialized for
VoIP development and not designers. Please don’t contact us with user interface
development or design related requests as we wish to focus only on
VoIP/SIP/WebRTC specific projects. The webphone already includes a few ready to
use skins for your convenience with their source code in your hand which you
can modify as you wish or create your own user interface from scratch if none
of them fulfills your needs. These tasks (both modifying the built-in skins and
creating new ones) are described in details in this documentation.
You will receive the followings:
·
the web phone software itself
(the webphone files –latest stable version- including the engines, javascript
API, html5/css skins and examples)
·
the ready-to-use/turn-key
softphone skin and click to call button
·
latest documentations and code
examples
·
invoice (on request or if you
haven’t received it before the payment)
·
support on your request according
to the license plan
Yes.
You can fully customize the webphone yourself by its
numerous configuration options. However if you have some specific requirement
which you can’t handle yourself, please contact us at webphone@mizu-voip.com. Contact us only with webphone/VoIP specific
requirements (not with general web development/design related requests as these
can be handled by any web developer and we are specialized for VoIP only).
No. The webphone can be
deployed by anybody. If you already have a website, then you should be able to
copy-paste and rewrite the example HTML codes. Some basic Java
Script knowledge is required only if
you plan to use the Java Script API (although there are copy-paste examples for
the API usage also).
What software/service do I need to be able to
use/deploy the webphone?
·
A webserver (local, rented, hosted) to host the webphone files
·
A SIP account
by one of the followings:
o Your existing IP-PBX
or softswitch OR
o SIP account(s) at
any VoIP service provider and/or
trunk/call-termination services OR
o Buy a VoIP server software or
hardware (Cisco, Mizu, Brekeke, others) OR
o A free or open
source VoIP server (Asterisk, FreePBX, OpenSIPS,
others) OR
o Rent a softswitch (SaaS)
·
Optional: Some server side
scripts if more customization/changes are required than possible with the
webphone API and parameters
·
Optionally if you need better
control on WebRTC: WebRTC capable SIP server or
WebRTC-SIP gateway (both options are freely available)
The webphone can be deployed both in cloud or
self-hosted / on-premise.
More details can be found here and in the following FAQ points.
In short:
Use any web server to host the webphone files. Just
copy the webphone folder to your webhost and you are ready to go.
For testing, you can also just launch it from local
file or from a localhost development server.
Some more details:
All the functionality of the web sip phone is
implemented on client side (JavaScript running in users browser) so there is no
any application specific requirements for the webserver. You can use any web
server software (IIS, nginx, Apache, NodeJS, Java, JSP, others) on any OS
(Linux, Windows, others).
The only purpose of the web server is to just host
the webphone files and serve it to browsers, the exact same way as a static
page or a simple jpg image. No any code will run on your web server.
You can also test the webphone by launching it from
localhost (launch any of it’s html files such
as the index.html, softphone.html or html’s from the samples subfolder).
The webphone can be also integrated with any server
side framework if you wish (.NET, PHP, java servlet, J2EE, NodeJS and others). Integration tasks are up to you, and it can be done multiple
ways such as dynamic webphone configuration per request, dynamic URL rewrite
(since the webphone accepts parameters also in URL’s), or add more server side
app logic via your custom HTTP API which can be called from webphone (for
example on call, on call disconnect or other events; the VoIP webphone has
callbacks for these to ease this kind of integrations). All these are optional
since you can implement any kind of app logic also on client side from
JavaScript if you need so.
We recommend deploying the
webphone to a secure site (https) otherwise the latest Chrome and Opera
doesn’t allow WebRTC. More details here.
If you can’t enable https on your webhost for some reason, then we can host
your webphone if you wish on a secure white-label domain for free.
Depending on the client
browser and the selected engine, the webphone might attempt to download some
platform specific binaries. (These are found in the “native” folder). Make sure
that your web server allows the download of these resource types by
allowing/adding the following mime types to your webserver configuration
if not already added/allowed:
·
extension: .bin MIME type:
application/octet-stream
·
extension: .mxml MIME type:
application/octet-stream (or application/xv+xml)
·
extension: .exe MIME type:
application/octet-stream (or application/x-msdownload)
·
extension: .dll MIME type:
application/x-msdownload (or application/x-msdownload)
·
extension: .jar MIME type:
application/java-archive
·
extension: .jnilib MIME type:
application/java-archive
·
extension: .so MIME type:
application/octet-stream
·
extension: .dylib MIME type:
application/octet-stream
·
extension: .pkg MIME type:
application/x-newton-compatible-pkg (or application/octet-stream)
·
extension: .swf MIME type:
application/x-shockwave-flash
Common mime types such as
.zip are not mentioned above since these are usually enabled by default on any
web server.
You can easily test if works
by trying to download these files typing their exact URI in the browser such
as: http://yourwebsite.com/webphone/native/webphone.jar
(The browser should begin to download the file, otherwise the jar mime type is
still not allowed on your webserver or you entered an incorrect path or
webserver doesn’t serve files from the specified folder)
You can also test the
webphone without a web server by running from local file system.
How to deploy the webphone on my web server?
In short:
Extract (unzip) the webphone.zip and copy the
resulting webphone folder to under your server web path and you are ready to
use the webphone.
Details:
The webphone doesn’t have any web server related
runtime, thus you can host the webphone as a static website or exactly as you
do hosting simple png files.
Just copy the webphone folder to your webserver path
and access any html (the included index.html, softphone.html, click2call.html
or html’s from the samples folder or write your own custom html. Of course, you can also use a runtime such as
PHP or .NET and integrate
the webphone library as you wish).
For example if you copy the webphone to your web
directory root folder, then you will be able to test it by typing the following
in your browser URL:
https://yourwebdomain.com/webphone/index.html
Note:
o
You can also test
the webphone by just launching any html from your local file system (just copy the webphone folder to your desktop or any other location in
this case and double click any html to open)
o
Instead of
yourwebdomain.com you might need to enter your web server IP:port if you don’t
have a domain name, but we recommend acquiring a domain name and setting
up a certificate for HTTPS.
o
Instead of
https:// you might have to type http:// if your server doesn’t have TLS
certificate, but we recommend to upgrade to HTTPS.
More details:
·
Step by step instructions can be
found here
·
In case if you wish to upgrade
from an old version, see the details here
·
If you wish to implement some
close integration with your web application or web backend, see the details here. (Otherwise the webphone is a client side library
and it can be fully controlled by its settings
and/or via its JavaScript
API)
We highly recommend hosting the webphone files on
HTTPS (secure http) to take full advantage of the webphone capabilities.
Otherwise you might run it from local file for
testing (modern browsers such as Chrome imposes more restrictions if you run it
from unsecure HTTP).
Details:
The webphone can work also from unsecure HTTP
hosting.
However to take full advantage of the webphone
capabilities, it is strongly recommended to use HTTPS (secure HTTP web hosting
using a domain with a valid TLS certificate).
The most important reason is that some browsers (for
example Chrome) will not allow media access permissions for WebRTC from unsecured pages.
In this case the webphone can failback to other
engines which doesn’t required HTTPS (such as the NS engine), however it might
be possible that the optimal engine in your environment is WebRTC (or in the
worst case it might be the single option).
More details about web hosting can be found here and here.
For development, in case if you don’t have a HTTPS
hosting yet, you can work in the following ways:
·
Use some browser which doesn’t
require HTTPS for WebRTC. For example old Firefox versions (until v.67.0)
should run just fine from unsecured HTTP
·
Run from local file (even Chrome
should allow WebRTC media permission if you launch the webphone html from a local
file, instead of from a web server)
Then only drawback for the above possibilities is
that the webphone might have to ask for media permission at each startup as the
browsers will save your preference only on HTTPS.
Note: Even if the webphone is running
from unsecure HTTP, if the only possible engine is WebRTC in your environment
and you are running it in a browser which requires HTTPS for media access (such
as Chrome), then the webphone might be able to do automatic HTTP > HTTPS
conversion using a proxy service. In this case it might simply reload itself on
HTTPS in some circumstances.
Is it working with my
VoIP server?
Yes. The webphone works with
any SIP capable voip server/softswitch/PBX
including Asterisk, FreeSWITCH, Huawei, Cisco, Mizu, 3CX, Voipswitch, Kamailio,
Brekeke and many others. You don’t necessarily need to have your own SIP server
to use the webphone as you can use any SIP account(s) from any VoIP provider.
The web phone is using the
SIP protocol standard to communicate with VoIP servers and sofswitches. Since
most of the VoIP servers are based on the SIP protocol today the webphone
should work without any issue. Some modules (WebRTC and Flash) might require
specific support by your server or a gateway to do the translation to SIP,
however these modules are optional, gateway software are available for free and
also mizutech includes its own free tier service (usable by default with the
webphone).
If your are using a private
VoIP server (local LAN / private IP address) and you wish to use the webphone
(also) from mobile devices, then you should also configure WebRTC since mobile
browsers don’t have plugin capabilities, thus the Java, NS and Flash engines can’t
work and for private IP the built-in WebRTC-SIP converter can’t work. For more
details see here, here and here.
Usually you can setup the
webphone the exact same way as you do with a regular IP phone or softphone like
X-Lite. Read more details here.
In case if you are using a
multi-tenant server with different logical domains for your tenants, then you
might have to set both the serveraddress parameter (to your server logical
domain name) and the proxyaddress parameter (to your server resolvable domain
name or IP address).
If you have any incompatibility problem, please contact webphone@mizu-voip.com with a problem description and a detailed log
(loglevel set to 5). For more tests please send us your VoIP server address
with 3 test accounts.
Is it working with
third-party VoIP servers and VoIP providers?
Yes, the answer is similar
here as for the previous FAQ point above.
The webphone is compatible with all regular SIP
providers with its default settings. Usually you just have to set the serveraddress/username/password parameters to go. If the provider SIP
service is not using (listening on) the standard 5060/5061 ports, then make
sure to append the port number for the serveraddress parameter. For example serveraddress: 'sip.myprovider.com:12345'. The
serveraddress is usually set in the webphone_config.js while the
username/password is usually set at runtime from user input.
Sometime the providers also specify an outbound proxy
address to be used which can be set with the proxyaddress
parameter.
Sometime the providers requires a specific network
transport protocol (instead of the standard default UDP), which can be set by
the transport parameter.
Some very rare SIP servers might require some special
settings (such as a specific realm) which you can easily set by changing the
webphone parameters accordingly. These are extremely rare and in these
situations and requirements should be clearly listed on the provider website.
I wish to use the webphone but I don't have a SIP
server or service
If you don’t have your own VoIP server, you can use
any third-party solution or service:
o SIP account(s) at
any VoIP service
provider and/or trunk/call-termination services OR
o Buy a VoIP server software or
hardware (Cisco, Mizu, Brekeke, others) OR
o A free or open
source VoIP server (Asterisk, FreePBX, OpenSIPS,
others) OR
o Rent a softswitch (SaaS)
There are many SIP servers over the
internet where you can create free SIP accounts.
We also provide such a service here: voip service
(you can create multiple sip accounts for free and make calls between them)
The webphone is a self-hosted client-side software
completely running in the client browser and with no any “cloud” dependencies.
It has the following server side dependencies (all of
this controllable by you so you can run the web VoIP bowser plugin on your own
also on a private local LAN without the need of any third-party service):
·
A webserver where the webphone files are hosted (we send all the
required files so it can be hosted on any web-server including servers behind
NAT)
Note: for WebRTC to work (if you need this engine) the
webphone have to be hosted on https. (This means that if you run the webphone
from local LAN then at least browser CA verification must be enabled to the
internet or you have to setup a local valid certificate)
·
Optional: connection to custom
web application (This is if you have some server side business logic such as
.NET or .PHP application or if you are making API calls or using any resources
from a custom web application. All these is up to you and it has nothing to do
with the webphone itself)
·
A SIP compatible VoIP server
where the webphone will connect: any SIP server
which can be otherwise reached by any sip softphone,
including local LAN PBX services
·
Optional: helper connectivity
services such as WebRTC gateway and STUN/TURN server. All of these can be
also disabled/changed and/or the webphone works also if these are not
reachable.
What are the main
benefits?
Using the Mizu webphone you can have a
single solution for all platforms with the same user interface and API. No
individual apps have to be maintained anymore for different platforms such as a
Windows Installer, a Web application, Google Play app for Android and other
binaries.
·
Unlike traditional softphones,
the webphone can be embedded in webpages while providing the same functionality
as a traditional native solution
·
Single unified JavaScript API and
custom web user interface
·
Easy and flexible customization
for all kind of use-case (by the numerous parameters and optionally by using
the API)
·
Compatible with all browsers (IE, Firefox, Safari, Opera, Chrome, Edge, etc) and all
OS (Windows, Linux, MAC, Android, etc)
·
Compatible with your existing
IP-PBX, VoIP server or any SIP service
·
Works also behind corporate
firewalls (auto tunnel over TCP/HTTP
80 if needed)
·
Combines modern browser
technologies (WebRTC, opus) with VoIP industry standards (G.729,
conference, transfer, chat, voice recording, etc)
·
Use well known VoIP codec’s with
WebRTC (for example G.729 with WebRTC)
·
Easy to use and easy to deploy
(copy-paste HTML code)
·
Easy integration with your
existing infrastructure since it is using the open SIP/RTP standards
·
Easy integration with your
existing website design
·
Proprietary SIP/RTP stack
guarantees our strong long term and continuous support
·
Support for all the common VoIP
features
·
Unlike NPAPI based solutions, the
webphone works in all browsers (NPAPI is not supported anymore in modern
browsers)
·
Unlike pure WebRTC solutions, the
webphone works in all browsers (webrtc doesn’t work in IE and old browsers only
with extra plugin downloads)
·
Unlike pure WebRTC solutions, the
webphone is optimized for SIP with fine-tuned settings (TURN, STUN and others)
The webphone can be used to create
standalone VoIP solutions or integrated with any website or web application.
Here are a few examples about how the
webphone could be used:
·
As a browser phone
·
JavaScript SIP library
·
Integration with other web or
desktop based software to add VoIP capabilities
·
A convenient dialer that can be
offered for VoIP endusers since it runs directly from your website
·
Callcenter VoIP client for
agents/operators (easy integration with your existing software)
·
Ready to use web VoIP client
without the need of any further development
·
SIP API for your favorite JS
framework such as React, jQuery, Angular, Vue, Ember, Backbone or any others or
just plain/vanilla JS
·
Embedded in VoIP devices such as
PBX or gateways
·
Click to call functionality on
any webpage
·
VoIP conferencing in online games
·
Voice assistance over IP
·
Hotels
·
Buy/sell portals
·
WebRTC SIP client, WebRTC SIP
library or WebRTC softphone
·
Salesforce help button
·
Social networking websites ,
facebook phone
·
Integrate SIP client with jQuery,
Drupal, joomla, WordPress, angularjs, phpBB, vBulletin and others as a web
plugin, module or API
·
As an efficient and portable
communication tool between company employees
·
VoIP service providers can deploy
the webphone on their web pages allowing customers to initiate SIP calls
without the need of any other equipment directly from their web browsers
·
Customer support calls (VoIP
enabled support pages where people can call your support people from your
website)
·
VoIP enabled blogs and forums
where members can call each other
·
VoIP enabled sales when customers
can call agents (In-bound sales calls from web)
·
Java Script phone or WebRTC SIP
client
·
Web dialer for Asterisk, FreePBX
or FusionPBX
·
Turn all phone numbers into
clickable links on your website
·
Integrate it with any Java
applications (add the webphone.jar as a lib to your project)
·
HTTP Call Me buttons
·
Remote meetings
·
HTML5 VoIP
·
Web VoIP phone for callcenter
agents integrated with your callcenter frontend
·
Asterisk integration (or with any
other IP-PBX)
·
Convert any SIP link (sip: URI)
on web to clickable (click to call) links and replace native/softphone
solutions with a pure web solution
The rest is up to your imagination.
Folders and file
structure
·
js folder: this is for javascript
o
js/lib folder: the webphone core
library files. Also there is a string resource file (stringres.js) which
contains all the text displayed to the user.
o
js/softphone folder: GUI files.
For every jQuery mobile "page" there is an equivalent JavaScript
file, which handles the behavior of the page.
·
css folder: - style sheets used
in skin (GUI). The style of the skin can be changed by editing
"mainlayout.css" file
o
css/themes folder: jQuery mobile
specific cascading style sheets and images used by the softphone and click to
call skin templates
·
images folder: images used by
the includes skins (GUI)
·
oldieskin folder: old webphone
skin, which is used only in very old browsers, ex: IE 6
·
sound folder: contains sound
files (for example ringtone and keypad dtmf sounds)
·
native folder: platform specific
native binaries (the webphone might load whichever needed if any, depending on
the engine used)
·
the root folder contains the
following files:
o favicon.ico: web page favicon (irrelevant)
o index.html: a start page for the examples
o oldapi_support.js: backward compatibility with old
skin. Useful for cases where the webphone was integrated using the
"old" JavaScript VoIP API.
o softphone.html: GUI html file for a full featured
web phone (use it as-is or further customize this after your needs)
o click2call.html: GUI html file for a click to call
implementation (use it as-is or further customize
this after your needs)
o softphone_launch.html: just a placeholder for the
“softphone.html” so you can use the softphone skin more comfortably (centered)
when launched directly
o webphone_api.js: the public Javascript API of the web
phone
o webphone_config.js: webphone configuration
o package.json: might be useful if you are using
package managers
o firebase-messaging-sw.js: used only if push
notifications are set
o your_custom_sip_client.html: just an empty html to
remind you that you can create your own GUI
·
The “samples” folder contains
other usage examples/skins/samples:
o techdemo_example.html: a simple demo html the
showcase the webphone functionalities
o minimal_example.html: shortest implementation to make
a call
o basic_example.html: simple usage example of softphone
SDK
o api_example.html: a more detailed example for the SIP
API usage
o incoming_example.html: simple example to handle
incoming call
o click2call_example.html: a minimal click to call
phone button implementation
o linkify_example.html: will convert phone numbers on a
webpage to clickable SIP URI’s for click to call
o mobile_example.html: just a show case to remind you
that the webphone also works on smartphones
o multipage_example.html: demonstrates using the same
webphone instances across multiple pages
It is possible to delete the unneeded
files (for example you can delete the softphone and the oldieskin folders if
you are using the webphone as an API), however you should not bother too much
about these and just leave all the files on your server. This can’t have any
security implications; the webphone will use only the required files for your
use-case. See the webphone_shrink document for more details.
Why the webphone
package size is so big?
Webphone package size including all
engines and documentation: ~34MB.
Endusers browsers download size first
time: ~1MB
Endusers browsers subsequent usage: ~0
– 300 KB
The downloadable webphone package
(webphone.zip or yourbrand.zip) is around 26 MB because it contains all the
webphone related files, including samples and documentation. It will take
around 34 MB space on your web server when unpacked (if you don’t remove any
unnecessary files), but only a tiny fraction of this have to be downloaded by
browsers.
The webphone package includes also
native binaries per platform which might be used in some circumstances (NS
engine plugin one-click installer), but in this case only the user device
specific binaries are to be downloaded (for example on 64 bit linux, only the
webphone_ns_lin64.zip might be downloaded).
In case if the webphone uses the WebRTC
engine, then there is no any native binary download required. The WebRTC stack
will be provided by the browsers in this case and the webphone itself will be
responsible mainly for the JS SIP signaling using the WebSocket Protocol as a
Transport for SIP (RFC 7118).
Your customers browser will have to
download only a few small files to launch the webphone at first time (usually
js/css/html between 100 KB – 2 MB in total, depending on the engine and skin to
be used). In some circumstances there might be an additional 1-7 MB download
(depending on the OS and if using a browser plugin/engine).
We consider this as negligible, since
if the enduser network connection is not fast enough to download the required
webphone library files very quickly, then most probably it will also have
degraded VoIP experience.
Of course, the whole webphone library
can be also loaded asynchronously, unnoticeable for the endusers.
All the webphone files can be cached by
the browsers minimizing the download size required at subsequent launch.
Downloading the webphone SIP library by
the browsers takes around 2 seconds at first time using a typical internet
connection and below 1 second on subsequent launches.
Additional plugin
download?
An additional download by the users
might be required only in some specific circumstances. For example if the
browser can’t use WebRTC or the Java engine, then the webphone might offer the
NS engine plugin download which is an one-click installer.
These downloads are NOT from some remote/third-party locations but from
your own webphone package (the webphone files what you copied to your web
server).
The webphone includes multiple VoIP
engines and the “best” one is automatically selected based on circumstances
(settings/server capabilities/browser capabilities/etc).
The most important engines are the
followings:
·
WebRTC: no any download is
required; will act as a standard WebRTC SIP client library
·
NS engine: native VoIP engine
browser plugin one-click installer download is always required
·
Java: no any download is required
as this is used only in browsers with java applet support if JRE is already
found/installed
·
Flash: no any download is
required and might be used in some rare occasions with for very old/outdated
browsers if Flash is already found/installed
If you must avoid any additional
download, then make sure that WebRTC can be used in your environment. Otherwise the NS engine can also offer a top
quality VoIP experience at the cost of two additional click required by the
enduser (one click to download and one click to install).
Does the webphone depends on Mizutech services?
No, the webphone can be used on their own as a fully
self-hosted solution, connecting to your VoIP server directly by SIP (Java, NS
and App engines), via WebRTC or via Flash so you will have a solution fully
owned/controlled/hosted by you without any dependency on our services,
third-party services or cloud services.
With other words: if all our
servers will be switched off tomorrow, you will be still able to continue using
our web softphone. You can also use the network in an private network with even
without internet access (hosted on your internal Web server and connecting to
your internal SIP server).
However, please note that by
default the webphone with its default settings might use some of the services
provided by Mizutech or third party cloud services for free, to ease the usage,
and to make it a turn-key solution with optimal NAT handling, without any extra
settings to be required from your side. All of these are for your convenience,
especially to help beginners in the VoIP fields to handle some corner cases.
Most of these are used only under special circumstances and none of these are
critical for functionality; all of them can be turned off or changed and the
webphone can work also if these are not set or services are not available.
The following services might
be used:
·
Mizutech
license service: demo, trial or free versions are verified against the license
service to prevent unauthorized usage. This can be turned off by purchasing a
license and your final build will not have any DRM or “call to home”
functionality and will continue to work even if the entire mizutech network is
down.
Note: this is not used
at all (completely removed) in paid/licensed versions
·
WebRTC
to SIP gateway: if your server doesn’t have WebRTC capabilities but you enable
the WebRTC engine in the webphone (using it as a JavaScript WebRTC client) then
it might use the Mizu WebRTC to SIP gateway service. Other possibilities are listed
here.
Note: this might be used
only if you are using the webphone WebRTC engine but your server doesn’t have
support for WebRTC nor you have a WebRTC-SIP gateway.
·
Flash
to SIP gateway: rarely used (only when there is no better engine then Flash
such as ancient browsers). Just turn it off (by setting the
“enginepriority_flash” parameter to 0) or install your own RTMP server and specify its
address.
Note: usually Flash is
not used at all as there are better built-in engines which are supported by
more than 99.9% of the browsers.
·
Push
notifications: Mizutech might provide push service (free tier) in case if you
need push notifications but your SIP server don’t have support for it. More
details can be read here.
Note: push notifications
are disabled by default (you can enable it with the “backgroundservice”
parameter) and there is no need to use the mizu service (you can use your SIP
server push service or via any other third party gateway if needed)
·
STUN
server: in some circumstances the webphone might use the Mizutech STUN service.
You can change this by changing the “stunserveraddress” to your server of
choice (there are a lot of free public STUN services or you can
run your own: stable open source software exists for this and
it requires minimal processing power and network bandwidth as STUN is basically
just a simple ping-pong protocol sending only a few short UDP packets and it is
not a critical service).
Note: you can use the
webphone without any STUN service if your SIP server has basic NAT handling
capabilities and it is capable to route the RTP if/when needed.
·
TURN
server: in some circumstances the webphone might use the Mizutech TURN service
which can help firewall/NAT traversal in some circumstances (rarely required).
You can specify your own turn server by
setting the “turnserveraddress” parameter (if TURN
is required at all).
Note: you can use the
webphone without any TURN service if your SIP server has basic NAT handling
capabilities and it is capable to route the RTP if/when needed.
·
Alternative
IP lookup: in some circumstances the webphone might try to auto-detect its
public IP address or the server IP (xhosttoip) by a service such as
mnt.mizu-voip.com, checkip.dyndns.org,
wtfismyip.com, icanhazip.com, my-ip.heroku.com, checkip.dyndns.org or
ipinfo.io. This is just an extra way to check if the SIP server is public or to
detect the correct external IP which might be useful in some rare circumstances
(SIP servers with poor NAT support when STUN is unavailable or bogus so at the
first request the webphone might be already able to present its public
address). The failure of this service does not affect the SIP stack
functionality.
Note: you can disable
this by setting the altexternpublicip parameter to 0.
·
Network
connectivity: if the SIP stack can’t connect to your server or network
connectivity have been lost, the webphone might ping some well know addresses
such as google.com to see if there is any network connection at all. When using
WebRTC, the webphone might check the internet connectivity against some public
websocket servers. (it can be reconfigured with the wstestservers
parameter; multiple servers can be separated by comma).
This “ping” is then
used only to clarify the connectivity problem reports and print appropriate
logs to the browser console to ease the troubleshooting (to separate “No
network” from other possible issues such as “SIP server is offline”).
This might be used only if your SIP server is public
(not checked if on the same LAN) and the websocket connectivity test is
performed only if the loglevel is higher than 2.
Note: You
can disable it by setting the networkchecks parameter to 0.
·
JSONP:
if you set some external API to be used by the softphone skin (such as for user
balance or call rating requests) and your server can’t be contacted directly
with AJAX requests due to CORS, then the API calls might be relayed by a JSONP
or websocket proxy. To disable this, make sure that the domain where you are
hosting the web phone plugin can access your domain where your API is hosted.
Note: this might be used
only in very specific circumstances which can be avoided (used only when you
integrate the webphone with your own API, but your own API isn’t configured
correctly so it can’t be accessed by the webphone via normal AJAX GET/POST
requests)
·
HTTPS
proxy: with the WebRTC engine if you are using the webphone from browsers which
require secure page for WebRTC (such as Chrome) and your website is not secured
(not https) then the webphone might reload itself via a HTTPS proxy. To disable
this, host your webphone on HTTPS if you wish to use WebRTC from Chrome. API
requests can be also routed via this service (such as credit or rating
requests) if you are running the webphone on HTTPS but defined your SIP server
API as HTTP (otherwise browser blocks requests from secure page to insecure
resources)
Note: this might be used
only if your website is not on HTTPS (no SSL certificate) and you try to use
the webphone WebRTC from a browser which disallows unsecure WebRTC.
It can be disabled by setting the “usemizutlsproxy” parameter to 0 (0=no,
1=auto, 2=yes).
·
Tunneling/encryption/obfuscation:
In some conditions the webphone might use the Mizu tunneling service to bypass VoIP
blockage and firewalls. This is usually required only in countries where VoIP
is blocked (such as UAE or China) or behind heavy firewalls with DPI and you can turn it
off by setting the “usetunneling” parameter to 0.
For the usual
encryption just setup HTTPS for your website hosting the webphone and use the
webphone built-in encryption capabilities such as SIPS/TLS/SRTP or WebRTC/DTLS/SRTP as these doesn’t
require any external service to be used (except support by your softswitch).
Note: this is a special
feature which needs to be turned on by mizutech support, otherwise it is not
enabled by default.
·
Geolocation:
the webphone doesn’t try to ask for Location permissions, but at first start it
might try to detect its location by a lookup via a random free service such as ip-api.com,
ipinfo.io or www.geoplugin.net from a low priority background thread. This is
just for your convenience so on your server side you can easily store the
client location as this information is just sent by X-Country SIP header. By
default this is turned off on private networks.
Note: this feature has
nothing to do with the SIP core functionality and it can be disabled by setting
the geolocation parameter to 0.
·
Connections
to nsX.webvoipphone.com.
The
nsX.webvoipphone.com domain points to localhost (127.0.0.1) and it is used to
allow the webphone (running in a local browser page) to securely communicate
with the locally running NS engine (some browsers allow raw connections to
127.0.0.1 but others require secure connections).
By default the
webphone uses the ns4.webvoipphone.com and maintains a Let’s Encrypt
certificate for it. You can rewrite the domain name if you wish with the
nsdomain webphone parameter (it can be any domain name owned by you with its
DNS A record set to 127.0.0.1). If you change the domain then you must also
change the TLS certificate (the .pem files in the NS app folder) and set the
tlscert_autoupgrade parameter to 0 in the NS engine .ini file(s).
Note: you can rewrite
the domain if you wish with the nsdomain parameter as described above.
·
NS
installer: The NS engine might use a JVM which is not included in the installer
to keep it as small as possible. If the enduser already has a Java installed on
their device/PC then the NS engine will use that Java virtual machine.
Otherwise the installer will auto download a tiny JVM of around 9 MB or the
system default JVM (a minimal JRE/JDK).
Note: this is used only
by the NS engine installer and if you wish, we can include the JVM into the
installer instead (mbuildoption_jrebundle mbuild option)
·
NS
engine TLS cert: The webphone communicates with the NS engine via WSS (secure
websocket) on localhost using the ns4.webvoipphone.com domain with an
automatically maintained Let’s Encrypt TLS certificate. The certificate is
refreshed time to time from
C:\Mizutech\WEB\webvoipphone.com\publicfiles\localhostcert2
Note: this is used only
by the NS engine in some browsers which doesn’t allow simple HTTP or TLS
localhost connections
·
Auto
upgrade: the native components can auto-upgrade itself from Mizutech download
service. This is enforced only from known old versions to know good versions.
You can disable this by setting the “autoupgrade” to 6. (You can also set the
“autoupgrade” to 5 which will also disable the upgrade of the SSL certificates
if any)
Note: this might be used
only if you use the webphone NS engine and can be turned off as described
above.
·
Send
log to support: the softphone skin (softphone.html) has a “Send log to support”
option on its menu which is a convenient way for endusers to report any issue.
By default this uploads the log file to mizutech support, but you just need to
rewrite the logform_action URL as described in the Logs FAQ to change to yours
Note: this is present
only in the softphone skin and it can be removed or rewritten to upload logs to
your server
If you are using the
webphone on a local LAN then these services are not required and are turned off
automatically (so the webphone will not try to use these if your VoIP and/or
Web server are located on local LAN / private IP).
If you need to white-list
(or block for some reason) our servers, here is the address list associated
with the above services:
mnt.mizu-voip.com, rtc.mizu-voip.com, usrtc.webvoipphone.com,
usrtc3.webvoipphone.com, usrtcx.webvoipphone.com, www.webvoipphone.com, www.mizu-voip.com, fcm.webvoipphone.com;
140.99.162.117, 107.174.212.78,
204.12.197.100, 204.12.197.98, 148.251.28.176 / 28
(148.251.28.177 - 148.251.28.190)
(In case if you can set domain name based firewall rules,
that is better, otherwise you can just use the IP addresses -all of these are
static fix IP’s and it is not expected to be changed anytime soon)
Note: blocking the license service for demo or trial
webphones will make them unusable after some time (But licensed/paid versions
doesn’t depend on any central license service at all).
How to configure the webphone
The most important settings are listed here.
The webphone can be configured by its parameters or dynamically
via the setparameter API. There are
many ways to set its parameters. You can statically hardcode them in the
webphone_config.js file, pass as URL parameters or load from a server API by setting the scurl_setparameters to point to your API (HTTP AJAX URL). For more
details about how you can pass the parameters for the webphone, see the beginning
of the parameters chapter.
Make sure to configure it correctly for your SIP server (this usually means only setting the serveraddress parameter correctly).
You can make a quick test with your SIP server using
one of the included
html (such as the softphone.html or
techdemo.html).
Once the webphone has the correct configuration, you
can go ahead using one of the included solution (such as the softphone or click to call;
you can also modify these as you wish) or build your
own custom solution which usually involves creating your custom
HTML/CSS and interacting with the webphone with JavaScript using its API.
The webphone includes multiple VoIP engines (such as
NS engine, WebRTC, Java, etc), each with their own advantages and
disadvantages.
Having multiple engines allows broad compatibility
with different browsers/servers and better resource utilizations. For example
if you are operating a call-center
then you might force the NS engine to avoid WebRTC utilization or if your
solution is deployed for wide range of customers connecting over the internet
then you might prefer WebRTC for a better user experience (no need to
download/install anything by the endusers).
By default the webphone will select the most optimal
engine for your environment. This process can be changed by the enginepriority parameter.
More detail can be found here and here.
Although WebRTC is a very important module where we
invest lots of effort to provide the best WebRTC-SIP experience, it is just one
of the engines built into the webphone. The webphone works also
without this engine if not available in your environment. Otherwise the
webphone will automatically detect WebRTC and will use it whenever available
and no better engine is available (such as the native NS engine or a manually
prioritized engine).
By default you don’t need to make any configuration
changes for the webphone to work for you. If possible (supported by the
OS/browser/server/gateway/peer) the WebPhone will use WebRTC. Otherwise it will
select the NS, Java, Flash or App engine and the enduser should not notice any
difference.
When the webphone selects the WebRTC engine, then it
will work as a standard JavaScript WebRTC SIP library and it can’t connect
directly to a server side SIP stack (if your SIP server doesn’t have built-in
WebRTC support), but a conversion of the WebRTC protocol (coming from the
browser) to SIP (which is understood by your VoIP server or IP-PBX) will be
required.
This conversion is done on the client side (the
webphone is sending SIP packets in Websocket which just have to be converted to
SIP UDP and it will emit a media stream compatible with SIP servers) and on the
server side (the server, proxy or gateway needs to understand WebRTC, ICE and
decrypt DTLS/SRTP into raw RTP packets).
Most of the time all these can be handled for you
automatically, without any further configuration required. However if you need
more control, you have several options to deal with WebRTC:
1.
Don’t use WebRTC at all.
Most JavaScript SIP clients implements
only the WebRTC protocol, but the webphone includes also other engines,
which can be used most of the time. There are only a few circumstances when the
only available engine would be WebRTC. (Although WebRTC is convenient for
enduser since it doesn’t need any browser plugin in browsers where it is
supported). To deprioritize/disable WebRTC, set the enginepriority_webrtc setting to 1 (or to 0; or set the enginepriority_ns
to 4; or both).
On the next start the
webphone should offer the NS engine download. If somehow this is not happening,
then you might install it manually on your test PC (because the WebPhone might
try to use the previously working engine by default). On Windows just launch
the WebPhoneService_Install.exe from the webphone\native folder. More details here.
2. Check if your VoIP server already has WebRTC support.
Most modern VoIP server already implements WebRTC (including mizu VoIP server,
Asterisk
and others) or you might just need to add/enable a module on your server for
this, so chances are high that your VoIP server can handle WebRTC natively.
Just set the webrtcserveraddress setting to point to your server websocket address in
this case. More details here.
3. Use the free Mizutech WebRTC to SIP
service tier. This is enabled by default and it might be suitable for your
needs if you don’t have too much traffic over WebRTC (the webphone will
automatically start to boost the priority for other engines when you are over
the free quote)
4. Use the mizutech WebRTC to SIP gateway software. We are providing this
software for free (the standard license) for our advanced webphone customers.
(You just have to setup this near your SIP server or web can install and
configure everything for you if you already purchased a webphone license and
sent us a remote access to the server where you wish to host this. It can be hosted
also on a virtual server.)
5. Use any third party WebRTC to SIP
gateway: There are few free software, which are capable to do this task for
you, including Janus and Dubango. (However if you don’t have any of these installed yet,
then we recommend our own gateway mentioned above as it is proven to be more
reliable than the open-source alternatives and we can also provide full support
for it)
6.
Use the Mizutech
WebRTC to SIP paid service. We can provide dedicated WebRTC to SIP conversion
services for a monthly fee if required.
The webphone can be used as a JavaScript WebRTC SIP
client library or as a WebRTC softphone by increasing the enginepriority_webrtc
to 3 or 4 (in this case it will use the other engines only when WebRTC is not
supported by the browser).
Important: Modern browsers require secure connection for
both your website (HTTPS) and websocket (WSS) to allow WebRTC (media permissions).
This means that if your page is not on HTTPS, then
you must use some old browser such as Firefox v.67.0. to test the webphone
WebRTC capabilities. Alternatively, you might test the webphone by just
launching from local file system which allows WebRTC in most browsers.
The following are the conditions for the
webphone to be able to use WebRTC:
·
You must run the webphone from a
WebRTC capable browser such as Chrome, Firefox, Edge, new Safari or Opera (in
old Safari trough there is no built-in WebRTC support, the webphone can ask the
user to download a plugin, thus turning old Safari browsers WebRTC aware)
·
The webphone must be hosted on
secure HTTP (HTTPS) with valid SSL certificate installed for your Web server
·
Your SIP server must have a
public IPv4 address, reachable from the public internet (so the webphone can
use our free WebRTC-SIP service) OR your SIP server must have built-in
WebRTC capabilities and you need to configure it by the “webrtcserveraddress”
webphone parameter OR you must run a WebRTC gateway on your LAN (we can
also provide a WebRTC-SIP gateway for free with the webphone Advanced or Gold
license or you can use open source solutions such as doubango or Janus)
How to configure
WebRTC with my WebRTC server or gateway?
In short:
Just set the webrtcserveraddress parameter to point to your websocket listener URL.
Details:
The webphone can be also used as a JavaScript WebRTC
SIP client library (with a possible failback to other SIP engines when WebRTC
is not available).
By default the webphone can also work without WebRTC
support (using native SIP/RTP by the NS or Java engine) or it can use our
WebRTC-SIP gateways (if WebRTC is preferred/needed in your environment and you
haven’t configured it yet with your WebRTC server settings). These will work
with the default settings without the need to change the webrtcserveraddress or
any other related parameters.
If for some reason this default behavior isn’t
suitable for you and you wish to setup your own WebRTC service to be used, then
you have two possibilities:
·
Configure WebRTC capabilities for
your server:
If your
softswitch/PBX has WebRTC support, follow its documentation to configure WebRTC
properly. For Asterisk you can find a guide here
(similar configuration can be used also for FreePBX, Elastix and other Asterisk
based solutions)
·
Or use a separate WebRTC-SIP
gateway:
If your
softswitch/PBX doesn’t have any WebRTC support, then you can setup a WebRTC-SIP
gateway near your softswitch/PBX such as Janus, MRTC or Dubango.
Of course, if your VoIP server has built-in WebRTC
support, then you should also configure the webphone accordingly.
Once your WebRTC service is running, you need to set
the following configurations for the webphone:
·
webrtcserveraddress (mandatory)
·
stunserveraddress (optional but highly recommended when using the
webphone over the public internet)
·
TURN
related settings (optional but
recommended when using the webphone over the public internet)
(or you can use the ice
parameter to set both the STUN and TURN parameters)
For STUN and TURN you can use any TURN server such as
coturn. (if your WebRTC server doesn’t have this built-in.
Our MRTC gateway has built-in STUN and TURN, but most third party WebRTC
servers doesn’t have this built-in and you need to run a separate TURN server).
Example configuration:
(You can set these in the
webphone_config.js file)
serveraddress: 'sip.yourdomain.com',
//Your SIP server address or domain name (append the port if not 5060.
For example: ‘11.22.33.44:5678’)
webrtcserveraddress:
'wss://rtc.yourdomain.com/anypath', //This is your websocket URL
socket address (WS for unsecure, WSS for secure. Append also the port if not on
the default 80/443. For example: 'ws://11.22.33.44:5555/anypath’. Note: your
SIP server and WebRTC websocket listener might use the same IP or domain, but
usually different ports)
stunserveraddress:
'22.33.45.55:3478’, //Your STUN server address (Optional)
turnserveraddress:
'22.33.45.55:3480', //TURN server address (Optional. Note: TURN and
STUN might use the same port.
turnparameters:
'transport=tcp', //TURN parameter (set this only if you wish to
use TURN over TCP only)
turnusername: 'turnuser', //TURN
username if required by your TURN server
turnpassword: '***', //TURN
password if required by your TURN server
enginepriority_webrtc: 3, //Increase
the priority for the WebRTC engine a bit
loglevel: 5 //Debug
trace level
With these settings the webphone will use your WebRTC
service and you can begin to initiate/receive calls over WebRTC. Check your
WebRTC server logs and the browser console log if you run into any issue. If
you used the NS or Java engine before with the softphone skin, then you might
need to go to the settings and set the VoIP Engine to WebRTC or clear your
browser cache (This might be required, because the webphone might remember and
prefer the previously used engine).
Note:
·
Modern browsers require secure WebSocket
connections (WSS), otherwise it will not allow WebRTC, so for production we
highly recommend to set a proper SSL certificate for your websocket listener.
·
You can test your server
websocket connectivity here (check if can connect,
you might not receive any answer for the requests sent if your server ignores
non-SIP requests)
·
For tests without SSL, you can
use old Firefox (v.67) browser as this allows WebRTC calls also on unsecure
websocket (WS) or launch the webphone from localhost/local file.
·
Your WebRTC server side software
must be able to understand the websocket protocol for SIP as described in RFC
7118.
First of all it is important to mention that the
browser web phone works just fine without Flash and Flash is already a
deprecated technology.
Chances are high that you don’t need Flash at all
even if available. In the rare circumstances when the only usable engine would
be Flash only (some very outdated or special browsers), the webphone can
automatically use the Mizutech Flash to SIP free service. In case if somehow
you wish to drive all your traffic over Flash, then you might install a Red5
server (open source free software)
to handle the translation between RTMP and SIP/RTP, then set the
rtmpserveraddress to point to your flash media server and increase the value of
the enginepriority_flash setting.
How to handle Java, Native and App engines?
These engines doesn’t need any special server side
support and they works with old legacy SIP (all SIP servers) without any extra
settings or software. When the browser VoIP plugin uses one of these engines,
there is a direct connection between the engine (running in the user’s browser)
and your VoIP server, without involving any intermediary relay (Actually RTP
can also flow directly between the endusers, bypassing your SIP server. This is
up to your server settings and its NAT handling features).
·
NS: The NS engine requires a
one-click install process to be performed by the endusers. You can prioritize
the NS engine by setting the enginepriority_ns parameter to 4. (And you can
prioritize other engines by setting the corresponding enginepriority_xxx
parameter to 4 where xxx is the engine name. See the enginepriority parameters for more details)
·
Java: If you wish to force the
usage of Java (which can offer top quality VoIP), then make sure to install the
JRE from here (if
not already installed on your system) and use Internet Explorer (any version), Pale Moon or old
Safari or Firefox below version 51 as Edge and new Chrome versions doesn’t have
Java applet support anymore.
First of all, please note
that the webphone contains also a top quality WebRTC stack, thus it can be used
as a JavaScript WebRTC SIP client library. However, it includes also other
engines (such as NS and Java) which works directly over plain legacy SIP/RTP
using the traditional SIP protocol standard, without the need for any WebRTC
capabilities.
WebRTC is becoming a trendy
technology but it has a lot of disadvantages and problems:
·
It is a moving target. The
standards are not completed yet. Lots of changes are planned also for the
upcoming years. For example Edge added a different “ORTC” implementation and
then moved to Chrome engine.
·
Incompatibility. WebRTC has known
incompatibility issues with SIP and there are a lot of incompatibilities even
between two WebRTC endpoint as browsers has different implementation and
different codec support.
·
Not supported by all browsers. No
support in IE and old browsers. No support on old iOS and MAC (except with
extra plugin downloads). No support on older Android phones.
·
Lack of popular VoIP codec such
as G.729 which can be solved only by expensive server side transcoding
·
Weak configuration support. It is
a black-box in the browser with browser specific bugs and a restrictive API.
You have little control on what is going in the background.
·
Missing functionalities: for
example it is not possible to change to speakerphone on iOS/Safari.
·
Extra server side processing
required for TLS/Websocket/DTLS/SRTP and error prone WebRTC to SIP conversion.
·
A WebRTC to SIP gateway required
if your VoIP server don’t have built-in support for WebRTC.
·
Adds unneeded extra complexity.
The server has to convert from the websocket protocol to clear SIP and from
DTLS to RTP.
Luckily the Mizu webphone
has some more robust engines that can be used without these limitations and it
can prioritize these over WebRTC whenever possible, depending on available
browser capabilities and user willingness. (Non-obtrusive notification might be
displayed for the enduser when a better engine is available or if a user can
upgrade with one-click install).
One of the advantages of the
Mizu webphone is that it can offer alternatives for WebRTC, so you can be sure
that all your VoIP users are served with the best available technology,
regardless of their OS and browser.
However we do understand
that WebRTC is comfortable for the endusers as it doesn’t require any extra
plugin if supported by the browser. The mizu browser phone takes full advantage
of this technology and we provide full support for WebRTC by closely following
the evolution of the standards. We have invested a lot of time and effort to
handle the above WebRTC related inconveniences as smoothly as possible
incorporating a robust and full featured WebRTC stack into the webphone,
capable to handle most edge cases.
With a WebRTC only solution
you would miss all the benefits that could be offered by a standard SIP/RTP
client connecting directly to your VoIP server with native performance, full
SIP support including all the popular VoIP codec and without the need for any
protocol conversion, directly from enduser browser.
The webphone by default will try to
handle all the differences, shortcomings and restrictions in different
environments to provide an unified API and consistent experience across all
browsers, engines and operating systems. However there are some operations,
which might not work correctly for your use-case, depending on your SIP server,
WebRTC gateway, OS, browser and the used webphone VoIP engine.
Please test with the demo
version first before to purchase a license, to make sure that it fulfills your
requirements and it works correctly in your environment.
The followings are the notable
limitations:
o Not all the listed features are available from all
engines (the webphone might automatically handle these differences internally)
o The webphone doesn’t work when Private
Browsing or Incognito mode is enabled (because no outbound WebSocket
connections are allowed when private browsing is enabled)
o Relative paths from iframes are not working in old
Internet Explorer versions such as IE8. The demo index.html are using iframes
to load the different examples and the upper folder (../) from the paths are
not working in this case (for example in line <script
src="../webphone_api.js"></script>). As a workaround, the
webphone examples are opened in a different window/tab from IE8.
o Some platforms
currently have very limited VoIP support available from browsers. The most
notable is old iOS releases where the default browser (old Safari versions)
lacks any VoIP support. The webphone tries all the best to work around about
these by using its secondary engines offering call capabilities also for users
on these platforms
o Audio output devices can’t be set programmatically in
some browsers if you are using WebRTC because
navigator.mediaDevices.enumerateDevices() and getUserMedia() returns only input
devices (no output device is ever returned). In these situations it is expected
that the user might change the audio device to be used from the WebRTC audio
permission popup. See the Firefox bug report for more details (marked as Fixed but still bogus). Also iOS browsers
don't have access at all to audio devices.
o Old Android Chrome browsers might use the speaker
(speakerphone) for audio. This might affect only the WebRTC engine on old
Android phones/tablets and you will have normal audio output if using the App
engine on Android. Otherwise it can be changed with the androidspeaker parameter.
o Volume cannot be changed programmatically if you are
using the WebRTC engine in Chrome and Firefox (use the OS volume settings)
o For chat/IM to work your server have to support SIP
MESSAGE as described in RFC 3428
(Supported by most SIP servers. See this section
for more details)
o In case if you wish to use BLF, then you should use
the NS or Java engine as BLF for WebRTC is in beta only
o WebRTC media negotiation issues with simultaneous
calls. As a workaround, delay the second/third/etc call with 2 seconds. Only
the WebRTC engine is affected by this.
o JRE audio handling is not so robust on Linux and you
might encounter audio open issues in some Linux/JRE/audio system combinations
when using the NS or Java engine.
o No support is provided for the AEC functionality. AEC
is not capable to remove echo in all circumstances (after average statistics it is capable to eliminate
more than 90% of the echo with around 90% success rate; the success rate
depends on many factor such as device, audio driver, engine, room, network,
peers, environment, settings).
o Not all the listed codec’s are supported by all
engines. If you are using the webphone as a JavaScript WebRTC library, then
codec support is up to the browser. More details here.
o Video is implemented only with the WebRTC engine (the
webphone will auto-switch or auto-offer WebRTC whenever possible on video
request). WebRTC-SIP video calls works only if there are a compatible codec on
SIP side (H.264 or VP8). WebRTC-WebRTC video calls are expected to work in all
circumstances between same browsers if the users have a camera device. Video
re-INVITE will not work with the webphone (use with SIP devices which initiate
or accept the video from start)
o There is no video support on old Safari versions
(video is supported from iPhone 7 / iOS 11 / Safari 11)
o While video should work via WebRTC on all supported
platforms, we recommend testing it first in your environment before to purchase
if this feature is important for you. Some SIP servers and devices doesn’t
handle the video features correctly and this is very difficult to debug (We
can’t offer support for extra video features. It either works or not works in
your environment depending on your SIP server and SIP peers capabilities).
o Screen sharing might require extra plugin and might not
work in all browsers (it was tested and works with both Chrome and Firefox but
due to API changes we can’t guarantee this functionality in all circumstances)
o Mizutech doesn’t provide direct support for the video
functionality with third-party devices, because of the many bogus
implementations and codec fragmentation. You will have the maximum chance for
the success if both parties are connected by WebRTC
o Conference support with local RTP mixer is
implemented only in the NS and Java engines. While the enduser is on WebRTC,
then local conference mixer is not available which means that conference can be
done only via server side dtmf control or conference rooms between webphones or
by auto switching to NS when available. Read more here.
o The NS engine for macOS have been revoked because
latest macOS versions doesn’t allow audio recording from services. It might be
reintroduced later after a rewrite to run it as regular app instead of a
service. You can use any other supported engine on MacOS such as the WebRTC
engine (handled automatically by default)
o Some features might not work correctly between WebRTC
and SIP. This is not a webphone limitation, but it depends completely on server
side (your softswitch or gateway responsible for WebRTC-SIP protocol
conversion) and for the loss of direct mapping between WebRTC and SIP protocol
capabilities
o Some features require also proper server side support
to work correctly. For example presence, chat, conference, video, call hold,
call transfer and call forward. See your VoIP server documentation about proper
setup
There are many browser and
OS related bugs either in the browser itself or in the plugins used for VoIP
(native/webrtc/java/flash). Most of the issues are handled automatically by the
webphone by implementing workarounds for a list of well-known problems. Rarely
there is no any way to circumvent such issues from the webphone itself and
needs some adjustment on server or client side.
Some chrome versions only
use the default input for audio. If you have multiple audio devices and not the
default have to be used changing on chrome, Advanced config, Privacy, Content
and media section will fix the problem.
Some linux audio drivers
allow only one audio stream to be opened which might cause audio issues in some
circumstances. Workaround: change audio driver from oss to alsa or inverse.
Other workarounds: Change JVM (OpenJDK); Change browser.
Incoming calls might not
have audio in some circumstances when the webphone is running in Firefox with
the WebRTC engine using the mizu WebRTC to SIP gateway (fixed in v.1.8).
Java related:
These details are important
only if for some reason you might wish to force the Java engine. However please
note that these java related issue are not real problems since when possible
the webphone uses WebRTC or NS engines, especially as Java is not available in
latest Chrome and Firefox anymore.
If the java (JVM or the
browser) is crashing under MAC at the start or end of the calls, please set the
“cancloseaudioline” parameter to 3. You might also set the
"singleaudiostream” to 5. If the webphone doesn’t load at all on MAC, then
you should check this link.
One way audio problem on OSX
10 Maverick / Safari 6/7 when using the Java engine: Safari allows users to
place specific websites in an "Unsafe Mode" which grants access to
the audio recording. Navigate to "Safari ->Preferences -> Security
(tab) and tick "Allow Plug-ins" checkbox. Then depending on safari
version:
-from the Internet plug-ins (Manage Website Settings)" find the site in
question and modify the dropdown to "Run In Unsafe Mode".
-or go to Plug-in Settings and for the option "When visiting other
websites" select "Run in Unsafe Mode". A popup will ask again,
click "Trust"
You will be asked to accept the site's certificates or a popup will ask again,
click "Trust". Alternatively, simply use the latest version of the
Firefox browser.
Java in modern browsers is
not supported anymore (the webphone will select NS or WebRTC engine by
default).
If for some reason you still wish to force Java, then in Chrome versions
prior September 1, 2015 it can still be re-enabled:
Go to this URL in Chrome: chrome://flags/#enable-npapi (then mark activate)
Or via registry: reg add HKLM\software\policies\google\chrome\EnabledPlugins /v
1 /t REG_SZ /d java
Java can be also re-enabled in Firefox 52 by configuring the
Firefox setting plugin.load_flash_only to false.
(By default the webphone
will handle these automatically by choosing some other engine such as WebRTC
unless you forced java by the engine priority settings)
Symptoms:
·
If your html can’t find the
webphone library files you might see the following errors in your browser
console:
o
Failed to load resource:
…/js/lib/api_helper.js
o
ReferenceError: webphone_api is
not defined
·
If not supported by browser or
your webserver doesn’t allow the required mime types, then the page hosting the
webphone might load, but you will not be able to make calls (VoIP engine will
not start)
Fixes:
·
Missing library: Make sure that
you have copied all files from the webphone folder (including the js and other
sub-folders)
·
Browser support: Make sure that
your browser has support for any of the implemented VoIP engines: either Java
or WebRTC is available in your browser or you can use the NS engine (on
Windows, MAC and Linux) or the app engine (on Android and iOS)
·
Web server mime settings: Make
sure that the .jar and .exe mime types are allowed on your webserver so the browsers are able to
download platform specific native binaries
·
HTTPS: Set a SSL certificate for
your website for secure http, otherwise WebRTC will not work in chrome
·
Lib not found: If your webphone
files are near your html (in the same folder) then you might have to set the
webphonebasedir parameter to point to the javascript directory
webphonebasedir
This setting
is deprecated after 1.9 as the webphone should automatically detect its library
path automatically.
If the html page, where you are including
the webphone, is not in the same directory as the webphone, then you must set
the "webphonebasedir" as the relative path to the webphone base
directory in relation to your html page.
The base directory is the "webphone" directory as
you download it from Mizutech (which contains the css,js,native,...
directories).
For example if your page is located at
http://yoursite.com/content/page.html and the webphone files are located at
http://yoursite.com/modules/webphone then the webphonebasedir have to be set to
'../modules/webphone/'
The webphonebasedir parameter must be set
in the webphone_config.js file directly (not at runtime by
webphone_api.webphonebasedir).
Default is empty (assumes that your html is
in the webphone folder).
·
NS engine download not found: you
might have to set the nativepluginurl parameter to point to the ns installer
file.
nativepluginurl
(string)
This setting is deprecated after 1.9 as the
webphone should automatically detect its library path automatically.
The absolute
location of the Native Service/Plugin installer. In most of the cases this is
automatically guessed by the webphone, but if for some reason (for example: you
era using URL rewrite) the guessed location is incorrect, then it can be
specified with this parameter.
The
Service/Plugin installer is located in webphone package "native"
directory.
Example:
“https://mydomain.com/webphopne/native/WebPhoneService_Install.exe”
Default value is
empty.
The webphone is not starting
Symptom: The webphone user interface is loaded but
nothing is happening (webphone doesn’t start / connect).
Solution: If the webphone doesn’t start or doesn’t
connect, that means that most probably you haven’t set the necessary parameters
(such as serveraddress/username/password) and/or you haven’t called any of the
API functions.
The webphone will start when one of the followings
happens:
·
Autostart: If the important
parameters such as the serveraddress/username/password (and sometimes
others such as the proxyaddress) are
preconfigured (set in the webphone_config.js, via the setparameter API
call or passed by URL). In this case the webphone can auto connect if you
haven’t set the autostart parameter to 0.
·
API triggered: even if the
autostart parameter is set to 0 and/or the important parameters are not set
yet, you can force the webphone start using the start()
API. The start API can also auto connect/register (if the above parameters are
preset), otherwise you can connect later after you have set these parameters
with the register() API.
Other API’s (such as the call() API) might also
trigger the start action on demand.
See this FAQ point for more details regarding auto start / auto register.
Note: There are multiple
ways to initialize the webphone:
·
Example
1:
o Set all the
important parameters in the webphone_config.js and just launch the webphone
html (any of the included skins or samples or your own including the
webpone_api.js). The webphone should auto start and auto connect.
·
Example
2:
o Set only the
serveraddress parameter in the webphone_config.js and just launch a html which
also has a login page (such as the included softphone.html). In this case the
webphone should just stop at the login page (if there is no any cached
credentials yet) waiting for the enduser to enter it’s username/password and
the start will be triggered from the OK/Login button
·
Example
3:
o Set the autostart
parameter to 0.
o Preconfigure the
serveraddress (or other required parameters such as the proxyaddress if needed)
set in the webphone_config.js, via the setparameter API
call or passed by URL
o Call the start() function
o Supply the
username/password (or other required parameters such as the sipusername if
needed) using the setparameter API.
o Call the register()
function
·
Example
4:
o Set all the required
parameters using the setparameter API
o Use the call()
function (this will auto trigger the start action and also the register action
if the register parameter is not set to false)
·
Example
5:
o Any other
combinations
o The important thing
is to just set the webphone parameters with any method and then call any action
API such as start/register/call/etc.
Can’t connect to SIP server
If the webphone cannot
connect or cannot register to your SIP server, you should verify the
followings:
·
You have set your SIP server
address:port correctly (from the user interface or “serveraddress” parameter in
the webphone_config.js file)
·
In case if you have set by the webrtcserversaddress parameter, make sure that it
actually works. You can test it with this
tool (set the “Location” to the same
string as you have set for the webphone webrtcserveraddress parameter and check
if it can connect).
·
Make sure that you are using a
SIP username/password
valid on your SIP server
·
Make sure that the autostart parameter is 1 or 2 and the register parameter is 1 or 2. Otherwise use the start() and register()
API explicitly. Details here.
·
If you are using it as a WebRTC
SIP client library with the Mizu WebRTC SIP gateway service, make sure that
your firewall or fail2ban doesn’t block the gateways. You should white-list
rtc.mizu-voip.com and usrtc.webvoipphone.com
·
Make a test from a regular SIP
client such as mizu softphone or x-lite
from the same device (if these also doesn’t work, then there is some
fundamental problem on your server not related to our webphone or your device
firewall or network connection is too restrictive)
·
Use an account-extensions with
digest authentication (don’t use IP authentication if you are using the
webphone WebRTC engine via gateway; in Asterisk the extension should be
configured as “users” and not as “peer”)
·
Check if some firewall, NAT or router
blocks the webphone process or the SIP signaling
·
Check the browser console output
for possible errors (search for “ERROR”, but note that some error messages are
normal to occure)
·
If there are no any answer for
the REGISTER requests, turn on your server logs and look for the followings:
o
The REGISTER reaches your server?
o
Is there any response triggered
(or some error)?
o
If answer is triggered, is it
sent to the correct address? (it should be sent to the exact same address from
where the server received the REGISTER request)
o
The answer packet reach the
client PC? You can use Wireshark
to see the packets at network level.
·
Send us a
detailed client side log if still doesn’t work with loglevel set to 5 (from the
browser console or from softphone skin help menu)
The NS engine is a native
executable which is running in background on your OS as a system service,
offering SIP/media capabilities for the webphone. The webphone communicates
with the NS engine via a websocket connection (or with HTTP poll if websocket
is not available in your browser).
The followings might be
responsible for the NS engine failure (in case when the webphone has to use the
NS engine but can’t connect):
1.
The NS engine is not running:
make sure that the webphone service is started successfully and you can see it
in your running process list from Task Manager.
The
“Webphone” or “YourBrandName” service state can be seen by opening the services
management console (run services.msc from
the command line)
2.
You are running a very old
outdated NS engine.
For Windows you can install the latest version from http://yourdomain.com/path_to_webphone/native/WebPhoneService_Install.exe
(or from the webphone package native folder sent to you by Mizutech)
3.
The webphone can’t resolve the
ns4.webvoipphone.com domain name to 127.0.0.1: Verify by running ping ns4.webvoipphone.com from your command line
and it should respond from 127.0.0.1. This might fail for the following
reasons:
a.
No any internet connection
b.
DNS requests are blocked
c.
You have a proxy which cannot
resolve this domain or blocks it
Possible
workaround: add the following line the hosts file of the client PC: 127.0.0.1 ns4.webvoipphone.com
4.
Check your HTTP proxy if any
5.
Your browser doesn’t accept the
SSL certificate of the domain for ns4.webvoipphone.com
some reason. As a workaround, you might add it to your browser white list
6.
The webphone was unable to listen
on the required ports. Make sure that no other applications are using ports: TCP 10443, TCP 18520, UDP 18521, UDP 18522 on your
client PC. You can verify this from the Resource Monitor -> Network tab or
with the nestat –a command
7.
The communication between the
browser and the NS service is blocked. This might happen if you have a very
restrictive firewall which blocks the communication also on localhost. As a
workaround, add the NS engine and the java.exe to the firewall exception list
To
test the connection, open the following URL:
https://ns4.webvoipphone.com:10443/extcmd_test (it should respond with some
text)
8.
The NS engine is unable to start
on Windows for some reason. Have a look at the logs (MizuCall_Servicelog.dat
and other logs files in the NS engine app directory which is located by default
at C:\Program Files
(x86)\YourBrandNameWebphone_Service\. Also check the engine log at C:\Program Files (x86)\
ourBrandNameWebphone_Service\content\native\)
9.
Corrupted JVM: In some circumstances
the NS engine might use the Java JVM which might become corrupted for various
reasons. Reinstall Java to fix this.
10.
You are trying to use the
webphone with a SIP server address which is not on your allowed (licensed)
server list. In these situations the webphone might also trigger an NS engine
upgrade request with the hope that you are running an old version and the
current SIP server address were added only later. The NS engine upgrade might
not solve the problem if the current SIP server you are trying is not allowed
also in your recent webphone/NS engine build.
11.
Send us a
detailed client side log if still doesn’t work with loglevel set to 5 (from the
browser console and also the NS and Java logs as described here)
Please note that all of these applies to the client PC
only (where the webphone is running in a browser) and has nothing to do with
your Web or SIP server.
Make a test call first
from a simple SIP client such as mizu softphone or x-lite
By default only the PCMU,PCMA,
G.729 and the speex ultra-wideband codec’s are offered on call setup which
might not be enabled on your server or peer UA.
You can enable all other codec’s (PCMA, GSM, speex narrowband, iLBC and G.729 )
with the use_xxx parameters set to 2 or 3 (where xxx is the name of the codec: use_pcma=2, use_gsm=2, use_speex=2,use_g729=2,use_ilbc=2).
Some servers has problems with codec negotiation (requiring re-invite which is
not support by some devices). In these situations you might disable all codec’s
and enable only one codec which is supported by your server (try to use G.729
if possible. Otherwise PCMU or PCMA is should be supported by all servers)
If you receive the “ERROR,
Already in call with xxx” error on call attempts and you wish to enable multiple
calls to/from the same number, set the disablesamecall
parameter to 0.
The webphone by default
doesn’t allow direct cross-domain calls. For example if you are registered as a@A.com (to A domain) then you will not be able to make
direct calls to b@B.com (to B domain). Contact mizutech support to remove
this limitation.
If still doesn’t work send us a
detailed client side log with loglevel set to 5 (from the browser console or
from softphone skin help menu)
How to enable only one single codec
Here is an example configuration enabling only PCMU:
prefercodec:
‘PCMU’,
codec:
‘PCMU’,
alwaysallowlowcodec:
0
For NS and Java you can also use the
use_xxx settings where xxx is the codec name and the accepted values are 0 for
never,1 for don’t offer,2 for yes with low priority,3 for yes with high
priority.
For example to disable all codec’s
except PCMU, you might set:
use_pcmu: 3 use_pcma: 0, use_opuswb:
0, use_opusnb: 0, use_g729: 0, use_gsm: 0, use_speex: 0, use_speexwb: 0,
use_speexuwb: 0, use_ilbc: 0
Note: you should never set the
use_codec settings to 0. Set to 1 if you don’t wish to use a codec (so the webphone
will still have a chanche to use that coded if the preferred is not available
or the other peer sends some other codec then negotiated)
Have a look at the followings if calls are
disconnecting:
·
Call disconnection immediately
upon setup can have many reasons such as codec incompatibility issues, NAT
issues, DTLS/SRTP setup problems or audio problems. If you are not sure, send a
detailed log to webphone@mizu-voip.com
·
If the calls are disconnecting
after a few second, then try to set the “invrecordroute” parameter to “true”
and the “setfinalcodec” to 0.
·
If the calls are disconnecting at
around 100 second, then most probably you are using the demo version which has
a 100 second call limit.
·
If the calls are disconnecting
when you open other webpages (other tabs or in new window), make sure that your
CPU usage is not too high (which might be caused by other webpages or by
misusing the phone API)
·
You are calling the hangup API
from some code path (add a log for each of your hangup function calls and
inspect your browser console)
·
The disconnect might be initiated
by the server or from the peer endpoint (see the logs from where the BYE is
sent)
Test
environment limitations
You can test the webphone also without a web server,
by launching from local file system (for example from your desktop) or
development environment using a localhost server.
For example just extract the webphone.zip on your
desktop and double click on the index.html to begin the usage.
Limitations when run from development tools:
Sometime you might wish to run the webphone from your
preferred development environment (for example for debug capabilities). The
limitations in this case depends on the sandboxing technology used by your
tools. Some tools might not allow websocket connections (this will block both
the NS and the WebRTC engines). Try to change the browser engine if you run
into these limitations or use an external browser process if possible.
Also make sure to open/run only one webphone instance
at a time, especially if you are testing with the NS engine (close old browser
windows before opening a new webphone instance).
Some versions of Chrome also might fail if you try to
run WebRTC from html launched from local file system.
The workaround for this is to launch with
--allow-file-access-from-files parameter
(Something like this on windows: "C:\Program
Files (x86)\Google\Chrome\Application\chrome.exe"
--allow-file-access-from-files C:\path\softphone.html)
For a better experience, we recommend to deploy the
webphone files on a web server and test from there. The best experience is with
a secure web server (via https), but you can also test with a local web server
via http://localhost.
Unsecure websocket connections are usually not
allowed on Linux (use a https server for testing).
In short:
Yes, the webphone works on private networks by
default, without the need of any configuration changes.
Note: It is
completely normal to use the webphone on LAN’s (browser client with private
IP). This FAQ refers to the case when the SIP server (set by the “serveraddress” parameter where the
webphone will register to) and/or Web server (from where you load your webpage embedding the
webphone) is located on private IP.
Details:
·
The webphone can be used also on
local LAN’s (when your VoIP server and/or Web server are on your private
network).
·
The NS and Java engines will
connect directly to your server as a normal SIP softphone does.
·
For
WebRTC to work you will need a
WebRTC to SIP gateway on your LAN or your PBX have to support WebRTC, otherwise
this engine will not be picked up (this is handled automatically). You should also
host your webpage on https (SSL certificate installed on your Web server) for
WebRTC to work in modern browsers (or test it by launching from local file
system).
·
If WebRTC is not supported in
your environment, then the webphone might offer to download a browser plugin,
which is usually an one-click installer.
·
The webphone could use the
Mizutech STUN, TURN, JSONP and HTTPS gateway services by default, however these
are not required on local LAN’s (the webphone will detect this automatically
and will not try to use these services while on local LAN).
Old notes (these are not relevant
anymore in latest webphone version since NS engine is implemented also for MAC
and Linux):
Recommendation for quick tests on local LAN :
·
If you wish to
work with the webphone on local LAN and your VoIP server doesn’t have WebRTC
support or your webserver doesn’t have SSL installed for the domain you are
using (HTTPS), we recommend to test on Windows operating system (with the NS
engine). On other platforms you might use a Java enabled browsers for easy
tests or setup WebRTC in your environment.
Recommendation for production on local LAN :
·
If the client PC’s
are running Windows OS then there is nothing to do. The webphone will run
optimally using its NS engine
·
For other operating
systems (MAC, Linux) we recommend to use the webphone’ WebRTC engine: check
your VoIP server WebRTC capabilities and set the webrtcserveraddress webphone parameter accordingly or install
a local WebRTC-SIP gateway. You can find more details here.
The webphone can be used
also without internet connection with some limitations. An easy workaround for
all this would be to enable at least CA verifications (SSL certificate
verifications) to the internet, however if this is not possible then the
following applies:
·
WebRTC in Chrome needs HTTPS
(secure http), which will work only with a local policy, otherwise the browser
will not be able to verify the SSL certificate against public CA. If you can’t
setup a local CA or browser rule for this, just disable WebRTC (or use old
Firefox v.67 instead of Chrome if you need WebRTC without certificate).
·
Java applets need to be signed
and on startup the JVM will have to pass the code verification signature.
Workaround: Just disable the Java engine or add the applet location to the exception site list (this is only if you wish to use the Java engine which is otherwise
rarely used)
·
The NS engine can be used from
unsecured http in local LAN’s with no issues (on https you might need to add
the ns4.webvoipphone.com domain to the browser security exception list. This
domain name just points to localhost/127.0.0.1, used by the webphone to
communicate with the NS engine)
These circumstances are also
automatically handled by the webphone, always selecting the best suitable
engine if it has at least one available and unless you change the engine
priority related settings.
Using the
webphone in controlled environment
If you are using the
webphone in a controlled environment (where you have control over the clients,
such as call-centers) then you might force the NS or Java engines by disabling
or lowering the priority for the WebRTC engine (enginepriority_webrtc = 1).
This is because NS and Java are more native for SIP/RTP and might have better
quality, more features and lower processing costs on your server. The big
advantage of WebRTC is that it can work without any extra plugin
download/install, however in a controlled environment you can train your users
(such as the callcenter agents) to allow and install the NS engine when
requested and this one-time extra action will reward with long term quality
improvement.
WebPhone behind HTTP proxy
Usually the webphone can
auto-detect the HTTP proxy capabilities and act accordingly. However in some
rare circumstances the connections might fail if you are behind a misconfigured
or outdated HTTP proxy.
You can find our whether you
are behind a proxy or not by checking your browser connectivity settings. The
followings are the common issues:
In case if you have
installed the NS engine on Windows, make sure that your browser can resolve the
ns4.webvoipphone.com domain to 127.0.0.1. You can also test this by opening
this link in your browser: https://ns4.webvoipphone.com:10443/extcmd_test. If
can’t connect, then make sure to configure your browser to bypass the proxy for
this domain and/or set this domain in your hosts file to point to 127.0.0.1.
This is relevant only for some browsers which doesn’t allow direct connections
to localhost, such as old Edge and Internet Explorer.
In case if you wish to use
the webphone WebRTC engine (or it is automatically selected by the webphone),
then make sure that your HTTP proxy has support for WebSocket, otherwise WebRTC
will not work.
Load the webphone in iframe
If you wish to load the webphone in an iframe,
make sure to allow microphone and camera access to that iFrame, because
otherwise it will not work in latest Chrome or
in other modern browsers.
Example:
<iframe id="webphoneframe"
src="softphone.html" width="300" height="500"
frameborder="0" allow="microphone *; camera *; autoplay *"
allowfullscreen="true" ></iframe>
Note: It is important to set
allow="microphone; camera", otherwise the WebRTC engine can’t work! (you can skip this only if you prefer
other engines such as NS and you wish to completely disable WebRTC for some
reason).
To avoid cross domain issues, you should
host the webphone on the same domain where you host your website/webpage.
Otherwise make sure to configure your server and iframe permissions/security
attributes accordingly.
You might place your webphone user interface
in a DIV tag instead.
You should use relative paths instead of
full URI if you load the webphone from the same domain.
You might also have to set the iframe sandbox attribute after your needs.
For example you might set the following
sandbox attribute to allow all permissions: "allow-forms allow-modals
allow-popups allow-popups-to-escape-sandbox allow-same-origin
allow-scripts".
Example:
<iframe id="webphoneframe"
src="softphone.html" width="300" height="500"
frameborder="0" allow="microphone *; camera *; autoplay *"
allowfullscreen="true" sandbox="allow-forms allow-modals
allow-popups allow-popups-to-escape-sandbox allow-same-origin
allow-scripts" ></iframe>
Instead of setting your iframe parameters
statically in your html, you can also set it from JS like this:
(this script will also pass the page URI
query parameters to the webphone frame)
window.onload = function ()
{
var page =
window.location.href;
if (typeof
(page) !== 'undefined' && page !== null && page.indexOf('?')
> 0)
{
page
= page.substring(page.indexOf('?'));
}else
{
page
= '';
}
var frm =
document.getElementById('IFRAME_ELEMENT_ID');
if (typeof
(frm) !== 'undefined' && frm !== null)
{
frm.src
= 'https://yourdomain.com/path_to_webphone/softphone.html' + page;
frm.setAttribute("allow",
"microphone *; camera *; autoplay *");
frm.setAttribute("allowfullscreen",
"true");
setTimeout(
function () { frm.style.display = 'block'; }, 50); }else {
try{console.log('Could not find webphone frame');} catch(e) { ; }
}
};
In case if you wish to access the
webphone_api object in an iframe from outside the iframe, then you should
either host both (your main page and the webphone/iframe content) on the same
domain or set the Access-Control-Allow-Origin header on your web server as
described here, otherwise you will get ERROR
DOMException: Permission denied to access property errors.
In case if you wish to include the webphone globally
to your websites to be present on all pages (such as a “call to support” widget
flying on the bottom-right side of your page), make sure to don’t let the
webphone to auto-initialize itself automatically with each page load/reload
because this might slow-down the responsivity of your website.
For this just set the “autostart” parameter to “0”.
In this call you can delay the VoIP engine
initialization to the point when the enduser actually wish to interact with
your VoIP US (such as clicking on your click to call button).
Multiple phones
on the same page
You just have to include the “webphone_api.js” to
your page and create multiple VoIP UI elements.
For example you might have a contact list (or people
list) displayed on your page, with a “Dial” button near each other. You don’t
even need to initialize the webphone on your page load (set the “autostart”
parameter to “0”). Just use the webhone_api.call(number) function when a user
click on the dial button and the webphone will initialize itself on the first
call.
The softphone user interface (softphone.html) can’t
be included multiple times in a page. If you really need multiple phone UI or
multiple completely separated webphone instance on your page, then use separate
iFrame for them.
Example:
<div
class="content">
<iframe
id="webphone1" src="./webphone1/softphone.html?wp_anyparameter=a"
width="300" height="500" frameborder="0"
allow="microphone; camera; autoplay" allowfullscreen="true"
sandbox="allow-forms allow-modals allow-popups
allow-popups-to-escape-sandbox allow-same-origin allow-scripts"
></iframe>
<iframe
id="webphone2" src="./webphone2/softphone.html?wp_anyparameter=b"
width="300" height="500" frameborder="0"
allow="microphone; camera; autoplay" allowfullscreen="true"
sandbox="allow-forms allow-modals allow-popups
allow-popups-to-escape-sandbox allow-same-origin allow-scripts"
></iframe>
You should also adjust the profile
and/or the usepathinfilenames parameters to avoid configuration mismatch between
the webphone instances if you are using different settings. For example you
might pass an unique string as the profile parameter in the iframe URL
(wp_profile=anystring) and set the usepathinfilenames parameter to 2 in the
webphone_config.js file.
Load the webphone on demand
Below are a few (both recommended and NOT
recommended) methods to load the webphone into your webpage:
a.
Load "webphone_api.js"
using a script tag in the <head> section of your web page. This is
actually not “on demand”, the webphone will be loaded when the page is loaded.
b.
Load "webphone_api.js"
on demand, by creating a <script> DOM element. Below is an example
function which loads the script into the <head> section of the page:
function
insertScript(pathToScript)
{
var
addScript = document.createElement( "script" );
addScript.type
= "text/javascript";
addScript.src
= pathToScript;
document.head.appendChild(
addScript );
}
c.
The webphone can also be loaded
into an iframe on demand. To have access to the webphone API in the iframe from
the parent page, you have to follow the below two steps:
i.
include the /js/lib/iframe_helper.js file into your parent
html page <head> section
ii.
set the iframe's
"id" attribute to
"webphoneframe", for example: <iframe
id="webphoneframe" src="softphone.html"
width="300" height="500" frameborder="0"
allow="microphone; camera" ></iframe>
iii.
access the webphone API from the
parent page only after the page has finished loading, for example:
window.onload
= function ()
{
webphone_api.onAppStateChange
(function (state)
{
if
(state === 'loaded')
{
webphone_api.setparameter("serveraddress",
"SERVERADDRESS");
webphone_api.setparameter("username",
"USERNAME");
webphone_api.setparameter("password",
"PASSWORD");
webphone_api.start();
}
});
};
Not recommended:
1. The web phone can be loaded on demand using
document.write(), but it is a bad practice to call document.write() after the
page has finished loading.
2. The web phone can also be loaded using any AMD
(Asynchronous Module Loader). This is not recommended, because webphone also
uses AMD (Require JS) to load its modules, so it won't improve performance, but
it can lead to conflict between AMD loaders.
The webphone is a client side software and pages/tabs
in your browser are separate entities, so a new page doesn’t know anything
about an old one (except via server side sessions, but it is impossible to
transfer live JavaScript object via your server in this way).
There is no way to keep a WebRTC session alive
between page loads.
Instead of this, you should choose one of the followings:
·
run the webphone in a separate
page (on its own dedicated page, so the enduser can just switch to this
window/tab if needs to interact with the webphone)
·
run the webphone in a separate
frame
·
load your content dynamically
(Ajax)
If this functionality is a must for your project,
check the following FAQ for the possibilities.
However, if you are using the NS engine, then calls
can survive page refresh by setting the following parameters:
·
callreceiver: 2
·
backgroundcalls: 1
·
destroyonpageclose: 0
·
needunregister: false
There might be situations when you might wish to use
the same webphone instance on multiple pages (cross-tab: opened in different
browser tab or windows).
For example to start a call on a page, open a second
page and be able to hangup the call on this second page.
First of all, it is important to note that the
webphone is client side software (it is impossible to implement a voip client
which would run on the server side).
This means that from the browser perspective, each of
the pages are treated completely separately (Only your web server knows that
those belongs together called a “session”). Each page load or reload will
completely re-initialize also the webphone (if the webphone is included in the
page). With other worlds: multiple pages opened from your domain doesn’t know
about each other at all and one page can’t access the other one (except if you
send some ajax message via your web server, but this kind of message passing is
useless in this case since you can't transfer the whole webphone javascript
object).
This means that you should avoid the above use-case
and just launch the webphone on a separate page in this case, so the enduser
can switch to the page dedicated for the webphone if need to interact with a
call (make a call, hangup current call or other operations such as mute,
conference, dtmf).
Here are a few ways to implement such functionality:
·
Simple data sharing: If you just
want to share some details across your pages, then you can do it via cookies or
from pure
javascript using the window.name reference. (This
can be used only for simple data sharing, but not to share live JavaScript
objects such as the webphone)
·
NS engine: It is possible with
the NS engine to have the webphone survive page (re)loads or opening new pages
on your website. This can be a solution of you know in advance that all users
will use the NS engine only (increase the value of the enginepriority_ns
parameter in this case)
·
Using a global webphone object:
There is way to share a global webphone instance across the opened pages: using
the window.opener property which is a reference to the window that opened the current
window. This means that you will pass the webphone instance across your pages
so can access your global webphone object from secondary opened pages via the
opener reference (Find an example for this below)
·
Avoid this use-case and just
launch the webphone on a separate page in this case, so the enduser can switch
to the page dedicated for the webphone if need to interact with a call (make a
call, hangup current call or other operations such as mute, conference, dtmf).
You might also load the webphone in a iframe.
In case if you wish to keep the calls on page close,
then set the destroyonpageclose parameter to
0 and the autostart
parameter to 0.
Here is a simplified example to access the webphone
object via window.opener:
//It is
important to set the “autostart” parameter to “0” in the webphone_config.js to
avoid auto initialization of the webphone on all pages where included (we will
start the webphone explicitly when needed)
//store
the wopener variable to be used here and also on subsequent pages (useful if we
open a third page from the second and so)
var
wopener = window; //set to this document
if(window.opener
&& window.opener.webphone_api)
{
wopener
= window.opener; //set to parent page document
}
if(wopener.wopener
&& wopener.wopener.webphone_api)
{
wopener
= wopener.wopener; //the parent page might also loaded from its own
parent, so load it from there
}
//create
a reference to the webphone so we can easily access it on this page via this
variable
var
wapi = webphone_api;
//Initialize
your webphone if not initialized yet
if(wopener
&& wopener.webphone_api)
{
//load
the wapi instance from the parent page in this case
wapi
= wopener.webphone_api;
//check
if already initialized
if(wapi.isstarted
!= 1)
{
wapi.isstarted
= 1;
//we are
staring the engine here, however you can delay the start if you wish to the
point when the user actually wish to use the phone such as making a call
wapi.start();
}
//else
already initialized by parent
}
else
if(wapi && wapi.isstarted != 1)
{
//we are
the first page
wapi.isstarted
= 1;
wopener
= window; //set the wopener to point to this page
wapi.start();
}
//use the
phone api on this page
function
onCalllButtonClick()
{
if(wapi)
wapi.call();
else
alert('error: no webphone found (webphone_api.js not included?)');
}
You can find a better/fully working example in the
webphone package: multipage_example.html.
Certain operations (such as file download controls)
might trigger window.unload events which might trigger webphone
unregistrations.
You might have to prevent these event being triggered
by your controls by using this technique (It can be applied to any element such as
<div>,<a>,<button>)
How to prevent
multiple endpoints to one account
Users might login to the SIP server from multiple
locations with the same user account and most SIP servers will forward the call
to all locations by default (multiple AOR/register binding with call fork to
multiple registered endpoints).
In some circumstances you might prefer only one
register for an account (for example if the user leaves the webphone running at
home, then logins from the office, all calls will be forked both to the office
and to home).
To prevent registration from multiple locations (thus
forking the calls to multiple endpoints), set the unregonidle
parameter to the number of seconds after that the webphone will automatically
unregister on no user activity.
You might also set the unregall
parameter to 1 to always unregister all accounts and the unregonstart parameter to 1 to unregister at
startup from the NS engine (before the first register).
You might also lower the registerinterval (don’t set it to higher then the unregonidle
parameter).
Example settings:
unregonidle:
600, //unregister after 10 minutes of user idle
unregall:
1, //optional if required for your use-case
unregonstart:
1, //optional if required for your use-case
You might also configure your server to allow only
one endpoint (registrar AOR) per account and/or disable call forking.
Sometimes you might have to change the settings for
each session (for example changing the user credentials).
In these situations it might happen that the webphone
is still using the old setting (which you have set for the previous session and
not for the current one).
Usually this might happen if the webphone is already
started and registered with the old parameters before it loads the new
parameters (For example before you call the setparameter() API with the new
values).
To prevent this, you should set the
"autostart" parameter to "0" in the webphone_config.js
You can also set the “register” parameter to
"0".
The use the start() and/or register() functions only
after the webphone were supplied with the new parameters.
Note:
The webphone is also capable to load
it’s parameters from the URL. Just us the format required (wp_username,
wp_password and others).
It is not needed to call the
register() after start() because the start() will automatically initiate the
register if the server/username/password is already preset when it starts and
if you leave the register parameter at 1.
The webphone will need the following ports to listen
on (local ports):
·
The SIP signaling port (TCP or
UDP port configurable with the signalingport
setting)
·
SIP media ports for RTP/RTCP (UDP
ports configurable with the rtpport settings)
·
WebRTC: When using it as a WebRTC
client library, the above ports are determined by your browser and can’t be
influenced by the webphone
·
NS engine: When used with the NS
engine it requires the following TCP and UDP internal ports on localhost only:
18520, 18521, 18522, 10443 (make sure to not use some restrictive
firewall which blocks these ports also for localhost/127.0.0.1)
The webphone might connect to the following ports
(listeners on your SIP server side):
·
SIP signaling port (configurable
with the serveraddress setting. Usually UDP 5060)
·
SIP media ports for RTP/RTCP (UDP
ports as negotiated with your server via SIP signaling SDP)
·
WebRTC only (connecting to your
server WebRTC module or to WebRTC-SIP gateway):
o
Websocket for WebRTC
(configurable with the webrtcserveraddress setting. Usually TCP 80 or 8080)
o
STUN server address (configurable
with the stunserveraddress setting. Usually UDP 80, 3478 or 8090)
o
TURN server address (configurable
with turnserveraddress setting. Usually TCP 80 UDP 3478 or 5349)
·
Optional services (described here with the IP/domain listed at the end of the chapter)
For RTP statistics increase
the log level to at least 3 and then after each call longer than 7 seconds you
should see the following line in the log:
EVENT, rtp stat: sent X rec X loss X X%.
If you set the “loglevel” parameter to at least “5” than the important rtp and
media related events are also stored in the logs.
You can also access the details about the last call from the softphone skin
menu “Last call statistics” item.
This will work only with the
NS and Java engines and not with WebRTC (the WebRTC media is handled internally
by the browser with no access for RTP statistics).
In the SIP
protocol the client endpoints have to send their (correct) address in the SIP
signaling, however in many situations the client is not able to detect it’s
correct public IP (or even the correct private local IP). This is a common
problem in the SIP protocol which occurs with clients behind NAT devices
(behind routers). The clients have to set its IP address in the following SIP
headers: contact, via, SDP connect (used for RTP media). A well written VoIP
server should be able to easily handle this situation, but a lot of widely used
VoIP server fails in correct NAT detection. RTP routing or offload should be
also determined based in this factor (servers should be always route the media
between 2 nat-ed endpoint and when at least one endpoint is on public IP than
the server should offload the media routing). This is just a short description.
The actual implementation might be more complicated.
With the WebRTC engine make
sure that the STUN and TURN settings are set correctly (by default it will use
mizu services which will work fine if your server is on the public internet).
For NS and Java engines you
may have to change the webphone configuration according to your SIP server if
you have any problems with devices behind NAT (router, firewall).
If your server has NAT support then set the use_fast_stun and use_rport
parameters to 0 and you should not have any problem with the signaling and
media for webphone behind NAT. If your server doesn’t have NAT support then you
should set these settings to 2. In this case the webphone will always try to
discover its external network address.
Example configurations:
If your server can work only with public IP sent in the signaling:
-use_rport: 2 or 3
-use_fast_stun: 1 or 2 or 3 (recommended is 2)
If your server can work fine with private IP’s in signaling (but not when a
wrong public IP is sent in signaling):
-use_rport: 9
-use_fast_stun: 0
-optionally you can also set the “udpconnect” parameter to 1
Asterisk is well known about its bad default NAT handling. Instead of detecting
the client capabilities automatically it relies on pre-configurations. You
should set the "nat" option to
"yes" for all peers.
More details can be found here.
For FreeSWITCH we recommend
to set the NDLB-force-rport and aggressive-nat-detection values to true in the sip_profiles configuration. More
details here.
Use the following settings if you have 2 SIP servers:
·
serveraddressfirst: the IP or
domain name of the first server to try
·
serveraddress: the IP or domain
name of the next server
·
autotransportdetect: true
·
enablefallback: true
In this way the webphone will always send a register
to the first server first and on no answer will use the second server (the
“first” server is the “serveraddressfirst” at the beginning, but it can change
to “serveraddress” on subsequent failures to speed up the initialization time)
New versions of the webphone also implements a
“backupserver” parameter which can be used instead of the above settings.
Alternatively you can also use multiple DNS A records
or multiple SRV DNS records to implement failover or load balancing, or use a
server side load balancer.
WebRTC specific:
Browsers doesn’t lookup for SRV DNS records, thus in case if you wish to use
multiple servers based on DNS lookups, you should set multiple A records for
your domain.
Otherwise the webphone can better handle multiple
WebRTC servers by itself, without the need for multiple DNS records.
In case if you have multiple WebRTC servers or
gateways, then you can list all of them for the “webrtcserveraddress”
parameter. The webphone will automatically choose and available server and it
can failover to other if can’t connect via websocket.
The WebRTC functionality
highly depends on your OS/browser and server side WebRTC –SIP module. Check the
followings if the webphone is using the WebRTC engine and you have
difficulties:
·
Make sure that your browser has support
for WebRTC and it works. Visit the following test pages: test1, test2
·
Make sure to run the webphone
from secure http (https) otherwise WebRTC will not work in Chrome and Opera
·
If you have set the “webrtcserveraddress” parameter to point to your server or gateway, make
sure that your server/gateway has WebRTC enabled and test it also from some
other client such as sipml5: config; test
·
You might contact mizutech support with a detailed
log about the problem
·
If you are unable to fix webrtc
in your setup then you might disable the webrtc engine by setting the enginepriority_webrtc parameter to 0 or 1.
See the other possibilities here.
Media access or
Media stream permission denied
In case the Webphone is using WebRTC engine, then the
user needs to grant access for the webphone to recording audio and/or video
devices. This is required by the browsers and not by the webphone itself. This
permission mechanism is implemented in all browsers and its behavior cannot be
altered or changed.
Your servers should be configured with a domain name
and a valid TLS certificate. The websocket connection should be secure (WSS)
and the webphone should be hosted on HTTPS, otherwise browser might not allow
media permissions (microphone recording). Some browsers treats
localhost/127.0.0.1 or file also as trusted.
This Permission Request will be presented to the user
only when he or she initiates or receives a call. The user might receive
similar popups or the calls just fails if you are using the WebRTC engine but
haven’t enabled the browser to use your microphone/camera device or denied it
previously (Technically the WebRTC getUserMedia()
function call will fail in this case).
Normally before WebRTC calls your browser should
popup a box asking to allow microphone access. You should click on the
Ok/Yes/Allow/Share/Always Share button there. In some situations there is no
browser popup, only silent fail with “ERROR, Warning, cannot access microphone”
in the log.
The Permission Requests are bit different in every
browser, but usually they are presented as a popup box somewhere on the top of
the page on Desktop browsers or on the bottom of the page on mobile device
browsers.
These popups ask a question similar to the ones below
and have an "Allow" and "Block/Don't allow/Deny" button:
·
"Will you allow
www.domain.com to use your microphone and/or camera?"
·
"www.domain.com wants to use
your microphone and/or camera"
Important note on HTTP/HTTPS:
·
If the Webphone is hosted on a
secure web site (HTTPS) then the Permission Request will be displayed only once
and the user's choice will be remembered.
·
If the Webphone is not hosted on
a secure web site (HTTP), then this Permission Request will be displayed for
every single call.
·
Some browsers such as chrome
don’t allow media permission at all on unsecure HTTP. In this case you might
try to allow a website from your browser security/privacy settings (In Chrome:
settings -> show advanced settings -> privacy section -> content
settings -> microphone -> manage exceptions).
·
More details here
If access is grant to recording devices, then you
will see some kind of notification in every browser:
·
in Firefox on desktop a little
icon like window will appear on the top of the browser
·
in Chrome on desktop a red dot
will appear on the browser tab near the web page title
·
on mobile devices usually a small
notification icon will be displayed on the device's top bar
Another important case is when the user intentionally
or accidentally blocks access to the recording devices.
If you clicked on No/Not/Don’t Share/Deny/Always Deny
button sometime before then the browser might not popup with this question
again.
In this case the Permission Request will never be
presented to the user again. To present this Permission Request again so you
can grant access to the recording devices, you will have to enable it manually
from browser settings. In this case you should see a red icon in your browser
address bar and click on “Allow” from there. This is a little bit different for
all browsers, below are a few examples for most common ones:
·
in Firefox on desktop: click Menu
icon in top-right corner -> Options -> select Privacy & Security on
the left -> scroll down to Permissions section and there you can allow/block
access to recording devices for every single web site
·
in Chrome on desktop: click Menu
icon in top-right corner -> Settings -> scroll down to bottom and click
Advanced -> click Content settings and there you can allow/block access to
recording devices for every single web site
·
in other Chrome versions this can
be found at Settings -> Advanced -> Privacy and security -> Site
settings -> Camera or Microphone as described here
·
in Chrome on Android: tap Menu
icon in top-right corner -> Settings -> Site settings and there you can
allow/block access to recording devices for every single web site
·
in Android native browser you
don't have any options to control this, instead Permission Request will be
presented every time you initiate/receive a call
If access to recording devices is blocked and the
Webphone initiates/receives a call, it will display a toast message:
"Cannot access microphone".
If you are using HTTPS/WSS then by default access to
recording devices is not blocked in browsers, all browsers ask the user for
permission when a webpage (in this case the Webphone) intends to use it, but
there is the possibility that the user disabled the use of recording devices
for all websites in his browser. In this case he or she has to enable it
manually as described above.
Other notes:
·
If you disabled the permission
earlier, then there will not be any popup just a red icon in your browser and
you might see a “Waiting for permission” status in the webphone. Click on it
and enable the permission. If you don’t see a red icon that means that WebRTC
or all special permissions are disable browser wide (if you mangled your
browser settings). In this case make sure to re-enable it in your browser
setting.
·
In case if you are using the webphone
in an iframe, make sure to enable permissions for the iframe as described here
·
In some situations the browser
might not ask for permission, just silently fails. This happens in Chrome if
your website is not on secure https (Chrome doesn’t allow WebRTC from http) or
if you are using an invalid or self-signed certificate (yes, Chrome might just
silently fail with self-signed certificates).
Also you must use wss (secure websocket) for your
WebRTC server WebSocket connection, otherwise Chrome will fail on unsecure ws.
·
Some versions of Chrome also
might fail if you try to run WebRTC from html launched from local file system
The workaround for this is to launch with
--allow-file-access-from-files parameter
(Something like this on windows: "C:\Program
Files (x86)\Google\Chrome\Application\chrome.exe"
--allow-file-access-from-files C:\path\softphone.html)
·
Also test your browser
webrtc capabilities from here and here
·
See this FAQ if you are using the webphone in a WebView or if you
plan to integrate it into an app
The webphone is capable to handle the situation when
calls are being connected without a microphone device. This is useful only if
the user needs to listen for some audio such as an IVR.
The only exception is if you use its WebRTC engine
with Firefox since Firefox requires the MediaStream to have a valid
MediaStreamTrack, but this is returned from getUserMedia() which fails on
Firefox if the user don't have a microphone with the following error:
WRTC, ERROR, InternalError: Cannot
create an offer with no local tracks, no offerToReceiveAudio/Video, and no
DataChannel.
This is a bug in Firefox already reported also by
others as you can see here and here.
This situation is handled automatically by the
webphone or you can force calls to always pass or always fail via the useaudiorecord
setting.
You might set the useaudiodevicerecord
parameter to false and the useaudiorecord parameter to 0 if you don’t have an audio recorder device
installed and don’t wish the webphone to check the device. You might also
change the volumein/volumeout
and mute/defmute settings. If your server
disconnects the calls on no RTP activity then you can set the sendrtponmuted parameter to tue.
Video calls are supported with the WebRTC engine.
You might need to set the video
parameter to 1 first to enable the video features.
Use the videocall
function to initiate a video call.
If you are using the webphone as a
SIP library with a custom skin (not via
the “softphone.html”),
then the video will be displayed in a div with id set to “video_container”, so
your html must have this element: <div
id="video_container"></div>.
You might also the setvideodisplaysize to adjust the display size.
You can use the getdevicelist / getdevice
/ setdevice
functions to manage the video devices.
You can also restrict the possible video codec’s with
the vcodec parameter and/or set a preferred codec with the prefvcodec parameter.
The webphone has support for the H.263, H.264, H.265,
VP8 and VP9 video codec’s, but codec availability is up to the browsers WebRTC
stack. H.264 and VP8 is supported by most browsers.
Other related parameters are the followings: displayvideodevice, video_bandwidth, video size parameters, videofacing.
Change the above parameters only if really required
for your use-case and after you already made a test with the default
parameters. The defaults are optimal for most use-cases.
The video call feature can be disabled by setting the
video parameter to 0 and the disableoptions parameter to 'VIDEO'.
Note:
The WebRTC engine is required for video to work (the webphone will try to
handle this automatically by switching to WebRTC on video request if it is
available).
Video calls might failback to a simple voice call if you try to use it
with an unsupported engine or if you don’t have a camera device or if video is
not supported by the peer or by the server/gateway. It should always work
between WebRTC endpoints if users has a camera device.
The video
call features are subject to support restrictions as described here and here.
If your main use case is video calls, then you should test with the demo
version before to get your license for production.
If you make a video call, the followings will happen
if the video is not supported or not accepted by the other end:
·
Webrtc to Webrtc: if the other
party doesn't have video, the call will connect just fine but there will be no
video
·
Webrtc to SIP: the call will
connect just fine but there will be no video
·
Webrtc to Webrtc: the other party
doesn't grant access to the video device: if you have camera device, and audio
and camera permission is requested, you can either grant permission for both,
or deny for both. You cannot share just audio or video device.
Note:
·
Video calls are not supported
with the NS and Java engine, however in this case the webphone can
automatically switch to WebRTC (on enduser video call request).
·
For the video to work, your SIP
server must have full support for H.264 and VP8 or it bypass the media routing
and forwards the SDP attributes correctly. The only exception is for webphone
to webphone calls when the video might be routed directly between the clients,
bypassing your server (if your server doesn’t force RTP relay and otherwise is
passing the SDP correctly)
·
Not all H.264 profiles are
accepted by the browsers (you should try with the baseline profile if fails)
·
If there is any issue with the
video calls from the webphone, you might test the video call capability of your
browser here and here.
The webphone can also fix incorrect video parameter
or remove video on failure.
You might adjust this with the fixvideo parameter. Possible values:
o -1: auto (default)
o 0: never
o 1: fix on fail
o 2: fix or remove on fail
o 3: remove on fail
o 4: always fix
o 5: always fix or remove
o 6: always remove
o 7: set to 0
o 8: always set to 0
What are the “best”
settings?
This is a question often
asked by our customers about how to optimize the webphone library for best call
quality. The answer is rather simple for this question:
The best settings are the
default settings. The default settings are optimized and should be preferred in
almost all use cases except if you have some uncommon needs. You should change
the default settings only if you have a good reason to do so. See the below FAQ
point for the possible changes for production usage. Related: best codec.
You might change the following
parameters when you switch to live:
·
Set the loglevel
parameter to 1 (off). The loglevel is
usually set to 5 (on) by default which is very helpful for debugging but will
consume more CPU/RAM. You can always switch back to 5 if you run into any issue
later where detailed logs can be useful.
·
Set the enablepresence
parameter to 0 if your server doesn’t have
SUBSCRIBE/NOTIFY support for presence or if you are not interested in this
feature (otherwise presence can generate a lot of extra signaling requests
using more CPU/RAM on both the client and server side)
·
Configure also STUN (stunserveraddress) and TURN (turnserveraddress) if you are using WebRTC. WebRTC
calls might work also without these settings, but, depending on the
circumstances and your environment, you can increase the success rate for the
calls using a STUN and TURN service (better NAT traversal).
Other then these, all
parameters comes with optimal defaults and you should change any settings only
if you have a strong reason.
How to achieve the best call quality
Since the webphone is
configured optimally by default and will auto-negotiate the best possible
settings by default, there is no much to tweak on the client side. However a
lot will depend on your server side configuration. Here are the key points:
·
If possible, avoid RTP routing on
the server side altogether. This will allow peer to peer direct media. If your
SIP trunk provider requires the RTP packets to be sent from your IP, then
configure your server with RTP routing only for outbound/inbound calls (and not
for user to user calls)
·
Use (enable) OPUS (and speex)
wideband if possible. Wideband codec has much better quality then narrowband
and even if your service providers(s) accepts only codec like G.729 or G.711,
this can be auto-negotiated and you should not force only these codec’s on your
server (allowing wideband for user to user calls)
·
If possible, avoid codec
conversion (transcoding). End to end G.711 has better quality then half-way
OPUS and then conversion to G.711
·
Follow best practices for VoIP
(make sure that you have enough and good quality bandwidth with minimal jitter
and no packet loss, make sure that your server resources are not over utilized
and the CPU is cable to handle RTP routing with minimal delay, etc)
When there is any call
quality problem with the webphone it is almost 100% that it is caused by some
external factor (such as poor network quality) or otherwise it can be fixed by
adjusting some of the webphone parameters.
Call quality is influenced
primarily by the followings:
·
Network conditions (QoS)
·
The engine used (NS, Java and
WebRTC tends to have the best quality, Flash has the worst quality)
·
Codec used to carry the media
(wideband has better quality)
·
AEC and denoise availability (mediaench)
·
Hardware: enough CPU power and
quality headset/microphone/speaker (try a headset, try on another device)
·
OS/Browser (drivers problems)
·
Settings (codec, jitter size,
AEC, etc)
·
Software problem or bug
(webphone/softswitch)
·
VoIP route (carrier/call
termination/voip service provider call quality)
If you have call quality
issues then the followings should be verified:
·
Make a test call with some other
simple third-party SIP softphone such as X-Lite. If call quality is
bad also with this, then the problem is not related to the webphone but it will
be some network/hardware/server/trunk issue.
·
Check your network quality:
upload speed, packet loss, delay and jitter here. (Other tools: a , b, c)
·
TURN usage: make sure that the
webphone is not behind a restrictive NAT or firewall to make sure that the call
can proceed normally on UDP and doesn't require TCP transport over TURN which
might result in lower quality then UDP especially on lower quality links
·
Check whether you have good call
quality using a third party softphone from the same location (try X-Lite for
example). If not, than the problem is not related to the webphone (continue to
look for server, termination gateway or bandwidth issues)
·
Make sure that the CPU load is
not near 100% when you are doing the tests (on multi-core systems none of the
cores should be near 100% utilization)
·
Make sure that you have enough bandwidth/QoS for the codec that
you are using (G.729 requires around 24 kbits. G.711 requires around 80 kbits.
Opus requires around 20-50 kbits. However the overall bandwidth is rarely the
problem and you should check if you have these minimums constantly, with less
packet loss then 2% and no big variations in roundtrip delays)
·
Change the codec (disable/enabled
codec’s with the codec and/or prefcodec
parameter)
·
Try to set only one single codec (such as PCMU) to make sure that the problem is not
caused by poor server side handling of the automatically selected codec
·
If the audio quality is wrong at
the peer side only then make sure that you are using a good quality microphone
(try also from another device) and make sure that the RTP packets are actually
received correctly to the other side (do a network capture on the other side to
rule out network issues for upload –internet connections are usually better for
downloads then for uploads)
·
Deploy the mediaench module (for
AEC and denoise). Make sure that the native dll/so/other files can be
actually downloaded from your Web server (enable their mime types if you can’t download these files by using
their full URI in your browser)
·
Try to disable the audio
enhancements. Set the following parameters to 0:
aec, aec2,
agc, denoise
·
Set the usecommdevice
parameter to 0
·
Set the volume in the
OS settings to 50% (or to other “normal” level, not near 100%)
·
If you are on Linux, try to
change your audio driver (from oss to alsa or others)
·
If you are using Windows, check
if you are not affected by high
DPC latency
·
If you are using the webphone as
a JavaScript WebRTC SIP library, then it might happen that the webphone will
chose to use our WebRTC-SIP gateway to handle your traffic. Our gateways are
located in US and Germany and if you are fare from these locations (Asia,
Australia, South America) then you might have too much delay. There are many
ways to solve this: webrtc solutions for web phone
·
Check the webphone logs (Check
audio and RTP related log entries. Also check the statistics after call
disconnect by searching for “EVENT, call details”)
·
Perform a network trace (With Wireshark for example; Filter for SIP and RTP. Check missing
or duplicated packets.)
The remote party hear
itself back (echo)
You can fine-tune AEC (acoustic echo cancellation)
with the aec, aec2, agc and denoise parameters.
Echo is generated by some devices/circumstances when
the output audio signal (from the speaker) arrives back to the input signal
(microphone). This usually happens only if you use a loudspeaker (and not with
headsets).
Please note that acoustic echo cancellation is not an
exact science and its success rate depends on many factors such as device, OS
version, browser, audio chip, audio driver, VoIP engine, environment, network
delay, headset/speaker/microphone quality, codec and others.
The webphone is capable to remove more than 90% of
the echo for more than 90% of the calls. There are some circumstances
(depending on the factors listed above) when echo cannot be detected correctly
and it is left in the voice signal.
When using the WebRTC, the webphone cannot influence
the media processing and thus can’t do any additional AEC (but it can force the
browser to apply AEC and AEC in this case is done by the browser internal
WebRTC media stack).
You hear yourself
back (echo)
In this case the echo is generated by the other end
and there is little to do with it on the webphone side.
Make sure that the other party uses an AEC capable
SIP client or device.
1.
Review your server NAT related
settings
2.
Make sur that your audio device
is connected and working correctly. If you have multiple devices, make sure
that the correct one is selected
3.
Set the “setfinalcodec” parameter
to 0 (especially if you are using Asterisk or OpenSIPS)
4.
If you are running the webphone
on the same local LAN with your SIP server, try to set the “stunserveraddress”
and “turnserveraddress” to “NULL”. (Sometimes this can be used also over the
public internet to avoid STUN and TURN related issues)
5.
Check stun and turn settings
(might be used for WebRTC if your server is not on the public internet, doesn’t
route the RTP or you need peer to peer media routing)
6.
Set use_fast_stun, use_fast_ice and use_rport to 0 (especially if you are using SIP aware
routers). If these don’t help, set them to 2.
7.
Set the enableearlyreinvite
parameter to 0.
8.
Check this FAQ if you are using Asterisk
9.
If you are using Mizu VoIP
server, set the RTP routing to “always” for the user(s)
10.
Make sure that you have enabled
all codec’s
11.
Make a test call with only one
codec enabled (this will solve codec negotiation issues if any)
12.
Check the next section if there
is any audio open related issues in the log (Audio device cannot be opened)
13.
Change the VoIP engine (switch to
NS if you have used WebRTC before or inverse. This can be enforced with the
enginepriority… settings)
14.
If you still have one side audio,
please make a test with any other softphone from the same PC. If that works,
then contact our support with a detailed log (set the” loglevel” parameter to 5
for this)
First of all, make sure that
you have a working audio device (and driver).
If you can’t hear audio, and
you can see audio related errors in the logs (with the loglevel parameter set
to 5), then make sure that your system has a suitable audio device capable for
full duplex playback and recording with the following format:
PCM SIGNED 8000.0 Hz (8 kHz) 16 bit mono (2 bytes/frame) in little-endian
If you have multiple sound
drivers then make sure that the system default is workable or set the device
explicitly from the webphone (with the “Audio” button from the default user
interface or using the “devicepopup()” function call from java-script)
To make sure that it is a
local PC related issue, please try the webphone also from some other PC.
If you are using Windows 10, make sure that microphone access is not blocked.
You might also try to
disable the wideband codec’s (set the codec parameter explicitly to a
narrowband codec or set the following parameters to 0 or 1: use_opuswb,
use_opusuwb, use_opusswb, use_speexwb, use_speexuwb).
Another source for this
problem can be if your sound device doesn’t support full duplex audio (some
wrong Linux drivers has this problem). In this case you might try to disable
the ringtone (set the “playring” parameter to 0 and check if this will solve
the problem).
Some linux audio drivers
allow only one audio stream to be opened which might cause audio issues in some
circumstances. Workaround: change audio driver from oss to alsa or inverse.
Change the JVM (Open JRE vs Oracle JRE) if you are using the Java engine;
Change browser if you are using the JS API.
If these don’t help, you
might set the “cancloseaudioline” parameter to 3 and/or the
"singleaudiostream” to 5.
How to change the sounds?
You can change the sounds by just replacing the audio
files.
Make sure to change the files in both the native and
the sound folders.
For example to change the ring tone, replace the
followings:
·
\sound\rtc_ringtone.wav
·
\sound\rtc_ringbacktone.wav
·
\native\ring.wav
Also set the ringtone parameter to
“ring.wav” (otherwise the NS and Java engines might use their built-in ringtone
instead of the ring.wav file)
The sound files should be standard 8 kHz 16 bit mono
PCM files (128 kbits - 15 kb/sec).
To disable ringtones, sent the playring parameter to 0 (disable
all) or 1 (disable ringback). Default is 2 which means enable all.
Other ringtone related settings: volumering, ringtimeout, beeponincoming.
Depending on your server
configuration, you might not have ringback tone or early media on call connect.
There are a few parameters that can be used in this situation:
·
set the “changesptoring”
parameter to 3
·
set the “natopenpackets”
parameter to 10
·
set the “earlymedia” parameter to
3
·
change the “use_fast_stun”
parameter (try with 0 or 2 or 4)
·
set the “nostopring” parameter to
1
·
set the “ringincall” parameter to
2
One of these should solve the
problem.
This might be displayed in rare
circumstances if your try to use the webphone with a local SIP server (SIP
server with private IP) and no any other engines are available in your
environment. The problem can be fixed with local WebRTC capabilities (built in
your server or by a WebRTC-SIP gateway.
In these circumstances (for example
running on Android with local SIP server), the webphone might not find any
suitable engine because of the following reasons:
-the NS engine is not available on
Android and iOS
-Java applets are not supported by your
browser
-the webphone also can’t use our WebRTC
gateway, since your SIP server is on local LAN (it could use our gateway if
your SIP server would be on a public IP)
-also you haven’t configured any local
WebRTC server (with the “webrtcserveraddress” parameter)
If any of the above conditions would be
false, then the webphone would run with no issues.
If this is only a test environment and
later you plan to use a SIP server with public IP, then the problem will be
resolved automatically and for now I recommend to use some other environment
for test.
If your final production environment
will be similar, then the followings can solve the problem:
-configure the webphone “webrtcserveraddress”
parameter to point to your server websocket listener (if your server has WebRTC
capabilities)
-alternatively you can use a separate
WebRTC-SIP gateway (any third party solution is fine such as doubango or janus
our our MRTC)
You can find more details about this in
the “How to
handle WebRTC” and “How to configure
WebRTC with my WebRTC server” FAQ points.
Make sure that your softswitch has
support for IM and it is enabled. The webphone is using the MESSAGE protocol
for this from the SIP SIMPLE protocol suite as described in RFC
3428.
Most old Asterisk installations might
not have support for this by default.
You might use Kamailio for this purpose or
any other softswitch
(most of them has support for RFC 3428).
For new versions of Asterisk based SIP
servers you need to properly configure SIP MESSAGE routing
in order for IM to work.
If subsequent chat messages are not
sent reliably, set the “separatechatdiag” parameter to 1.
In case if you are using the softphone
user interface (softphone.html) then you can disable chat by setting the textmessaging parameter to 0. (Alternatively you might use the disableoptions parameter).
Presence is implemented as standard SIP
PUBLISH/SUBSCRIBE/NOTIFY so your SIP server must support RFC
3265 and RFC
3856 in order for this to work.
For Asterisk based servers you can find
configuration details here and here.
To be able to receive calls,
the webphone must be registered to your server by clicking on the “Connect”
button on the user interface (or in case if you don’t display the webphone GUI
than you can use the “register” parameter with supplied username and password,
or via the register() JavaScript SIP API)
Once the webphone is registered, the
server should be able to send incoming calls to it.
To find out the reason of failed
incoming calls, check the followings:
1.
Check if the call arrives to your
SIP server (if not, then the problem has nothing to do with the webphone)
2.
Check if your server is sending
the INVITE to the proper IP:port (from where it received the latest valid
REGISTER from the webphone)
If your server doesn’t route the call or routes to
wrong address, check the followings:
a.
Increase your server log level,
so you can see the SIP signaling messages in the logs
b.
Check any error in your server
log near the call setup or near the previous registration coming from the
webphone
c.
NAT: if your browser webphone is
behind NAT, check if your server can handle NAT’s properly (via rport and other
settings). As a workaround you might try to start the webphone with
use_fast_stun parameter set to 0 and if still not works then try it with 2 or
4.
d.
Call fork: if you are registered
from multiple locations with the same credentials then your server must be able
to support call fork to ring on all devices. Otherwise make sure to use the
same credentials only from one location and one protocol (don’t mismatch SIP
and WebRTC logins)
3.
Check if the INVITE arrives to the
webphone and the webphone process it normally
a.
Search for “INVITE SIP” in the webphone log (if not found, then check if the webphone is
actually connected)
b.
Check any error in the webphone
log near the incoming INVITE
c.
Make sure that autoignore or DND
(do not disturb) are not set
If the calls are still
not coming, send a detailed log from the webphone (set the loglevel parameter
to 5) and also from the caller (your server or remote SIP client)
This depends on the
circumstances and there is no such thing as the "best codec". All
commonly used codec's present in the webphone are well tested and suitable for
IP calls with optimized priority order by default, regarding to environment
(client device, bandwidth, server capabilities).
This means that usually
you don’t need to change any codec related settings except if you have some special requirement.
Between webphone users
(or other IP to IP calls) you should prefer wideband codec's (this is why you
just always leave the opus and speex wideband and ultra wideband
with the highest priority if you have calls between your VoIP users. These will
be picked for IP to IP calls and simply omitted for IP to PSTN calls).
Otherwise G.729 provides
both good quality and low bandwidth if this codec is available for you.
G.711 (PCMU/PCMA) is always supported and they offer good
call quality using some more bandwidth then G.729.
The other available
codec’s are iLBC and GSM. These offers a good compromise between
quality and bandwidth usage if the above mentioned opus and G.729 is not
supported by your server or the other peer.
The WebRTC engine will
use the browser media stack capabilities. Most
browsers has support for at least G.711 (PCMU/PCMA) and OPUS, so you always
have a narrowband codec which should work with all trunks (G.711) and a
wideband codec for the best quality (OPUS). Other codec’s might also work with
automatic transcoding. By default the WebRTC engine will negotiate the best possible
codec.
To calculate the bandwidth needed, you can use this tool. You might also check this blog entry: Codec misunderstandings
With the webphone you
don’t need to change the codec settings except if you have some special
requirement. With the default settings the webphone is already optimized and
will always choose and negotiate the “best” available codec.
Not all the listed codec’s are
supported by all engines. WebRTC codec support is up to the browser.
The webphone will always automatically
choose the best available codec based on your settings, local capabilities,
peer capabilities and other circumstances (networking, CPU type, etc).
Audio codec support per
engine:
·
PCMU (G.711/µ-law): WebRTC, NS,
Java, Flash
·
PCMA (G.711/A-law): WebRTC, NS,
Java, Flash
·
G.729: NS, Java, Flash
·
GSM: NS, Java
·
iLBC: NS, Java
·
iSAC: WebRTC
·
SPEEX: NS, Java (both narrowband
and wideband)
·
OPUS: WebRTC, NS, Java (both
narrowband and wideband)
If you are using the NS
or Java engine, then set the rtpstat parameter to -1 or to a positive value to
receive RTPSTAT notifications by the onEvent
callback.
More details here.
In case if you are using
the WebRTC engine then you can capture the statistics via the RTCPeerConnection object which is exposed by the webphone_api.getrtcpeerconnection()
function.
From there you can use the RTCRtpStreamStats object to get the statistics.
If you don' wish to use
the RTCRtpStreamStats directly, then there are also libraries for this such as webrtcmetrics.
[Optimizations for VoIP callcenter]
The webphone is a favorite VoIP client for
callcenters as it can be easily integrated with any frontend, backend or CRM
and it can be used for both inbound and outbound campaigns. The integration
usually consists of database lookup for caller/callee details on
incoming/outgoing calls so the agent can see all the details about the
customer.
There are multiple ways to implement such kind of
database/CRM/API lookups:
o
From JavaScript catch the call
init from the onCallStateChange callback (on event = 'setup') and load the required data by an AJAX
call to your backend
o
Via the “scurl_displaypeerdetails”: implement a HTTP API on your server which will
return the peer details and set the scurl_displaypeerdetails webphone setting
to point to this API URL
o
If your backend has VoIP client
integration capabilities, then just implement its specification. For example
here is a tutorial about integrating the webphone with salesfoce
There are many other things what you can do for a
better integration, such as processing cdr records or recording the calls however most of these can be easily controlled by the webphone parameters or implemented via the API. You can also easily implement any kind of call
disposition after your needs integrated with your user interface and/or pushed
to your server with a simple AJAX call.
We recommend use the NS and/or the Java VoIP engine in call-centers since these provides native call
processing, connecting directly to your SIP server without the need of any
extra layer such as WebRTC. More details here.
How to store the call details in my database?
The webphone is a client side mostly javascript
solution running in the client browsers so it can't touch directly any server
side database.
However, you can easily send the call details from
the webphone to the server (web service) and from there insert the required
fields to your database with a simple script.
(Please note that you will need to write a small
script for this on the server side to handle the HTTP AJAX request from the
webphone or just extend your existing web service if any with one more API for
this. You can do this in your preferred language such as .PHP, .NET, nodejs or
anything what you are using on the server side)
There is multiple ways to catch the call details and
send it to your server (use any ONE of these):
·
Set an onCdr callback function which will be triggered after each
call and make an AJAX request from there to your server with the call details.
·
You could also use the getlastcalldetails function (call this function after a call to get the
CDR -call details).
·
Set the scurl_onoutcalldisconnected
and scurl_onincalldisconnected
webphone parameters to your server side script API URL and the webphone will
automatically submit the call details after each call (you might use this if
you don't have any JavaScript knowledge to implement a custom ajax submit
mentioned in the above points).
·
All SIP servers has CDR
reporting/storage features and you might use that instead of the webphone to
get the call details.
In this case there is nothing to do with the
webphone, you can query the call details from your SIP server via some HTTP API
or from its database using SQL.
How the conference works?
The webphone has built-in support for multiple
conference solutions and it’s behavior can be set changed with the conferencetype parameter:
·
Conference via built-in
conference mixer (NS and Java client side RTP mixer, so the conference will
work, even if your server doesn’t have conference support)
·
Conference via standard SIP 3-way
calling (NS and Java engines and basic support also for WebRTC)
·
There is no built-in conference
support in the WebRTC protocol, but the webphone is capable to create
conference calls also while using WebRTC with the following methods:
o
auto switch to NS or Java (When
any of these are available, then conferencing will work with any peer
regardless of your server capabilities)
o
using server or gateway side DTMF
controlled conference functionality.
o
using server or gateway side
conference room (When this is supported by the server or gateway, then it is
transparently integrated. Note: conferencing might be created only between
Webphone instances in this case and might not succeed for SIP or PSTN peers.
Hangup per line is not supported in this mode)
o
Note: Mizutech doesn’t provide
direct support for WebRTC conference rooms (especially if your SIP server
doesn’t support SIP MESSAGE and SIP REFER properly or if there is no available
server-side WebRTC conference room support). See the “known limitations” for
more details.
·
Server side conferencing is also
available in all circumstances (via DTMF/IVR/conference rooms as supported by
your server)
When conferencing is available, you can trigger a
conference call in the following ways:
·
If you are using the softphone
user interface: use the conference menu option in the main menu or the add
people option while in call
·
If you are using the webphone as
a JS SIP library: use the conference
API function
The “P2P” term is misleading sometimes and it can
have the following meanings:
·
Peer to peer calls: refers to the
ability to call other SIP endpoint directly without the need for a SIP server.
This is fully supported by the webphone. You just need to call to the other
endpoint full URI (such as sip:user@ip:port). Note that the main purpose of a SIP registrar is to allow calls
using just the username part (extension number) without the need for the
enduser to know the target network address and it allows calls also to other
networks (via any NAT). Using the full URI can be uncomfortable for endusers
thus we recommend to use the webphone with a SIP server to ease the usage.
·
Peer to peer media: direct media
routing is important to minimize the audio delay and to free up your server
side resources. This is fully supported by the webphone and used whenever
possible. Note that this also depends on server side capabilities (SIP servers
can act as a B2B relay, removing all the necessary information from the
signaling that would be required to setup a direct media stream between peers
thus forcing RTP routing via the server media relay)
·
Sometimes it might refer to peer
to peer encryption (or end to end E2E encryption) which means that the server
(if used) is a passive party from the encryption point of view and is unable to
decrypt the streams between the endpoints (just forwards the stream if needed).
End to end encryption is supported by the webphone and it is applied whenever
direct media routing is possible. The webphone also has support for peer to
peer encrypted media with direct streaming (this is done via ICE techniques
with automatic failback to routing via server if a direct path can’t be found)
·
Server assisted phone to phone
calls. This means that both endpoints will be called by the server and once
connected, the server interconnects the 2 endpoint. It can be useful when the
client device doesn’t have internet connection or doesn’t have any platform to
enable VoIP, such as an old dumb phone. Exactly for this concept we refer with
the P2P
engine.
·
Peer-to-peer distributed
application architecture: this has nothing to do with the webphone
capabilities. The SIP protocol itself is a client-server protocol and doesn’t
define any automatic internetworking capabilities, however if you wish, you can
use an external library to construct a peer-to-peer network of SIP nodes. This
is usually worthless as for signaling you can use a thin proxy capable to
handle millions of users and for media we already have capabilities to
establish direct connection between peers (STUN, ICE). There is no standard way
for distributed SIP network architecture (you can implement any architecture
after your needs which is supported by all your network elements).
In order for the webphone to be capable sending SMS
messages, your softswitch need SMS support.
Usually this is done by using SMS gateway services
such as clickatell or a directly
connected SMS capable phone device.
Note: such kind of services can’t be used directly from the
webphone, because you need to implement billing on your SIP server. So the
messages have to be sent to your SIP server first and from there it can be
forwarded to a SMS gateway.
From webphone to server the SMS can be sent via one
of the following methods:
·
via HTTP API: just configure your
server SMS API via the “sms” webphone parameter (you can set this in the
webphone_config.js file).
For example: sms:‘https://myserver.com/api/function=sms&authkey=5829157329773&authid=4753584&authmd5=xxx&anum=MYNUMBER&bnum=TARGETMOBILE&txt=TEXT’
(upper case keywords will be replaced automatically by the webphone).
·
via chat/IM: instead of calling
an API, the SMS messages can be also carrier via SIP MESSAGE (RFC
3428). In this case your server have
to check the destination number and if that is a mobile number then it should
forward the message as SMS instead of chat. You can also set the textmessaging webphone
parameter to 5 which will insert a X-Sms: Yes header (the server might check this
header to know when char to SMS conversion is required)
If you are using the mizu softswitch with the
webphone, then the sms functionality will be automatically preconfigured in
your webphone build if you have configured sms on your server (via the smsurl global config option or by adding separate
SMS gateways in “Users and devices”)
If your server has sms support and you have
configured in the webphone as described above, then you can send SMS from the
webphone in the following ways:
·
if you are using the softphone
skin: send SMS as you were sending normal chat messages
·
if you are using the webphone as
a JavaScript library: use the sendsms API
Receiving SMS messages:
The standard way for receiving messages in a VoIP network
is via the SIP MESSAGE protocol, thus your SIP server will just need to convert
SMS message to a SIP chat message and deliver it as simple IM.
If this feature is not supported by your server, then
the webphone can also poll an API for new incoming SMS messages, although this
should not be used in large networks since this kind of polling is not very
efficient.
Another way to implement incoming SMS is to use push
notification, however this has nothing to do with the webphone SIP stack and it
should be implemented separately.
Presence can be used to publish your webphone state
for others or to learn about the state of the peer devices (online, offline,
etc).
You can use the presence functionality for this if
your server has support for the standard presence SUBSCRIBE/NOTIFY.
Set the enablepresence parameter to
See the checkpresence/setpresencestatus/onPresenceStateChange functions for the details
In case if you wish to publish or learn also about
peers call state, then you might use the BLF (busy lamp field) features
(instead or in addition to presence).
Set the enableblf
parameter to 2 then pass the userlist (list of extensions) to be monitored
either by the blfuserlist parameter or with
the checkblf(userlist) API.
Then just use the onBLFStateChage callback to watch for the subscribed extensions call
status changes.
Call Forward vs
Call Transfer
Here are the main differences between SIP call
forward and transfer:
Call forward:
·
In the webphone you can forward
calls by using the callforwardonbusy, callforwardonnoanswer, callforwardalways parameters or the forward()
API
·
It is like HTTP redirect
·
It is done by sending a 301 or
302 (moved) disconnect code to the caller (specifying the new target)
·
Can be initiated by the called
party only
·
Not all SIP servers has support
for this and some servers explicitly disables this functionality to avoid user
confusion
·
Can be initiated only before call
connect (as a response for the incoming INVITE)
Call transfer:
·
In the webphone you can forward
calls by using the calltransferalways parameter or the transfer()
API
·
It is done by the SIP REFER
method (sending the new target by the Refer-To SIP header)
·
Can be configured with the transfertype parameter
·
Unattended transfer means a
simple REFER request and the other party should call the new target
·
Attended transfer means
consultation call first (supervised transfer)
·
Can be initiated by both the
caller and called party
·
Not all servers has support for SIP
REFER (check your server specification and settings)
·
Can be initiated only after call
connect
The transfer mode can be
set with the transfertype parameter.
The call transfer is
handled with the SIP REFER method as described in RFC
3515, RFC
5589 and RFC
6665.
With unattended
transfer the transfer will be executed immediately once you call the transfer function (blind transfer; only a SIP REFER is sent).
With attended transfer
(transfertype 5) you can use the following call-flow, supposing that you are
working at A (webphone) side and wish to transfer B (the original call) to C
(the transfer target):
1.
A call B (outgoing) or B call to
A (incoming)
A
speaking with B
2.
Call transfer(C)
The
call between A and B will be put on hold by A
A
will call to C and connect (consultation call; if call fails, then the call
between A and C will be un-hold automatically)
A
speaking with C
3.
The actual call transfer will be
initiated when A disconnect the call (hangup())
REFER
message will be sent to B (which tells to B to call C. usually by automatically
replacing the A-B call with A-C)
4.
After transfer events:
Transfer
related notifications (SIP NOTIFY) can be sent between the endpoints once the
call transfer is initiated, reporting the transfer state.
o
If transfer fails (B can’t call
C) the call between A and B will be will be un-hold automatically (if server
sends proper notifications)
o
If the transfer succeeds (B
called C) the call between A and B will be will be disconnected automatically
(if server sends proper notifications)
o
If the server doesn’t support
NOTIFY, then the call can be un-hold or disconnected from the API (hold(false), hangup())
5.
B speaking with C at this point
if the transfer was successful
If you use call transfer,
you will have multiple lines and you might handle the lines explicitly as
described here.
The softphone skin (in
case if you are using the softphone.html) call transfer user interface depends
on the transfertype and transferpopup parameters.
If the transfertype is
set to attended and the transferpopup is set to -1 or 2 then once the call was
initiated to the transfer target (consultation call) an additional transfer
control popup will appear with the following buttons:
o
Transfer: will transfer the call
when clicked and will hangup the original call (otherwise the call will be
transferred only at consultation call disconnect)
o
Revert: close the popup and do
nothing (the call will be transferred only at consultation call disconnect)
o
Hangup: will disconnect the
consultation call and will un-hold the original call
Create custom attended
transfer
In case if attended
transfer doesn't work or if you wish to do it in a different way then the
webphone does, you can also perform attended transfer from your code while the
webphone transfertype is set unattended
transfer (1, 6 or 7).
In this case just
initiate the consultation call yourself (using the call
function) and then use the transfer function
(with unattended transfer) whenever you wish the actual call transfer to happen
(usually after hangup with the target).
Step-by-step example:
1.
Set the transfertype
parameter to 7 and do the followings on
transfer.
2.
A is the webphone, B is the
original caller/called and C is the transfer target.
3.
Put the old line with B on hold: hold(true)
4.
Call the new number for the
consultation call: call('C')
5.
If the consultation call to C
fails, then reload the call with B: hold(false)
6.
Watch if any peers disconnects
from the onCallStateChange() callback. If
peer B disconnects, then there is no need for any transfer anymore. If peer C
disconnect (after the consultation call) , then do the transfer right away
7.
Transfer the B to C by using the transfer('C') function once the consultation call
with C ends
8.
Disconnect from C using the hangup() function (if not already disconnected.
You might disconnect before to make the transfer but in that case transfer with
replaces will not work, so a new call will be initiated to C instead of reusing
the same old call-leg)
Since you are operating
with multiple lines here, you might need to use also the setline(x) function before the above function call
to specify the exact line.
See the How to manage multiple lines FAQ point for the details about this topic.
Transfer related
parameters
Note: not all parameters
are applied for all engines.
transfertype
Specify
transfer mode for native SIP.
-1=default
transfer type [default; same as 6]
0=call
transfer is disabled
1=transfer
immediately and disconnect with the A user when the Transf button is pressed
and the number entered (unattended/blind transfer)
2=transfer
the call only when the second party is disconnected (attended transfer)
3=transfer
the call when the VoIP phone is disconnected from the second party (attended
transfer)
4=transfer
the call when any party is disconnected except when the original caller was
initiated the disconnect (attended transfer)
5=transfer
the call when the VoIP phone is disconnected from the second party. Put the
caller on hold during the call transfer (standard attended transfer)
6=transfer
the call immediately with hold and watch for notifications (unattended
transfer)
7=transfer
with no hold and no disconnect (simplest unattended transfer)
8=transfer
with conference (will put the parties to conference on transfer; will mute or
hold the old party by default)
Note:
o Unattended means simple immediate transfer (just a
REFER message sent)
o Attended transfer means that there will be a consultation
call first
o It is also possible to simulate an attended transfer by
initiating a simple call to the transfer target and on hangup an unattended
call-transfer (transfertype 1)
o If you have any incompatibility issue, then set to 7
(unattended is the simplest way to transfer a call and all sip server and
device should support it correctly)
transfwithreplace
Specify
if replace should be used with transfer requests, so the old call (dialog) is
not disconnected but just replaced.
This way
the transferee and the transfer-target parties are not disconnected, just the
other party is changed at runtime.
The
feature is implemented by adding a Replaces= for the Contact header in the
REFER request as described in RFC 5589 and RFC 5359.
The
transferee (the party which receives the REFER transfer request) or the SIP
server must be able to handle replaces for this to work.
Possible
values:
-1: auto
/ default (if server/peer has replaces support and we are connected with the
transfer target)
0: no
1: yes
replacetype
Specify
how to handle incoming call transfer with replaces requests (How to handle the
Replaces= Contact tag in incoming REFER requests)
-1: auto
(defaults to 1)
0:
disable
1:
standard (sending the Replaces header in the new call INVITE request as described
in RFC 3891)
2: in
place (might be useful with servers without replaces support; not supported by
the WebRTC engine)
transferpopup
Specify
softphone skin attended transfer behavior.
-1: auto
0: hold
current line and call the new number (might transfer at call disconnect only)
1: call
the new number first (without holding the old line first; the call will be
transferred at disconnect)
2: with
additional popup (possibility to transfer, hangup or revert)
defmute
Default
mute direction:
0: both
1: mute
out (speakers)
2: mute
in (microphone)
3: both
4: both
5:
disable mute
Default:
0 or 2
discontransfer
[For the
NS and Java engines only. For WebRTC only the 0/non-0 is considered]
Specify
if line should disconnect after transfer
-1=auto
[default; disconnect if transfertype is 1]
0=never
1=on C
party connected status
2=on
timeout
3=on
connected or timeout
4=on ok
for refer
disconincomingrefer
[For the
NS and Java engines only. Ignored for the WebRTC and Flash engines]
Specify
if line should disconnect after transfer
-1=auto
[default]
0=no
1= yes
allowreplace
[For the
NS and Java engines only. Ignored for the WebRTC and Flash engines]
Allow
incoming replace requests.
0=no
1=yes and
always disconnect old ep
2=yes and
don't disconnect if in transfer (default)
3=yes but
never disconnect old ep
inversetransfer
[For the
NS and Java engines only. Ignored for the WebRTC and Flash engines]
Specify
inverse attended transfer.
0: no.
The REFER will be sent to the ep for which the transfer function was called.
This is the standard behavior. [default]
1: yes.
The REFER will be sent to the ep for which the hangup function was called.
Might be used only if the original ep (for which the transfer was called)
doesn't support transfer (REFER sip message).
transferdelay
[For the
NS and Java engines only. Ignored for the WebRTC and Flash engines]
Milliseconds
to wait before sending REFER/INVITE while in transfer.
Default
value is 400.
newdialogforrefer
[For the
NS and Java engines only. Ignored for the WebRTC and Flash engines]
Specify
if the REFER have to be sent in a new dialog (for compatibility reasons).
0: no
[default; after SIP standards]
1: yes,
with no to tag
autohold
Specify
if other lines will be put on hold on new call.
0=no
[default]
1=on incoming
call
2=on
outgoing call
3=on
incoming and outgoing calls
4=on line
change
5=on
outgoing call and on line change (like 2+4)
6=on any
call and on line change (like 3+4)
automute
Specify
if other lines will be muted on new call.
0=no
[default]
1=on incoming
call
2=on
outgoing call
3=on
incoming and outgoing calls
4=on line
change
5=on
outgoing call and on line change (like 2+4)
6=on any
call and on line change (like 3+4)
holdtype
Specify
how the call hold function should work:
-2=no
(will ignore hold requests)
-1=auto/default
(defaults to 2)
0=no
1=not
used
2=hold
(standard hold by sending “a=sendonly”)
3=other
party hold (will send “a=recvonly”)
4=both in
hold (will send “a=inactive”)
holdontransfer
(int)
Specify
if initial line should be put on hold on transfer.
-1=auto
(default; means 3 for transfertype 5 and 6, otherwise 0)
0=no
1=yes,
hold before transfer
2=yes,
hold before transfer and reload if needed (on transfer failure)
3=yes,
hold on successful transfer init (OK for REFER received or attended call
progress or success received; transferred call might not be initiated/connected
yet). Will reload if needed (on transfer failure).
unholdontransfer
(int)
Unhold
the line just before the actual transfer if it was holded and the transfer is
made with replaces (to prevent keeping the endpoint in hold)
-1=auto
(default; usually same like 1)
0=no
1=yes
with replaces if there was hold before
2=yes
always
How to auto start / auto register
Library initialization
The webphone library will auto initialize itself by
default at page load.
You might use the autostart
parameter to modify this behavior or use the start()
API.
Softphone skin auto login
In case if you are using the softphone.html and the
SIP account parameters (serveraddress/username/password/others if needed) have
been preconfigured or already entered by the user, then the softphone skin will
not stop at the login screen.
You might use the autologin
parameter to modify this behavior.
Auto register
The webphone will automatically register to the SIP
server upon startup if the SIP account parameters
(serveraddress/username/password/others if needed) have been preconfigured or
entered by the user.
You might use the register
parameter to modify this behavior or use the register()
API.
Other not so important related
parameters: appengine_startat (native engine launch), startsipstack (NS engine
specific).
See this FAQ point if the webphone doesn’t start
correctly.
Register vs Login vs Credentials
These terms might be also misleading especially for
user with no VoIP/SIP knowledge.
Register or registration provides a way for the SIP
clients to connect/login to the server so the server will learn the client
address and will be able to route calls and other message to it. It is
implemented by sending a REGISTER message by the SIP signaling. The server
might or might not challenge the request with an authentication request (in
this case the client will send a second REGISTER with a hash of its
credentials). On credentials we refer to the sip username/password.
However:
·
Register is optional and is not
really needed if your client will make only outbound calls (not used to accept
calls or chat)
·
You can configure your server to
not require registrations (actually most server doesn’t require it by default,
however in some servers the default configuration is to not allow calls if
there was no previous successful registration)
·
For the webphone you can set the
“register” parameter to 0 to skip registration (so the webphone will not send
REGISTER requests)
·
Disabling registration is not a
security treat since the server will do the same authentication for each call
as it does for registrations (so the clients will not be able to make calls if
their credentials are incorrect)
·
You can also configure your
server to allow blind registrations. This means that the client might send the
REGISTER with any credentials (any username/password) and it will be
unconditionally accepted
·
You can also configure your
server to allow blind calls. This means that the client might send the INVITE
with any credentials (any username/password) and it will be unconditionally
accepted (the call will be routed)
·
If your server accepts blind
registrations and calls then you can set the webphone password parameter to any
value since it will not be checked or used anyway. (You can set it to
“nopassword” as a special value to hide it from settings and login forms)
·
There are situations when even
the username doesn’t matter (if you wish to make only unconditional outbound
calls or calls to ivr). However you must also set the username parameter to
some value or allow the user to enter something since it is required for the
SIP messages. You might set it to “Anonymous” in this case.
If your users will have to login to your webportal,
then we recommend using the same username/password for WEB and SIP. You might
need to do some integration work between your web service and VoIP service for
this, for example synchronize the users or use a single source (database table
or configuration file) for both your web server and SIP server.
Sometime you might use a separate username/password
combination on your website then on your SIP server. In this case you can
auto-provision the webphone with the sip credentials if the user is already
logged in on your website to avoid typing a different username/password. This
can be implemented multiple ways:
·
by dynamically generating the
webphone settings from a server script (set the username/password from the
server since there you already know the signed in user details and you can grab
the SIP credentials from your softswitch database)
·
implement a custom API which
returns the sip credentials and set it’s URI as the “scurl_setparameters”
parameter (webphone will call scurl_setparameters URI and wait for the
(key/value) parameters in response and once received it will start the
webphone)
·
handle it from JavaScript (use
the setparameter() API to set the username/password)
·
implement some alternative authentication
method on your SIP server (for example based a custom SIP header which you
might set from the web session using the setsipheader() API call)
Alternative authentication methods
This is a JavaScript SIP client, so it has support
for the standard SIP digest authentication (with SIP username/password).
However, you are not forced to use this.
If your VoIP server does not ask for authentication,
then you can just configure a random username/password (it will not be used
anyway) and/or you can use any other authentication as required by your
platform.
For example, you can use the dtmf
function to send PIN code as DTMF digits, use the setsipheader
function to pass any extra data with the signaling, add a tech prefix before
the called numbers or any other method.
SIP registration means connecting to your SIP server
and authenticating. From this procedure your SIP server will learn your
application address and can route incoming calls to your application (or other
sessions, such as chat, presence, voicemail, etc).
The SIP stack auto-start behavior can be altered with
the autostart setting or you can use the start function to launch the instance explicitly.
When started, the SIP stack by default (unless you
set the register parameter to 0) will automatically register to your
SIP server if you configured the SIP account details (serveraddress, username, password and any other parameters that might
be required such as the proxyaddress and sipusername).
Otherwise you might disable auto-start (autostart) and/or the auto register (register), pass the
above parameters dynamically from your code and use the start and/or the register
function to initiate the start/connect/register procedure.
Check this FAQ point if you wish to use multiple accounts in one webphone instance.
Check this FAQ point if you are having problems with connect/register.
How to find out
registration status
Depending on the settings, the webphone will automatically
register upon startup or you can explicitly connect to the server by calling
the register() API.
To find out whether the webphone is successfully
registered or not, you can use the isregistered()
API to query the status at any time.
You can also receive notifications about the
registration status via the followings callbacks:
·
onRegStateChange called on
register state change
·
onEvent called with display
type parameter when register fails with the message containing one of the
following text:
o
Connection lost
o
No network
o
Server address unreachable
o
No response from server
o
Server lost
o
Authentication failed
o
Rejected by server
o
Register rejected
o
Register expired
o
Register failed
In old versions you
can also use the getregfailreason function to find
the reason of a failed connect/register attempt.
You can receive the call disconnect
reason with the onCDR event (“reason”
parameter) or using the getlastcalldetails()
function.
There are endless possibilities why
a call can fail, the most common reasons are listed below.
The disconnect reasons are reported
in the following format: code text. (So you
have the text after a space)
Code:
Is a SIP disconnect
request or answer code including BYE, CANCEL or any SIP response code above
300.
If no disconnect
message were received or sent then the code is -1 or empty/not set.
Text:
The text is one of
the followings:
1.
local disconnect
reasons (listed below)
2.
disconnect
reason extracted from SIP Warning or Reason headers
3.
response text
extracted from the first line of SIP responses (textual representation of the response
code)
4.
textual
representation of the disconnect code
The local disconnect reasons can be one of the followings
(extra details might be appended and new disconnect texts might be added in the
future):
·
notaccepted
·
User
Hung Up
·
bye
received
·
cancel
received
·
authentication
failed
·
endpoint
destroy
·
no
response
·
call
setup timeout
·
ring
timeout
·
media
timeout
·
endpoint
timeout
·
tunneling
calltime limit
·
call
max timer expired
·
max
call time expired
·
max
speech time expired
·
not
acked connection expired
·
disconnect
on transfer
·
transferalways
·
transfer
timeout
·
transfer
fail
·
transfer
done
·
transfer
terminated
·
transfer
(other)
·
refer
received
·
cannot
start media
·
not
encrypted
·
srtp
fail
·
srtp
init fail
·
disc
resend
·
failed
media
·
forward
·
forwardonbusy
·
forwardonnoanswer
·
forwardalways
·
rejectbusy
·
rejectonphonebusy
·
call
rejected by peer
·
rejected
by the peer
·
rejected
·
autoreject
·
autoignore
·
ignored
The SIP disconnect codes (3xx, 4xx,
5xx, 6xx) are described in the SIP RFC.
With the getlastcalldetails()
function, “Disc By“ text, you can also get the party which was initiated the
disconnect.
This can be one of the followings:
·
0: unknown/not
set
·
1: local
webphone
·
2: remote peer
·
3:
undefined/timeout
You can also get the exact disconnect reason /
disconnect message from the SIP signaling using the getsipmessage()
function.
For example to extract the disconnect reason from the
last incoming message, you can use something like this:
webphone_api.getsipmessage(0,
0, function (sipmsg) {
var disconnectcode = "";
if(sipmsg.indexOf("BYE
") == 0) disconnectcode = "BYE";
else
if(sipmsg.indexOf("CANCEL ") == 0) disconnectcode =
"CANCEL";
else
if(sipmsg.indexOf("SIP/2.0 ") == 0)
{
sipmsg
= sipmsg.substring(sipmsg.indexOf(' ')+1);
sipmsg
= sipmsg.substring(0, sipmsg.indexOf(' '));
var
codenum = parseInt(sipmsg.trim(),10);
if(codenum
>= 300) disconnectcode = codenum.toString();
}
if(disconnectcode.length
> 0) console.log("The disconnect code is: "+disconnectcode);
});
For outgoing calls:
The Caller-ID (CLID/CLI/A number
display) is controlled by the server and the application at the peer side (be
it a VoIP softphone or a pstn/mobile phone).
You can use the following parameters
to influence the caller id display at the remote end:
·
username
(SIP user name / Extension number / User ID. This is used as both SIP username
and authentication username if sipusername is not set)
·
sipusername (Auth user name / Auth ID / PIN / Authorization name. If
this parameter is set, then the “sipusername” will be used for authentication
and the “username” parameter as the SIP user name and caller-id)
·
displayname
(SIP display name / Caller ID)
You might also set the showusername
parameter to 2 to show both the username and the caller-id input on the
softphone skin login page.
Some service providers will provide
you a globally routed telephone number (DID) which might be applied on the
server side or you might have to use it as the username parameter.
If you set all these parameters,
then it will be sent in the SIP signaling in the following way (see the
uppercase worlds):
INVITE
sip:called@sipdomain.com SIP/2.0
From: "DISPLAYNAME"
<sip:USERNAME@sipdomain.com>;tag=xyz
Contact:
"DISPLAYNAME"<sip:USERNAME@sipdomain.com>
Remote-Party-ID:
"DISPLAYNAME"
<sip:USERNAME@88.150.183.87>;party=calling;screen=yes;privacy=off
Authorization: Digest
username="SIPUSERNAME",realm="sipdomain.com" …
The WebRTC engine
will send the “Contact” URI with an invalid domain by default for outgoing
REGISTER/INVITE/etc requests as required by RFC 7118.
You might set the contactdomain webphone
parameter to 1 if your server expects its
valid domain for this.
Some VoIP server
will suppress the CLI if you are calling to pstn and the number is not a valid
DID number or the webphone account doesn’t have a valid DID number assigned
(You can buy DID numbers from various providers).
The CLI is usually
suppressed if you set the caller name to “Anonymous” (hide CLI).
If required by your
SIP server, you can also set a Caller Identity header as a “customsipheader”
parameter. (P-Preferred-Identity/P-Asserted-Identity/Identity-Info)
For incoming calls:
In case if you are using one of the
prebuilt skins:
For incoming calls the webphone will
use the caller username, name or display name to display the Caller ID. (SIP
From, Contact and Remote-Party-ID fields).
If you are using the API then you
can get the caller-id (caller number / caller username / CLI / caller
extension) by using one of the followings methods:
·
the onCallStateChange callback (you receive the caller name and display name at each call
state change in the peername/peerdisplayname variables)
·
the getcallerdisplayfull callback (detailed caller id on incoming calls)
·
the onCdr callback (caller details at the end
of the call)
·
the getlastcalldetails function (more details can be requested after the call)
·
the getsipheader function can be used to request any received SIP header
(such as the “From” or the “Remote-Party-ID” headers)
·
the getsipmessage function can be used to request the received SIP message in
raw text (such as the whole incoming INVITE message)
My server requires separate extension and
authentication username
Some SIP servers might require a
different user name and auth user name.
This means that for the webphone you
must set both the username and sipusername parameters
or if you are using the softphone skin then you must set both the Username
field on the login screen and the Caller-ID field in the settings.
From the softphone skin (softphone.html):
·
On the login
screen:
o set the “Server” field to your
server address (domain or IP:port)
o set the “Username” field to the
Authentication username (example: ‘1qu3iqt’) . This will be saved as the
“sipusername” parameter.
o set the “Password” field to the
Authentication Password (example: ‘xkclq7n’)
·
Go to the
Settings and set the “Caller ID” field to the Extension number (example: ‘04’).
This will be saved as the “username” parameter.
·
Then just login.
Via webphone parameters (configurable in the
webphone_config.js):
webphone_api.parameters
= {
serveraddress: '11.22.33.44', //your server domain:port or IP:port
sipusername:
'1qu3iqt', //Authentication
username (Auth ID)
username: '04', //Extension number (SIP
user name or Caller-ID)
password: 'xkclq7n', //Authentication
Password
loglevel: 5
//comma is not needed after the last parameter
};
You can configure also by passing
the above settings via the setparameter API or by URL query
parameters.
Please note that you can create a
login user interface that requires both the Auth user name and the Auth ID, so
the users don’t have to go to settings details.
Set the showusername parameter to 2
to show both the sipusername and the username input on the login page.
If you expect the @ character (full
SIP URI) in the sipusername, then set the handleusernameuri parameter to 0 to
prevent extracting the domain from it on the softphone skin.
For production you might reconfigure
this on your server (if possible) to not require a separate user name and auth
user name (by accepting the auth username also as the username without the need
to set the extension number). This is important only if the endusers needs to
type these credentials themselves (to simplify their login process) and it is
not so important if you automate it with some process.
More details about caller-id processing can be found here.
Special
characters in SIP username-password
The webphone filter out special
characters because the SIP standard has some related flaws and a lot of SIP
servers don’t allow such characters.
Some SIP implementations treat the
digest authentication as ASCII text while others treat it as Unicode.
To prevent compatibility issues, the
webphone will warn the users if their account credential contains special
characters.
The built-in algorithm is very
simple:
if
(input != encodeURIComponent(input))
{
//don’t allow and display error
}
else
{
// input is ok. go ahead with it
}
This means that we don't allow
special characters and some implementations might block also the followings
especially as username: , / ? : @ & = + $ #.
See the RFC 3986 about URI reserved characters.
You can add any SIP features after
your needs by changing the SIP headers.
This can be done with the customsipheader parameter or with the setsipheader API.
For example to add asserted
identity, you might use one of the followings as required by your server:
o
P-Asserted-Identity:
<sip: john@yourdomain.com>
o
Remote-Party-ID:
<sip: john@yourdomain.com>;party=calling; privacy=off
o
P-Preferred-Identity:
"John Smith" sip:john@ yourdomain.com
o
Privacy:
id
You can receive the
incoming SIP messages using the getsipheader or getsipmessage API’s (then parse them after your needs from
your JavaScript code).
1.
Make sure that the
“serveraddress” parameter is set correctly (otherwise you will be able to make
calls only to direct SIP URI).
2.
Optionally: Register to the
server. This can be done automatically if the “username” and “password”
parameters are preset. Alternatively you can register from API (Register) or
just let the user to fill in the username/password fields and click on the
“Connect” button. If the webphone is registered, then it can already accept
incoming calls (it will do it automatically, or you can handle incoming calls
from your application, or you can entirely disable incoming calls)
3.
Now you can make outgoing calls
in the following ways:
a.
Automatically with the webphone
startup. For this you will have to preset the username/password/autocall and
callto parameter. Then webphone will immediately launch the outgoing call when
starts (usually with your page load)
b.
Just let the users to enter a
called number and hit the “Call” button (if you are using on of the included
html’s)
c.
or just call the call function (from user button click or from your
business logic)
Read through the parameters to find out
more call divert settings, such as auto-answer or forward.
How to handle incoming calls?
To be able to receive incoming calls,
make sure that you are registered to your SIP server first. Then you can easily
test for example by using any third party softphone
and make calls to your application SIP username (or extension id or full URI,
as required by your server).
The webphone is capable for automatic
line management so if you don’t wish to handle lines explicitly in some specific way, then you can ignore all
notifications, except those where the line (first parameter) is -1 (the global state).
If you wish to auto accept all incoming
calls, you can set the autoaccept parameter to
true. Otherwise use the accept to connect the call
(or the reject to disconnect).
You can listen for call state changes (including for
incoming call setup) using the onCallStateChange callback.
Here is a simple example:
//you
might place this callback inside the on onAppStateChange “loaded” event as
discussed here
webphone_api.onCallStateChange(function
(event, direction, peername, peerdisplayname)
{
if
(event === 'setup') // call init
{
if (direction == 1)
{
// means it is an outgoing call
}
else if (direction == 2)
{
// means it is an icoming call. you might display your call
notification by something like this:
document.getElementById('icoming_call_layout').style.display = 'block'; //
display Accept, Reject buttons
/*
<div id="icoming_call_layout">
<button onclick="webphone_api.accept();">Accept</button>
<button onclick="webphone_api.reject();">Reject</button>
</div>
alert('Incoming call from '+peerdisplayname);
*/
}
}
else if (event === 'disconnected') // call disconnect
{
//you might hide Accept, Reject buttons by something like this:
document.getElementById('icoming_call_layout').style.display = 'none';
}
});
More details and examples can be
found here.
Simple working examples can be found
also among the html’s in the samples folder.
Details about incoming call alert
options can be found here.
How to get the call
duration?
To get the call duration, you can use the onCdr() callback API function like this:
// you will receive call duration on
oncdr() callback
// NOTE: the "connecttime"
and "duration" is expressed in milliseconds
webphone_api.onCdr(function
(caller, called, connecttime, duration, direction, peerdisplayname, reason,
line)
{
// convert string value to integer;
var
durationInt = parseInt(duration,10);
var
durationSec = Math.floor((durationInt+500)/1000);
alert('Call
duration is: ' + durationSec + ' seconds');
});
Full example here (see
the html source).
In case if you need the call
duration during the call (for example to display a call timer), then you can
just should start a javascript timer at call connect and measure the elapsed
time.
Web SIP client setup for Asterisk
You can easily use the webphone with Asterisk and
with any Asterisk derivatives such as FreePBX, Elastix or Trixbox.
There is no any special requirement
for the webphone. You can use the webphone like any other usual SIP or WebRTC
extension (as other regular SIP device, softphone or webrtc endpoint).
The webphone is fine-tuned for Asterisk out of the
box and no changes are needed to work.
The following settings for webphone extensions might
help in some circumstances (in the Asterisk config):
·
dtmfmode=info
·
nat=yes
We created two tutorials to help
Asterisk beginners with the webphone integrations, useful especially if you have some special requirement, such as using
the built-in WebRTC module in Asterisk:
1. Using the webphone as a regular JS
SIP client: Asterisk web SIP client
2. If you wish to use the Asterisk
built-in WebRTC module: WebRTC client for Asterisk
More about webphone WebRTC can be
found here.
We recommend to set the NAT
parameter to yes (nat=yes or nat=force_rport,comedia for new versions) for your
endpoints in the pjsip.conf if you are using your Asterisk server over the
internet.
More details:
http://www.voip-info.org/wiki/view/NAT+and+VOIP
http://www.voip-info.org/wiki/view/Asterisk+sip+nat
http://www.asteriskguru.com/tutorials/sip_nat_oneway_or_no_audio_asterisk.html
If you experience no audio or one
way voice issue, try to set the use_fast_stun, use_fast_ice and use_rport
webphone parameters to 0.
You might also check chat and presence settings if required for your use-case.
If you have some special requirement, such as using
the built-in WebRTC module in Asterisk, check these articles:
·
Setup Web SIP client for Asterisk
·
Asterisk WebRTC setup
Web SIP client setup for 3CX
3CX server (and some other
softswitch software) by default might require a different user name and auth
user name.
This means that for the webphone you
must set both the username and sipusername parameters
or if you are using the softphone skin then you must set both the Username
field on the login screen and the Caller-ID field in the settings.
From the softphone skin (softphone.html):
·
On the login
screen:
o set the “Server” field to the 3CX
address (domain or IP:port)
o set the “Username” field to the 3CX
Authentication ID (example: ‘1qu3iqt’). This will be saved as the “sipusername”
parameter.
o set the “Password” field to the 3CX
Authentication Password (example: ‘xkclq7n’)
·
Go to the
Settings and set the “Caller ID” field to the 3CX Extension number (example:
‘04’). This will be saved as the “username” parameter.
·
Then just login.
Via webphone parameters (configurable in the
webphone_config.js):
webphone_api.parameters
= {
serveraddress: '11.22.33.44:5060', //your 3CX server domain or IP:port
sipusername:
'1qu3iqt', //Auth
ID (Authentication ID)
username: '04', //Extension (Extension
number or Caller-ID)
password: 'xkclq7n', //Authentication Password
(Auth Pass)
display name: 'John
Kennedy', //Account
name (no so important)
loglevel: 5
};
You can configure also by passing
the above settings via the setparameter API or by URL query
parameters.
Please note that you can create a
login user interface that requires both the Auth user name and the Auth ID, so the
users don’t have to go to settings details.
Set the showusername parameter to 2
to show both the username and the sipusername input on the login page.
For production you might reconfigure
this on your 3CX to not require a separate user name and auth user name (by
accepting the auth username also as the username without the need to set the
extension number). This is important only if the endusers needs to type these
credentials themselves (to simplify their login process) and it is not so
important if you automate it with some application.
More details about caller-id
processing can be found here.
Web SIP client setup for OnSIP
Similarly with the above discussed 3CX, OnSIP servers usually requires a
separate username and sipusername to be set and usually also requires an
outbound proxy server setting.
For example if your account details
(as provided by your OnSIP service provider) looks like this:
·
Address
of Record: john@america.onsip.com
·
SIP
Password: secret
·
Auth
Username: america_john
·
Username:
john
·
Domain:
america.onsip.com
·
Outbound
Proxy: sip.onsip.com
Then these are the parameters to be
set for the webphone in the webphone_config.js (for the parameters object at
the beginning of the file):
·
serveraddress:
'america.onsip.com'
·
proxyaddress:
'sip.onsip.com'
·
username:
'john'
·
sipusername:
'america_john'
·
password:
'secret'
Of course, the
username/sipusername/password parameters can be asked from the user at runtime
instead to be set statically in the configuration or you can pass these
parameters also via the SetParameter API.
More details about caller-id
processing can be found here.
Web phone setup with my SIP server
There is nothing special to set the
webphone with any SIP server. The webphone works just like any other SIP client (like an
IP phone or a softphone such as X-Lite). We mentioned Asterisk, OnSIP and 3CX
above because they are popular and they require some specific settings, however
with most other SIP servers all you need to do is to set the serveraddress
parameter and with some SIP service providers you might have to set a separate
username/sipusername (extension/auth id) and set also the proxyaddress
parameter.
The parameters can be set for the
webphone multiple ways as explained at the beginning of the parameters section.
The most important settings are
listed here.
The most important setting is the
serveraddress. Just set it to your SIP server domain or IP address. Make sure
to append the port number if your server is not using the default port (5060).
Example: serveraddress: 'mysipdomain.com:6789'.
The serveraddress (and other
“static” parameters such as the proxyaddress) should usually be set in the
webphone_config.js file.
Other user depending parameters (such as the username, sipusername, password)
might be asked by the user and/or set at runtime with the setparameter
API.
Some SIP servers or services might
require also some other parameters to be set correctly:
·
If you have a
SIP proxy (such as an outbound proxy), then set it as the proxyaddress parameter
·
Some servers
might require a separate user name (extension) and auth user name (auth id). In
this case you will need to set both the username and the sipusername parameters respectively as discussed for 3CX, OnSIP and also described here.
·
Some SIP service
providers provides globally routable telephone number (DID) which might be
applied on the server side or you might need to use it as the username
parameter (thus you might set your phone number as the webphone username parameter and the auth id as the sipusername parameter)
·
If your server
doesn’t accept UDP transport, then you might need to set the transport parameter to TCP (or you can also
set TLS/SRTP)
·
If your server
auth realm is different from its address, then you can set the realm parameter accordingly
·
If your server
doesn’t accept registrations, then you might set the register parameter to 0
·
If your server
has WebRTC support, then configure the webrtcserveraddress accordingly. Read here for more details regarding WebRTC.
·
You might also
adjust some other settings such as dtmf mode, codec or the voicemail
number however
these are usually negotiated automatically
·
For more tweaks,
go through the parameter list and change anything after your needs. However we
recommend to change any parameter only if you are sure, otherwise the default
settings are the best settings and most of them are guessed or negotiated automatically at
runtime
If you have changed any
parameter in the webphone_config.js, make sure that you see the latest version
if you open the js file directly in the browser like: www.yourdomain.com/webphonefolderpath/webphone_config.js.js
If you don’t see the
recent settings that means that the old version was cached by your browser, by
your webserver or some intermediary proxy.
The webphone might
store/cache previous settings in cookie and indexDB "localforage".
Refresh the browser cache
by pressing F5 or Ctrl+F5.
·
In Chrome you can clear all
settings related to the from Developers Tools (from the Menu or F12 or
Ctrl+Shift+I) -> Application tab -> Clear site data
·
In Firefox you can clear all
settings related to the webphone by pressing ALT, then select “Show All
History” from the “History” menu, then right click to your domain and select
“Forget About This Site”.
Check your webserver
caching. You might disable caching by setting the Cache-Control header to
no-store.
More details here.
Make sure that you don’t
have some caching proxy on the path. A sure way to bypass all caching is to
change the server folder (deploy in a “test2” directory and launch from there).
If you are using the NS engine, then you might need to upgrade the webphone
service.
Once a parameter is set,
it might be cached by the browser phone and used even if you remove it later.
To prevent this (instead
of just deleting or setting an empty value) set the parameter to “DEF” or
“NULL” or to its default value for string parameters. For number parameters
instead of removing or commenting them out, you should change it back to their
default value instead.
You might set the configversion parameter to a positive number (or increment it by
one if already set) if you wish the webphone to forget the old settings.
If you have changed some
parameter in the webphone_config.js then you might change its jscodeversion parameter where you include it in your
project, to avoid any caching and force
a re-download by the browser. For example: <script
src="webphone_config.js?jscodeversion=1234"></script>
This is because browser aggressively
cache js files regardless of your HTML expires and cache-control headers. You
can read more about this here.
You can also use different profiles as
described here.
Additionally you might
force the webphone to forgot its old settings at startup with the resetsettings parameter or you can use the delsettings API to clear the settings at runtime (this should be
used only when closing).
Also check this FAQ if you made a recent upgrade but still seems that
the old version is running.
If still doesn’t work,
you should check from another PC (to make sure that nothing is
preinstalled/cached on your PC).
If still doesn’t work,
send a detailed
log to Mizutech support.
How to upgrade to
a new version of the webphone?
Short answer:
Just overwrite all files where you
haven’t made changes and merge the
webphone files where you made changes.
Usually you have to keep your old
webphone_config.js.
Note:
If you haven’t deployed the webphone
before (haven’t used the demo version also), then you should begin the usage by
reading here and here.
Long answer:
You need to upgrade your webphone in
the following situations:
1.
If you have used the demo before
and pay for the license, Mizutech will send your licensed copy
2.
Upon a support request, Mizutech
might send you a new build with changes regarding to your request (bug
fix/improvement/new feature)
3.
Occasionally you might choose to
upgrade to the latest version if you see a new version published by Mizutech
with features/changes of your interest (new versions will be provided by
mizutech for free during your support period)
Before to upgrade, first you should
backup your existing webphone folder.
Then extract the zip sent by Mizutech
and replace the files in your webphone
folder with the new content, but make sure to:
o preserve the settings: if you set some configuration
in the webphone_config.js file, make sure to not overwrite this file
o don’t overwrite files where you made changes if any
(merge them if possible)
Actually there are 2 ways to work with
the webphone:
1.
Include the webphone_api.js into
your project and use the webphone API to build your custom solution.
In this case there are no any concerns, you can just
overwrite the whole webphone folder once we send a new build, except the
webphone_config.js file.
2.
Modify directly the html/css/js
files included in the webphone:
In this case make sure to not overwrite the files
where you made modifications.
The core of the webphone is the webphone\js\lib\*.js files,
this is where most our work are done and these files might differ depending on
your license. You never need to change these files and you should always
overwrite them with the latest version we send (full customization can be done
without touching these files)
With the upgrades we usually made
changes all over in our code (js/html/css/native files).
However all the parameters and the API
is fully backward and forward compatible, so you don’t need to change your own
code.
·
If your code is in separate files
(separate js/css/html) then you just need to replace the webphone files.
·
If you made changes in our files
(such as modifying the softphone skin) then at least replace the “\js\lib” and
the “native” folders and try to merge the rest if/when possible.
Note:
o Although the webphone_js.api file is rarely changed,
we don’t recommend writing code in this file. Use your separate js files for
your project and just include the webphone_api.js script to your project.
o If you/your customers might use also the NS engine
(you haven’t deprioritized it): you might adjust the minserviceversion if you have this set to any value, otherwise you
might have to upgrade the NS service manually or the new webphone will continue
to use the old version (which is not a problem most of the time, but we don’t
recommend to use very old outdated versions).
o You might reinstall the NS engine on your test client
PC if you have used this engine before, for the changes to be applied
instantly: On windows you just need to run the WebPhoneService_Install.exe from
the webphone\native folder.
o If you have changed the parameters in the
webphone_config.js then you might change its jscodeversion parameter where you
include it in your project. For example: <script
src="webphone_config.js?jscodeversion=1234"></script>
o New versions of the webphone are always backward
compatible and API compatibility is always ensured except occasional
minor/compatible changes so you can upgrade without any changes in your code.
However each you version contains changes in the VoIP engines so you should
always verify and test before to put in production to make sure that the
webphone still fulfills your needs and downgrade to the previous version if you
encounter issues (Then you might try the upcoming release again to see if your
pending issue were fixed).
If somehow you managed to achieve your
goals by modifying the webphone files (and not working in a separate
projects/your own files by including the webphone_api.js as suggested above),
then just overwrite all files where you haven’t made any changes and all should
be fine. You must overwrite at least the followings:
o all .js files from the webphone\js\lib folder
o all files from the webphone\native folder
o all missing files (if there are some new files in the
new version not present in your old version)
I got an upgrade for my feature/issue request, but
nothings seems to be changed
Make sure that you are
actually using the new version. Refresh the browser cache by pressing F5 or Ctrl+F5.
Make sure that you don’t have some caching proxy on the path. A sure way to
bypass all caching is to change the server folder (deploy in a “test2”
directory and launch from there) and/or use another PC or browser where the
webphone was not loaded before.
If your webphone is using
the NS engine, then it might be possible that the PC is running an old version.
Upgrade the NS engine as explained here.
If you are having
difficulties applying new settings, read here.
If still doesn’t work,
you should check from another PC (to make sure that nothing is
preinstalled/cached on your PC).
If still doesn’t work,
send a detailed
log to Mizutech support.
How to upgrade the NS engine?
In short:
The NS engine (if used by
the webphone) should upgrade itself automatically if needed, however, you can
also perform a manual reinstall in the following way:
·
On Windows: Just run the
WebPhoneService_Install.exe installer on the client PC from webphonepath\native
folder to quickly upgrade to latest version.
·
On Linux: Extract the
webphone_ns_lin64.zip exe from the from webphonepath\native folder and run the
webphone_ns_lin64.run executable with root user privileges (sudo).
·
On MacOS (deprecated): Launch the
webphone_ns_mac.zip from the from webphonepath\native folder which is an
application container and will reinstall the NS engine.
Windows details:
In some circumstances
under Windows OS the webphone might install an NT service named “Webphone”
(This is the NS service plugin and it is installed only on user opt-in). The
NS engine will run as a background service and it has a silent single-click
installer. This is a full SIP stack running as a windows native executable and
used by the webphone if set so or other engines (such as WebRTC) are not
available. It is important to understand that this is a client side component,
running on the endusers PC’s (you don’t need to install anything on your web
server).
The webphone (javascript
running in the browser) will auto detect the locally running NS engine to be
used as a SIP stack and will communicate with the NS engine over a localhost
websocket connection.
Time to time new versions
of the engine are released, shipped with new versions of the webphone (you can
find the engine installer in the native subfolder of the webphone package).
This might result in situation when you already have a new version of the
webphone but the users are still using an old version of the NS engine
installed previously on their PC.
There are the following
options to upgrade the NS engine to latest version:
·
Auto-upgrade: the core of the ns
engine is capable to auto upgrade itself if new versions are found (you can
disable this by setting the “autoupgrade” parameter to 6). This is very
conservative which will rarely trigger an upgrade (only if the current version
is very outdated or the current version has a serious issue which have been fixed
in the new version).
(In
the NS service there is a built-in SSL certificate for localhost. This is also
capable for auto-upgrade when new certificates are found unless you set the
“autoupgrade” to 5)
·
Force upgrade: Set the minserviceversion webphone parameter to the (latest) version of the engine you have.
This will trigger an automatic install. You might also set the nsupgrademode to force immediate upgrade
·
Reinstall manually: just launch
the \webphone\native\WebPhoneService_Install.exe (directly from the webphone
package sent by Mizutech or deploy it first to your webserver and let the users
to download from www.yourdomain.com\webphonepath\native\WebPhoneService_Install.exe). Reinstall from client PC is also explained here.
·
Reinstall from the softphone
skin: Users can install the latest NS engine from the softphone skin by just
going to menu -> settings -> advanced settings -> sip settings ->
voip engine -> select the NS engine. That will offer the download of the new
version.
·
Custom methods: You can offer the
NS upgrades as you wish and when you wish from your custom solution. Just
redirect the user to download the installer executable.
·
Disable: you can disable the
usage of the NS engine by setting the enginepriority_ns to 0 (completely
disable) or 1 (deprioritize). You should do so only if other engines such as
WebRTC are available in your environment.
You can also query the NS
engine version with the following API calls:
·
get_version_ns_num (callback):
returns with the NS engine major version number which is used also for
minserviceversion
·
get_version_ns (callback):
returns with the NS engine exe version
Linux details:
The webphone_ns_lin64.run
script (from the webphone_ns_mac.zip file) will copy the NS engine files to
/opt/WebPhone_NS/ and will install it as a service (daemon).
The installer script will
also auto detect local JRE if any, otherwise might install it automatically if
needed.
The webphone (javascript
running in the browser) will auto detect the locally running NS engine to be
used as a SIP stack and will communicate with the NS engine over a localhost
websocket connection.
MacOS details:
Launching the
webphone_ns_mac.zip app will copy the NS engine files to
/Applications/WebPhone_NS/ and will install it as a service.
The installer script will
also auto detect local JRE if any, otherwise might install it automatically if
needed.
The webphone (javascript
running in the browser) will auto detect the locally running NS engine to be
used as a SIP stack and will communicate with the NS engine over a localhost
websocket connection.
Note: you can also ask
Mizutech to send you a build which will force upgrade to latest version
(forcensupgr/minimumservicebuild/BUILDNUMBER/API_GetBuildNumber)
How to uninstall or (re)install the NS engine
Windows:
In some situation under
Windows OS the webphone might install an NT service named “Webphone”. This is
the NS service plugin running on the client PC and it is installed only on user
opt-in.
Here are how you can
disable/uninstall/reinstall if somehow you need to:
·
Disabling: If you don’t wish to
use the NS engine, you can just disable the service (set startup type to Manual
and Stop the service) or set the enginepriority_ns to 0
·
Uninstalling: The service has its
own uninstaller, so you can easily uninstall it from the Add/Remove Programs
control panel. It can be also removed with the –uninstall parameter. Example: C:\Program Files
(x86)\WebPhoneService\WebPhoneService.exe –uninstall.
·
Re(installing): The install can
be done from the softphone skin by just going to menu -> settings ->
advanced settings -> sip settings -> voip engine -> select the NS
engine. That should offer the download of the new version.
You
can also (re)install/upgrade manually by running the
“WebPhoneService_Install.exe” from the webphone\native folder. (You can also
download it from your webserver: http://yourdomain.com/path_to_webphone/native/WebPhoneService_Install.exe or from the webphone package provided by mizutech).
Just run the executable and it will install the NS engine automatically (this
should work even if the service is already running as it will automatically
update your old version)
·
Upgrade: see the above FAQ
point
Linux:
Use this script
to uninstall the NS engine daemon from any Linux distro.
MacOS:
Use this script
to uninstall the NS engine service from macOS.
Note: There is no need to uninstall the old previous
version before to install the new one. Then installer will take care about the
details (will stop the old executable first and will overwrite the old files as
needed)
How to upgrade
from the old java applet websipphone?
Note: this is relevant only for our old
customers using the old java applet based webphone.
This new webphone has an easy to use
API, however if you wish to keep your old code, you can do so with minimal
changes as we created a compatibility layer for your convenience. Follow the
next steps to upgrade/migrate to our new webphone:
1. The root folder of the new webphone
is the folder, in which "webphone_api.js", “webphone_config.js” and
"softphone.html" files are located.
2. Copy the contents of the new
webphone root folder, in the same folder where the old webphone's .html file is
(merge "images" and "js" folders, if asked upon copy
process).
3. In the <head> section of the
.html file, where the old webphone is, replace line:
<script type="text/JavaScript"
src="js/wp_common.js"></script>"
with the following lines:
<script
type="text/JavaScript"
src="webphone_api.js"></script>
<script
type="text/JavaScript"
src="oldapi_support.js"></script>
Note: Don't remove or add any webphone
related Javascript file imports.
"jquery-1.8.3.min.js " file
will be imported twice, but that is how it supposed to be, in order for the
upgrade to work correctly.
For old webphone customers: please note
that this new webphone is a separate product and purchase or upgrade cost might
be required. The old java applet webphone have been renamed to “VoIP Applet”
and we will continue to fully support it. More details can be found in the wiki.
How to activate
voice recording?
The webphone has the capability to
record calls, store in a voice file and upload it to your FTP server or web
service.
To activate this feature, just set the
set the voicerecupload parameter or use the voicerecord API after your needs.
All you need for call recording is to
set the URL where the files will be uploaded.
The URL can be:
·
FTP: in this case you have to run
an FTP service somewhere
·
or HTTP: in this case you will
need to create a server side script which can accept the upload
This URL can be set:
·
globally with the voicerecupload webphone parameter if all calls have to be recorded.
Example with FTP
upload (added in the webphone_config.js file):
voicerecupload:
'ftp://user01:pass1234@ftp.foo.com/voice_DATETIME_CALLER_CALLED'
·
or dynamically (for example for a
user or per call) with the voicerecord
Java Script API.
Example with HTTP upload
(add this somewhere into your JavaScript code):
webphone_api.voicerecord(true,
'http://www.foo.com/myfilehandler.php/?filename=callrecord_DATETIME_USER.wav')
See the voicerecupload parameter and the voicerecord API for more details.
Notes:
Since the WebRTC engine is running from browser, it doesn't have local
access such as disk access.
Activating call recording with the WebRTC engine might completely
change the media path if you are using a WebRTC gateway. With other words, the
media path is more optimized when call recording is not activated. This is only
for WebRTC. For NS or Java you will have the same path.
If your SIP server is public, then we recommend to setup a public FTP
server or Web service to handle the storage of the voice files and configure
your webphone accordingly.
Otherwise, the file storage location possibilities are the followings:
·
WebRTC engine with our public WebRTC-SIP proxy service: the
webphone can upload the recorded files to public a FTP server or Web service
·
WebRTC engine with the MRTC gateway:
the recording will happen on the MRTC gateway as directed by the webphone
·
WebRTC engine your own WebRTC service: you should do the call
recording on your WebRTC server and store it anywhere you wish
·
NS or Java engine: these engines are capable to store the
recorded files to any FTP server or Web service (including localhost or private
servers) and also to local file (by setting the voicerecording parameter
accordingly: 0=no, 1=record to local file system, 2=remote http/ftp only,
3=both local and remote)
The webphone comes with encryption
support for both the signaling and the media, including end-to-end encryption.
·
For SIP signaling TLS encryption
is supported (SIPS) configurable with the transport
parameter.
·
For media (RTP) the webphone has
support for SRTP, configurable with the mediaencryption parameter.
·
When used as a JS WebRTC library,
then by default everything is encrypted: WSS (secure websocket) for the signaling
and DTLS/SRTP for the media.
·
For user to user calls the
webphone is capable for end-to-end encryption even if your server doesn’t have
any encryption support (only if your server doesn’t force media proxy).
Configurable with the use_fast_ice setting.
·
Optionally we also provide
proprietary VoIP tunneling solution. This is useful to bypass any ISP VoIP filtering especially
in countries where VoIP is banned.
Auto-provisioning or auto-configuration is a simple
way to configure IP-phones for SIP servers used on local LAN.
The exact same behavior can be easily achieved by
using the webphone with dynamic parameters.
Actually since the webphone is web hosted, it is
auto-provisioned by default (you can just change the settings in the webphone_config.js, or change the settings
from Java Script using the setparameter() API or pass them via URI query parameters or you can just deploy separate instances into
separate paths).
Obviously MAC address based autoprovisioning will not
work for browsers (webpages doesn’t have access for the device MAC address).
However you can easily serve different configurations
to your users dynamically using any logic after your needs. Since this is a web
based solution its configuration can be very easily controlled from a server side
script by just changing the webphone parameters dynamically as you wish.
First you should set the parameters common for all
instances (all users) on your webserver in the webphone_config.js file.
Then (at runtime or from a server side script ) you
just have to set account related settings (per user settings) using one of the
method specified in the Parameters
chapter (by URL, via a server API by scurl_setparameters, or from javascript by the setparameter API).
For example you might auto provision the webphone
based on username, browser IP, browser fingerprint or a random ID per client.
The prebuilt softphone skin has the
file transfer feature already built in. File transfer actually consists of two
simple steps:
·
upload to a
webserver the file selected by the user
·
send a chat
message to the destination containing the download URL
By default Mizutech’s service is
used for storage, but this can be customized using the filetransferurl
parameter, for example:
filetransferurl:
'http://www.domain.com/filestorage/'
The file name is a unique
automatically generated string.
If the webphone is used as SDK and
you wish to implement the file transfer feature, it can be done easily. Below
is a simple example HTML form, similar to the one used by the webphone. This
form consists of a filedata input, a hidden input for the filename and a submit
button. The action should be the URL to your file webserver (filetransferurl):
<form
action="http://www.domain.com/filestorage/" method="post"
enctype="multipart/form-data" >
<input
type="hidden" id="filename" name="filename"
value="MY_UNIQUE_FILE_NAME">
<input
name="filedata" type="file" id="fileinput"
/><br />
<input
type="submit" id="btn_submit" value="Send file"
/>
</form>
Also you have to implement a simple
script on server side to store the received files.
Disable popups and
toasts
Set the following parameters to
disable all kind of popup messages and toasts/hints:
incomingcallpopup: set to 0 to disable
showtoasts: set to false to disable hints
askfornotifpermission: set to 0 to disable
transferpopup: set to 0 to disable call transfer
popup
displayvideodevice: set to 0 to disable video preview
displaynotification: set to 0 to disable missed
call/chat notifications
disablepopup: set to 1 to
blindly/unconditionally disable all alert dialogs
disabletoasts: set to 1 to
blindly/unconditionally disable all toast/hints texts
enablenomicvoicewarning: set to 0 to disable audio related
notifications
If you are using a specific engine,
then set its enginepriority value to 5 to avoid asking for other engines regardless of
the circumstances.
Incoming call notifications
The notification capabilities about
incoming calls depends on the browser and the engine used.
Normally the webphone is capable to
accept incoming calls once registered to the SIP server and on incoming calls
it is possible to display various notifications and a ringtone for the
endusers.
Some browsers/engines can present
the incoming calls only if your page is running, however some browser/engine
combinations is capable to notify the user even if the page (or even the
browser) is closed.
You can adjust the following
incoming call alert related settings based on your needs:
o callreceiver: specify to listen for incoming
calls even if the browser page is closed. With WebRTC this might use push
notifications. With the NS engine it will use background listener service.
o push notifications: may be capable to notify the user about incoming calls even if the
browser page is closed while using the WebRTC engine
o incomingcallpopup: set HMTL5 notification for
incoming calls
o displaynotification: configuration option for missed
call/chat notifications
o sound alert related settings: volumering, ringtimeout, beeponincoming and here
In case if you wish to disable beep
emitted on new calls when there is already other call in progress, set the ringincall,
beeponincoming and beeponconnect parameters to 0.
See this FAQ point to handle incoming calls from your
code.
It is possible to configure the webphone to always
receive calls, even if your webpage is closed.
If you are using the WebRTC engine you can receive
incoming call notifications if push notifications are enabled for your project.
For the NS engine, set the following parameters to
always run and listen in the background:
callreceiver:
2
backgroundcalls:
1
destroyonpageclose:
0
needunregister:
false
With the above settings, the NS engine can also
survive page reloads while in call.
VoIP Push notification is a method
to display a browser popup for the user on incoming SIP call or text message
even when the webphone is not running.
The user can pick-up the call if
clicks/taps on the notification.
This is specific for the WebRTC engine
only as with the NS engine you already have a local service which can listen for
incoming calls even if the browser is not running.
Note: Currently browsers doesn’t support a background
listener, thus to receive the notification a browser instance must be already
running (but it is not necessary that your page with the webphone to be
opened). You might force the NS engine (set the enginepriority_ns to 4) If the
enduser must be always available regardless whether the browser is running or
not. Browser vendors also plan to implement an always running service for push
notifications but it remains to be seen when this feature will be actually
released.
You can enable/disable push
notifications with the callreceiver parameter or with the enablepush parameter (possible values: 0: disable,
1: enable).
Also the firebase-messaging-sw.js
file have to be copied to your web server root directory (If the webphone
folder is not your web root, then you must copy this file to webroot).
Push notifications can be handled in
the following ways:
·
Via the free Mizu PUSH service.
If you are using the Mizutech WebRTC-SIP gateway service, then you also have
server side push notifications support.
·
Directly with your SIP server if
your server has support for push notifications. Contact your server vendor or
check your server documentations for the details and implement it accordingly for the webphone.
·
With the Mizu WebRTC-SIP
or voip push gateway. Instead of using our free service, you can setup your dedicated
gateway to handle the push notifications. A detailed guide with the
implementation details can be found here: VoIP Push Notifications. See the Web and WebPhone chapters specific for this
SIP library
·
Using the webphone with the Mizu
SIP Softswitch or IP-PBX. Push notifications are supported by all Mizu server
side products.
In case if you wish to manage push
notifications externally (such as from a native Android or iOS app running the
webphone in WebView) then you might just send the X-MPUSH
extra header (if using our VoIP server or gateway) or set the push parameters in the
contact header with the contact_uri_parameters parameter after the RFC
8599 standard.
For example for Android the contact_uri_parameters should be set to 'pn-provider=fcm;pn-param=APPPACKAGENAME;pn-prid=TOKEN'.
More details here.
More details about Mizutech VoIP
push notifications tech can be found here and here.
Using the webphone in a WebView
You can embed the webphone into any
application using a WebView to be used in any native app for any OS such as Windows, Android or iOS.
Permissions (such as audio
recording) are usually required if the webphone will be used in webview! These permissions needs to be handled in your native
app and most platforms have permission handling mechanisms.
It is possible to just use the webphone user interface
(for example the softphone skin from softphone.html) or you can implement any
native GUI running the webphone in a hidden webview and interacting with it via
the API.
For example in Android:
- A WebView
tutorial can be found here.
- You need to request RECORD_AUDIO
(and CAMERA for video calls) to be able to make calls.
- These are considered “dangerous”
permissions and have to be requested runtime, and the user needs to grant
access in order to be able to record audio inside a webview.
·
It is best
practice to request the native android “RECORD_AUDIO” permission before you
load the webphone into the webview.
·
You can fully
interact from your app with the webphone and inverse using your platform
specific mechanisms (dynamically generate HTML from your native code, call
JavaScript directly from your native code or use callbacks from JS to app)
- Below are a few useful links
regarding android permissions:
A full android project example can be downloaded from
here.
Another simple android example code can be found here.
A basic Electron
integration example can be found here.
The same also applies to iOS and other OS: you have
to request the permission runtime from the user, and only if the user grants
access, will the webphone be able to record audio and/or video.
You might also implement push notifications: get a
token in your native app and pass it to the webphone to be sent by SIP
signaling to the server. Details here.
Note:
WebRTC is not
supported in WebKIT browser on iOS. In iOS native webview
(SFSafariViewController) WebRTC is supported starting from version 13.
There are
also several tools and frameworks to convert your web app into a native WebView
based application such as React Native
or PhoneGap.
We take special care to remain compatible with all
browsers, including down to IE6, thus we are not using the latest ES5/ES6
features.
However, since the webphone is pure vanilla
JavaScript, you can easily create any wrapper around it (for example using an
async/await interface instead of the existing callback functions) or convert it
into a JS module if in this way it can be more easily consumed in your
project.
The webphone is just plain JavaScript which can be
deployed as copy-paste and consumed in any framework.
See the package.json file (in the webphone.zip)
if you wish to create an npm package from it (the webphone itself doesn't have
any dependencies on other JS libraries).
Since the webphone comes as simple/vanilla JS API it
can be easily used from any framework, including React and React Native.
The integration should be simple.
You might use it as vanilla JS, you might create a
wrapper around the webphone_api.js, you might convert it into a module or
create a react component.
More help can be found here and here.
If you wish to use it as-is as a module, then you
might use the exports-loader like this:
import * as webphone_api from
'exports-loader?webphone_api!webphone_api;
A simple react example generated with create
react app can be downloaded from here.
You can quickly test your desired
language by setting the language parameter.
To add a new language or change/fix
existing translations, use this website.
If you don’t have the login
credentials, ask Mizutech support.
You will be able to add new
translations, change any existing strings and generate your new webphone copy
with the changes.
By default the webphone
might have the following languages included with full or partial translation:
o
en: English
(default)
o
hu: Hungarian
o
it: Italian
o
pt: Portuguese
o
ro: Romanian
o
es: Spanish
o
de: German
o
tr: Turkish
o
ja: Japanese
o
fr: French
o
zh: Chineze
You can set the default
language with the language parameter.
Note for Mizutech support: use the
MTranslate app to merge the translations.
Use an
iframe to integrate the webphone into your Angular HTML page and set the iframe's "id"
attribute to "webphoneframe", for example:
<iframe id="webphoneframe" src="http://www.yourdomain.com/webphone_package/softphone.html" width="300" height="500" frameborder="0" allow="microphone
*; camera *; autoplay" allowfullscreen="true"
></iframe>
To be able
to access the webphone API in the iframe
from the parent page you will have to include the iframe_helper.js file from the webphone package.
This can
be achieved following the below steps:
-
Create a
directory inside your Angular project src directory. We will name the directory webphone.
-
Copy iframe_helper.js from webphone package into src\webphone directory.
-
Open angular.json file and set the path to iframe_helper.js under projects -> scripts
section:
"src/webphone/iframe_helper.js"
-
Open app.component.ts and declare the webphone_api
variable:
declare var webphone_api:any;
Now you
are able to fully take advantage of the webphone API.
More
details can be found here, here and here.
Although the webphone has built-in
support for contacts, you might implement your own separate contact list /
address-book module if you need some more related functionalities.
See the listcontacts/addcontact/getcontact/delcontact API’s for more details.
These are useful especially if you are
using the softphone skin (softphone.html) and you wish to manipulate the
contacts from your code.
How to integrate with server side address-book
This
description is mostly for non-JavaScript developers of you are going to
integrate with a server side address book API with the softphone skin
(softphone.html).
Otherwise,
you can easily manipulate the contacts from JavaScript with the listcontacts/addcontact/getcontact/delcontact
API’s.
Use the serveraddressbook_sync
parameter to specify how the synchronization have to be done: 0=only once, 1=once, until we receive
contacts, 2=every time webphone starts.
Use the serveraddressbook_url
parameter to specify the URL or API from where the contacts have to be
synchronized. The downloaded data can be a static file or dynamically generated
and it must have the following format:
Contacts
will be separated by "carriage return new line": \r\n
Contact
fields will be separated by "tabs": \t
A
contact must have the "name" and "number" fields. Other
fields are optional.
The
order of fields and their meaning:
name: the name of the contact (usually full name or nickname)
number: username, phone number, extension ID or SIP URI
favorite: 0 means No, 1 means Yes
email: email address of the contact
address: the address of the contact
notes: notes attached to this contact
website: web site attached to this contact
type: any string, but on the softphone skin only the following are handled:
phone, home, mobile, work, other, fax_home, fax_work, pager, sip
The
number and the type can be a list with strings separated by the | character.
Set the serveraddressbook_clear
parameter to 1 if you wish to always clear/replace all contacts instead if
merge (default is 0 which means merge).
Set the serveraddressbook_allowedit
parameter to 0 if you wish to disable
contacts edit/delete/add by the enduser (default is 1 which means edit enabled)
Set the normalize_contact
parameter to 0 if you wish to avoid also characters, otherwise (1 by
default) the webphone will normalize the strings.
How to add a color
theme?
Webphone comes with a few prebuilt skins, which can
be changed from Settings -> Theme or preconfigured with the colortheme parameter.
The look and feel of the webphone skin can further be
customized by altering any of the predefined themes found in:
js\softphone\themes.js.
Open the themes.js file (it is located in
webphone/js/softphone folder) with your favorite text editor.
In the "themelist" variable are stored the
current webphone themes, you can edit for example the theme_1 after your needs.
Please note that the theme_0 (default theme) can't be modified from this file.
From the variables names should be obvious they
meaning (bg - means background), the colors are defined in RGB hex.
mainlayout.css: color
to replace: #1d1d1d with urlparam: bgcolor
wphone_1.0.css: color
to replace: #333 with urlparam: buttoncolor
wphone_1.0.css: color
to replace: #373737 with urlparam: buttonhover
wphone_1.0.css: color
to replace: #22aadd with urlparam: tabselectedcolor
mainlayout.css: color
to replace: #31b6e7 with urlparam: fontctheme
mainlayout.css: color
to replace: #ffffff with urlparam: fontcwhite
wphone_1.0.css: color
to replace: sans-serif with urlparam: fontfamily
After you modify a variables value, you need to
reload your webphone otherwise the modifications will not any effect.
You will also need to set the “colortheme” parameter
to match your theme index.
You can create new themes easily by searching
for existent dialer skins and after you find one that it is close to your needs
just pick the preferred colors
using a software like Color
Pic or you can search for a color matching tool to help you in building better color schemes.
It is also possible to use the softphone build web service to customize the webphone design (“Design” link the
and “Advanced coloring” option using the designer).
How to use the webphone
via URL parameters?
The webphone can load its
settings also from the webpage URL (URI query strings) and perform various
actions such as initiate a call. All the listed parameters can be used,
prefixed with “wp_”.
Example to trigger a call
with the softphone by html url parameters:
http://www.yourwebsite.com/webphonedir/softphone.html?wp_serveraddress=YOURSIPDOMAIN&wp_username=USERNAME&wp_password=PASSWORD&wp_callto=CALLEDNUMBER&wp_autoaction=1
Example to trigger a call
with the click to call by html url parameters:
http://www.yourwebsite.com/webphonedir/click2call.html?wp_serveraddress=YOURSIPDOMAIN&wp_username=USERNAME&wp_password=PASSWORD&wp_callto=CALLEDNUMBER&wp_autoaction=1
Example trigger chat by
html parameters
http://www.yourwebsite.com/webphonedir/softphone.html?wp_serveraddress=YOURSIPDOMAIN&wp_username=USERNAME&wp_password=PASSWORD&wp_sendchat=TEXT&wp_to=DESTINATION&wp_autoaction=2
Note:
You should use clear
password only if the account is locked on your server (can’t call costly
outside numbers). Otherwise you should pass it encrypted or use MD5 instead.
You should encode with encodeURIComponent(). Parameters can be encoded separately or you can
encode the whole query string after the ? character.
See also click to call.
All you need to implement
click-to-call for your webpage is this webphone and a SIP account (at any VoIP
service provider or your own SIP server)
Just set your account
settings for the webphone and you are ready to go:
-your voip service
provider server address (“serveraddress”
webphone parameter)
-sip username (“username” webphone parameter),
-sip password (“password” webphone parameter)
-optionally preconfigure
the number to call (“callto” webphone
parameter)
You can set these
statically from the webphone_config.js file or via javascript using the setparameter and call
API. (Mizutech can also hardcode these in your final licensed build if you
wish.)
Then you can use the
“click2call.html” from the samples folder or just use the call API from your custom button.
Note: if you hardcode the above parameters in the
webphone_config.js, then it is a good idea to encrypt them or make sure that
the account is restricted after your needs.
For more details check
the click to
call section.
Just set your phone number
in your email signature as a link (URL anchor) to the webphone click to dial: http://www.yourwebsite.com/webphonedir/click2call.html?wp_serveraddress=YOURSIPDOMAIN&wp_username=USERNAME&wp_password=PASSWORD&wp_callto=YOURNUMBER
In this way the phone
number in your email signature will become a clickable link which will trigger
the webphone and will call your number automatically on SIP.
Instead of the
click2call.html, you can also use the softhone.html (or your custom webphone
html).
For account
username/password you should just create a special extension on your SIP server
which is not authenticated and allows unrestricted calls to local extensions
only (not to outbound/paid).
More details about click
to call can be found here.
PTT can be implemented by
using the hold function.
If call hold is not well
supported by your server or the remote peer, then you might use mute instead.
Other related functions and
parameters which you might use are the followings:
ismuted, isonhold,
automute, autohold, holdtype, muteonhold, defmute, sendrtponmuted
Clickable phone
numbers on webpages
The webphone can be used
to automatically recognize telephone numbers on a web page, convert them to
clickable links and if the users click on the link it will dial the number.
This functionality is
implemented by the linkify.js (in the /js/linkify folder).
You can find a working
example for this in the samples folder linkify_example.html.
To float the webphone skin over your
web page, just set the following CSS attributes for the container HTML element
of the webphone (which can be a DIV or an iframe):
// this aligns the webphone
to the bottom-right corner of you page
z-index: 1000; position:
fixed; bottom: 0px; right: 0px;
If you wanted for instance to set it in
the top-left corner, then the CSS attributes would be:
z-index: 1000; position:
fixed; top: 0px; left: 0px;
How to pass PHP session variables?
You can use this format:
var
jsvariable='<?php echo $php_session_value;?>';
webphone_api.setparameter('parametername',
jsvariable);
Just make sure that the
page is actually generated by php and not statically served (so the php scripts
runs on the page).
You can easily verify by
inspecting the page source once the page is loaded into the browsers.
How to manage multiple lines?
Multi-line means the
capability to handle more than one call at the same time (multiple channels).
By default you don't need
to do anything to have multi-line functionality as this is managed automatically with each new call on the first “free”
line.
If you have multiple
ongoing calls, then the active call will be the last one you make or pickup.
Multi-line vs
Conference
When we refer to
“multi-line” we mean the capability to have multiple calls in progress at the
same time. This doesn’t necessarily means conference calls. You can initiate
multiple simultaneous calls by just using the call API
multiple times (to initiate calls to more than one user/phone), so you can talk
with remote peers independently (all pears will hear you unless you use hold on
some lines, but the peers will not hear each-others). You can also have
multiple incoming calls at the same time in any state (ringing/connected).
To turn multiple calls
into a conference, you need to use the conference API (or use the conference button from the
softphone.html). When you have multiple peers in a conference, all peers can hear
each-other.
User interface:
Multi line functionality
is enabled by default in the webphone.
Once the enduser initiate
or receive a second call, the webphone will automatically switch to multi-line
mode.
If you are using the
softphone skin (the softphone.html) its user interface will display the
separate calls in separate tabs, so the user can easily switch between the
active calls.
Actually the followings
user interface elements are related to multi line:
·
on the Call page, once you have a
call, you can initiate more calls from Menu -> New call
·
for every call session, a line
button will appear at the top of the page so the users can change the active
line from there
·
the line buttons for managing
call sessions, will also appear in case another incoming call arrives
·
you can easily transfer the call
from line A to line B
·
you can easily interconnect the
active lines (create conference calls)
Disable multi-line
You can disable
multi-line functionality with the following settings:
-set the “multilinegui”
webphone parameter to 0
-set the "rejectonbusy" setting to "true"
Other related parameters
are the "automute" and "autohold"
settings.
JavaScript library/API
When the webphone is used
as an SDK, the lines can be explicitly managed by calling the setline/getline
API functions:
- webphone_api.setline(line); // Will
set the current line. Just set it before other API calls and the next API calls
will be applied for the selected line
- webphone_api.getline(); //Will return
the current active line number. This should be the line which you have set
previously except after incoming and outgoing calls (the webphone will
automatically switch the active line to a new free line for these if the
current active line is already occupied by a call)
For example if there are
multiple calls in progress and you wish to hangup one of the calls, then just
call the webphone_api.setline(X) before to
call webphone_api.hangup().
The active line is also
switched automatically on new outgoing or incoming calls (to the line where the
new call is handled).
Channels
The following line
numbers are defined:
o
-2: all (some API calls can be
applied to all lines. For example calling hangup(-2) will disconnect all
current calls)
o
-1: current line (means the
currently selected line or otherwise the “best” line to be used for the
respective API)
o
0: undefined (this should not be
received/sent for endpoints in call, but might be used for other endpoints such
as register endpoints)
o
1: first channel
o
2: second channel
o
…
o
N: channel number X
Some behaviors will
automatically change when you have multiple simultaneous calls. For example the
conference API/button will automatically interconnect the existing parties or
the transfer API/button will transfer the call from the current line to the
other line.
Note: If you use the setline() with -2
and -1, it will be remembered only for a short time; after that the getline()
will report the real active line or “best” line.
API usage example:
webphone_api.call(‘1111’); //make a call
webphone_api.call(‘2222’); //make second call
//setup conference call between all lines
webphone_api.setline(-2); //select all lines
webphone_api.conference(); //interconnect current lines
//disconnect the second call
webphone_api.setline(‘2222’);
webphone_api.hangup(true);
//put first call on hold
webphone_api.setline(‘1111’);
webphone_api.hold(true);
Notes
o
If your use-case requires
multiple simultaneous calls, then you might wish to set the following
parameters:
usecommdevice: 0
aec: 0
aec2: 0
agc: 0
o
Some API might auto-guess the
correct line to use if you supply a wrong line. For example if you call
hangup() on a line which doesn’t have an active call then the webphone might
disconnect the call on another line if any. (Auto-guess best match line)
o
You can use the linetocallid and the callidtoline
functions if you wish to convert between line number and SIP Call-ID.
Alternatively, you might
just run separate webphone instances to implement multiple lines as described here.
How to manage multiple accounts?
Multi-accounts means the
capability to handle more than one SIP account at a time.
You can use different SIP
credentials on the same server (extensions) or to different servers.
To enable multiple
accounts, you can use the extraregisteraccounts parameter (if you are using fix accounts which can
be set statically in the webphone_config.js or passed as URL parameter) or at
run-time with the registerex
API.
When you are using
multiple accounts, the SIP engine will register with each account so it is
capable to also receive calls via any of the accounts. For outgoing calls or
chat the “main account” is used by default (which is specified by the
serveraddress/username/password/etc parameters).
Another way to be registered with
multiple accounts is to launch multiple webphone instances in different
webpages (or in different iFrames if you wish to display them on the same
page).
You can also use different profiles to completely separate the settings storage.
How can I set the engine to be used?
The best engine is
selected by the webphone automatically based on circumstances (client device,
OS, browser, network, server):
However the preferred
engine can influenced on 3 levels:
-Choice presented to the
user in some circumstances on startup (This is not always presented. The
webphone will go with the best engine when there is a definitive winner,
without asking the user)
-Engine settings in the
user interface, so the enduser might change its own preferred engine
-Engine priority options
in the configuration. You can set this in the “webphone_config.js”
(enginepriority_xxx settings as discussed in this documentation Parameters section)
There should be very rare
circumstances when the default engine selection algorithm should be changed.
The web sip lib always tries to select the engine which will disturb the user
the less (minimizing required user actions) and offers the best performance.
For example don't be
inclined to disable Java for the sake of its age. Users will not be alerted to
install Java by default. However if Java is already enabled in the user browser
then why not to use it? Java can offer native like VoIP capabilities and there
should be no reason to disable it.
We spent a considerable
amount of work to always select the best possible engine in all circumstances.
Don't change this unadvisedly, except if you have a good reason to use a
particular engine in a controlled environment.
Common terms used in this
document:
WebPhone: JavaScript SIP
library or ready to use softphone for browsers
Caller: The person
making/initiating a call
Callee: The person
receiving a call (called party)
SIP: The Session
Initiation Protocol (SIP) is a signaling protocol used for establishing
sessions in an IP network
NS engine: native VoIP
client service to be installed on client PC to be used by the webphone from
browsers similarly to a browser plugin
WebRTC: Web Real-Time
Communication used implemented in HTML5 browsers and other clients
RTP: media channel
protocol
DTLS: UDP security
protocol to encrypt the RTP packets
SRTP: encrypted RTP
Websocket: TCP like
connection for browsers
WS: websocket
WSS: secure websocket
TLS: transport layer
security (secure TCP using a certificate for your server domain)
HTTPS: secure HTTP
provided by TLS
SIP server: VoIP server,
softswitch or IP PBX capable to understand the SIP protocol
WebRTC server: VoIP
server, softswitch or IP PBX capable to understand the WebRTC protocol
WebRTC gateway: a
software or service which can convert from WebRTC to SIP and inverse, usually
implemented as a proxy, gateway or SBC
JS WebRTC SIP library /
WebRTC engine: the webphone acting as a WebRTC client (websocket for the SIP
signaling, DTLS/SRTP for the media)
Native NS or Java engine:
the webphone acting as a native SIP client (UDP, TCP or TLS for the SIP
signaling, plain RTP or SRTP for the media)
SIP proxy: SIP protocol
relay at the network edge implemented as proxy, gateway or SBC
ASR: average success
ratio (percent of the connected calls)
ACD: average call
duration. The same as ACL
ACL or ACD: average call
length. (ACD is sometime also used for Automatic Call Distributor)
TCP: is a connection-oriented
internet protocol
UDP: internet core
protocol for datagram packets (not reliable)
REGISTRAR: server-side
component that allows SIP REGISTER requests (registrar server)
ANI / CLI: Automatic
Number Identification or Caller Line Identification
IVR: Interactive Voice
Recognition
SMS: short messaging
service usually provided by mobile carriers (the closest term in SIP is chat
SIP messages)
How to set the webphone parameters dynamically?
The easiest way to
specify parameters for the webphone is to just enter them in the
webphone_config.js file.
However if you need to
integrate the webphone with your server (for example with a CRM) you might have
to set different parameters regarding the session (for example different user
credentials based on the currently logged-in user). There are 3 ways to do
this:
1.
With the client side JavaScript
using the webphone setparameter
API (get the parameters from you webapp or via ajax requests)
2.
Just generate the URL (iframe or link) dynamically from your server side
scripts with the parameters set as required (wp_username, wp_password and other
URL parameters).
3.
Set the “scurl_setparameters” setting to point to your server side http api which
will have to return the details once called by the webphone.
This
will be called before onAppStateChange “started” event and can be used to
provision the webphone from server API. The answer should contain parameters as
key/value pairs, ex: username=xxx,password=yyy.
See the beginning of the parameters section for all other possibilities.
Errors in the
browser console
There are a few common
operations done by the webphone which might trigger an error or warning line in
the browser console which can be safely ignored if otherwise your webphone
works correctly.
The most frequent errors
are the followings:
ERROR
and WARNING messages
If you set the
loglevel higher than 1 than you will receive messages that are useful only for
debug.
Most
of ERROR and WARNING message cannot be considered as faults in this case.
Some
of them will appear also under normal circumstances and you should not take
special attention for these messages.
If there are any
issue affecting the normal usage, please send the detailed logs to Mizutech
support (webphone@mizu-voip.com) in a text file
attachment.
nsX.webvoipphone.com connectivity
errors
The
nsX.webvoipphone.com points to localhost (127.0.0.1) and it is used by the
webphone to communicate with the local NS engine if any.
In the
logs you might notice errors like:
POST https://ns4.webvoipphone.com:10433
net::ERR_CONNECTION_REFUSED.
or
WebSocket connection to
'wss://ns4.webvoipphone.com:10443/msstwebsock' failed: Error in connection
establishment: net::ERR_CONNECTION_REFUSED
This is
a normal error condition if you are not using the NS engine as at startup the
webphone might try to detect the presence of the local NS engine by trying to
connect to this URL.
You
might also see CORS issues like this:
Cross-Origin Request Blocked:
The Same Origin Policy disallows reading the remote resource at
https://127.0.0.1:18520/extcmd_test.
(Reason: CORS request did not succeed)
These
can be also safely ignored as the webphone will try to connect to the local NS
engine by domain name or via websocket.
Uncaught TypeError: webphone_api.xxx
is not a function errors
This
usually happens if you try to access the webphone API before the webphone was
fully loaded.
Make
sure to call any API only after the onAppStateChange callback “loaded” event was triggered.
“empty-block” statements related
warnings in JSLint
Our
build stacks automatically removes some unneeded code at built time. These
warnings can be safely ignored.
AbortError: The fetching process for
the media resource was aborted by the user agent at the user's request.
Firefox sometimes throws an AbortError when an audio/video
stream is attached to an <audio>/<video> HTML element.
This is an internal Promise failing in Firefox and is logged in browser
console.
This error can be ignored and it doesn’t affect any functionality.
Deprecation warnings
Our goal is to be compatible with all possible browsers,
including old versions.
For this reason we are using also deprecated tag which might trigger a browser
warning but otherwise are omitted.
Usually
all these warnings can be safely ignored and they doesn’t affect the webphone
functionality.
RTP
warning
The webphone will send a few (maximum 10)
short UDP packets (\r\n) to open the media path (also the NAT if any).
For this reason you might see the following or similar Asterisk log entries:
“WARNING[8860]: res_rtp_asterisk.c:2019
ast_rtp_read: RTP Read too short” or “Unknown RTP Version 1”.
or “codec_opus.c:503 opus_samples_count:
Opus: Unable to parse packet for number of samples: corrupted stream”
These packets are simply dropped by Asterisk which is the expected behavior.
This is not a webphone or Asterisk error and will not have any negative impact
for the calls. You can safely skip this.
You might turn this off by the
“natopenpackets” parameter (set to 0). You might also set the “keepaliveival”
to 0 and modify the “keepaliveival” (all these might have an impact on the
webphone NAT traversal capability).
All of the above can be
usually ignored. If you see other errors and the webphone doesn’t work as
expected, please contact our support by sending the browser console output as
email text file attachment. Make sure that the console output was generated with
the webphone loglevel parameter set to 5.
In short:
Make sure that the
webphone loglevel parameter is set to 5 in the webphone_config.js file. Then reproduce
the problem and sent the full content of your browser console by email to webphone@mizu-voip.com as a text file attachment with an accurate problem
description in English (including What you did? What happened? What was
expected to happen?).
Details:
The webphone can generate
detailed logs for debugging purposes.
For this just set the “loglevel” setting to 5 (or enable logs from the user
interface if any).
Note: by default the loglevel is already set to 5 (on) in
demo and trial versions and we usually send out licensed builds with loglevel 1
(off) by default.
Once enabled, you can see
the logs in the browser console or in the softphone
skin help menu (if you are using this GUI). If the Java engine is being used,
then the logs will appear also in the Java console. You might also use the API:
getlogs() or the onEvent(callback) with “log” type events.
When contacting Mizutech
support with any issue, please always attach the detailed logs: the full output
of the browser console (or you can find the same from the softphone skin help
menu if you are using the softphone.html).
On Firefox and Chrome you
can access the logs with the Ctrl+Shift+J shortcut (or Cmd+Shift+J on a Mac). On Edge and
Internet Explorer the shortcut key is F12. In some browsers this is found under
a “Developer Tools” or similar menu, “Console” tab. See this
page for more help if you still
can’t find the browser console.
Make sure to include the
logs from the very beginning (select and copy all text) as we need to check
your environment and settings which is written at startup.
If there are multiple
calls in the logs but not all of them has the issue you described, then please
specify the SIP Call-ID of the problematic call or much better if you send a
log with only a single call to avoid confusions.
Avoid sending recordings
or screenshots. We always need detailed logs only and a detailed and exact
issue description.
When sending logs to
Mizutech support, please attach them as files (don’t insert in email body).
In some circumstances you
might have to send logs from the specific webphone engine as described below.
HTML/JavaScript logs
You
can get this from the browser console as described above.
iOS/Safari browser
console
In
case if you need to access the Safari browser console from an iPhone, follow this guide.
Here
is an iOS specific wiki.
Firefox browser console limitation
Firefox by default trims
the console logs to 200 lines.
To increase this limit
type config into the address bar and search for "loglimit" and
increase every value to 5000.
WebRTC engine detailed
logs
If
the webphone is using the WebRTC engine then the browser console output will
contain the most important logs.
If
you are using the softphone skin, then better if you check the logs from the
skin help menu because the number of lines are limited in the browser console.
If
you have voice issues (no voce, one side voice, delays) then you should get a
detailed log:
With Firefox this can be done by navigating to webrtc.
With Chrome this can be done by navigating to chrome://webrtc-internals
For
more internal details, you might enable WebRTC tracing:
With Chrome this can be done by launching it like:
"C:\Program Files
(x86)\Google\Chrome\Application\chrome.exe" --enable-logging --v=4
--vmodule=*libjingle/source/talk/*=4 --vmodule=*media/audio/*=4
Then you can find the logs at: C:\Users\USER\AppData\Local\Google\Chrome\User
Data\chrome_debug.log
(replace USER with your windows username or rewrite the
path to match your user directory)
Java engine detailed
logs
If
the webphone is using the Java engine, then a log window will appear if the
“loglevel” is set to “5” and the “canopenlogview” to “true”.
Grab
the logs also from this log window (Ctrl+A,
Ctrl+C, Ctrl+V) or from the Java console.
NS engine detailed logs
on Windows
If
the webphone library is using the NS engine on Windows, then some more detailed
logs can be obtained from:
C:\Program Files (x86)\WebPhone_Service\WebPhone_Servicelog.dat
and
C:\Program Files
(x86)\WebPhone_Service\content\native\mwphonedata\webphonelog.dat.
The folder name might contain your brandname instead of “WebPhone”
such as YourBrand_Service. In this case the
C:\Program Files (x86)\YourBrandName_Service will be the default data directory or it might be
different on your PC.
It
might be located in the C:\Users\USER\AppData\Roaming\WebPhone_Service
directory if the account doesn’t have write access to Program Files).
If
there is no *log.dat file, just send the “wphoneout.dat” or
send
all the *.dat files from the NS folder and
it’s subfolders if you are not sure (from both the app directory and from /content/native/mwphonedata folder).
NS
engine install related logs (relevant only if install fails) can be found at: C:\Users\USER\AppData\Local\Temp\i4j_nlog_*
Ideally
you should stop the webphone service before to grab the logs (from cmd command
line: net stop Webphone).
You can restart it after you copied the logs with the “net
start Webphone” command.
NS engine Linux logs
The
NS engine logs can be found usually at: /opt/WebPhone_NS/mwphonedata (rarely it might be located at /home/username/mwphonedata)
Install
related logs can be found at: /opt/WebPhone_NS/installog.dat (useful if install fails, NS service can’t start or the
webphone can’t connect to it)
NS engine MacOS logs
The
NS engine logs can be found at: /home/username/mwphonedata
or at: /Applications/WebPhone_NS/mwphonedata
Server side logs
If the problem is triggered by your
SIP server, you should look after the reason in the server log first. Make sure
to increase your server log/debug/trace level to maximum to also include the
SIP signaling.
Working with logs
Logs are generated to help you in
troubleshooting.
To understand the log
files, you need some basic SIP protocol understanding. Here are some basic message flow examples.
In case if the
softphone doesn’t connect or register, look for WebSocket (ws/wss) connectivity
issues or register issues (search for “REGISTER sip”).
In case if there is some
call related problem, find the call in the log (search for “INVITE sip”) and
then go trough the call by searching after the Call-ID field what you found in
the first INVITE.
If your server
disconnected/rejected the call or the registration, then check your server log
about the same call or registration.
If the problem is not obvious, send
the relevant logs to mizutech support.
How to find which engine was used?
To find all engine related log, like
which engines are supported, selected/recommended engine, just search for
"engine".
Also, before every engine start, all
the engine priorities are logged, search for: "enginepriority"
To find out which engine was actually
started, search for: "start engine:" in the browser console output.
If WebRTC engine is selected, how to find the websocket URL,
sip server and ice settings?
Search for: "Webrtc connection
details:". There you will find all the above details.
“Send
log to support” functionality
The
softphone skin (softphone.html) has a “Send log to support” option in its main
menu where users can comfortably upload log if they encounter any issue.
This
is a simple HTML form, which sends a POST request to a specified URL. By
default this is sent to Mizutech support.
You
can completely remove this functionality or rewrite the target URL to yours:
-"logform_action"
(String) the action URL of the form where the POST request is sent
-"logform_filename"
(String) this will set the "filename" hidden input parameter of the
form. This filename can be used to save the log file on server side.
Note:
you need to write a small server side scripts to handle the POST and save it to
file for this functionality to work.
Sending logs to MizuTech technical
support:
o Always generate the logs with the
loglevel parameter set to 5 (set this in the webphone_config.js file)
o Send the full log, which includes both
the webphone startup and the problematic session. If the problem is call
related, then make sure that the log contains also the disconnect of your call.
o Make your session as short as possible
reproducing the problem (for example only one call if possible).
o If your log contains multiple calls
then make it clear which one is the problematic one (send it's SIP Call-ID
and/or make sure that it is the very last call in your log)
o Send the log as email attached file
(not as screenshot or copy-pasted to email body)
Homepage: https://www.mizu-voip.com/Software/WebPhone.aspx
Download: https://www.mizu-voip.com/Portals/0/Files/webphone.zip
Pricing: https://www.mizu-voip.com/Support/Webphonepricing.aspx
Contact: webphone@mizu-voip.com
Copyright ©
2008-2024 Mizutech SRL