Mizu WebPhone

v.2.9. May 28, 2019

 

Contents

About 2

Usage. 2

Steps. 2

Web Softphone. 3

Click-to-call 4

Developers. 4

Designers. 4

Features, technology and licensing. 4

Feature list 4

Requirements. 5

Technical details. 5

Licensing. 7

Integration and customization. 8

Concepts. 8

User interface Skin/Design. 9

Web Dialer/Softphone. 10

Click to call 12

Custom solutions. 15

Integration with Web server side applications or scripts. 15

Integration with SIP server side applications or scripts. 17

Development 17

Parameters. 20

SIP account settings. 22

Engine related settings. 24

Call divert and other settings. 38

User interface related settings. 46

Parameter security. 51

JavaScript API 52

About 52

Basic example. 52

Functions. 53

Events. 61

FAQ.. 68

Resources. 109

 

About                                      

The Mizu WebPhone is a universal SIP client 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 (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 library via its API.

The provided user interfaces are implemented as simple HTML/CSS and can be fully customized, modified, extended or removed/replaced.

Usage                                      

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 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.

 

In short:

Just copy the webphone to your webserver (or test it from your local file system) and configure it like you do with a usual SIP client such as an IP Phone or softphone like X-Lite. A quick tutorial can be found here.

 

Setup

1.       Download

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.

2.       Deploy

You can find the requirements here which need to be fulfilled to be able to use the webphone.

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, .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). Chrome and Opera 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.

Alternatives:

o    You can also test it without a webserver by launching the html files from your desktop, although some engines might not work correctly this way

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)

·          Regarding private SIP servers while running the webphone on MAC or Linux:

o    If you wish to test by running the webphone on a Linux or MAC browser and your SIP server is on local LAN (with a private IP) then you might need local WebRTC capabilities for the WebPhone to work.

o    Otherwise:

§   if your SIP server is on public internet and your webpage is hosted on HTTPS, then WebRTC is always available (in case if the NS or Java engine can’t be used)

§   on Windows the NS engine is always available (in case if the WebRTC or Java engine can’t be used)

3.       Settings

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_api.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_api.js file.

 

4.       Integrate

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 library (if you are a JavaScript developer)

 

5.       Design

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.

6.       Launch

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_api.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 library

 

More details:

·         Webphone file list

·         Customization

·         How it works?

·         Quick webphone tutorial

 

Web Softphone

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_api.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_api.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.

 

Click-to-call

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_api.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

Developers can use the webphone as a JavaScript library to create any custom VoIP solution integrated in any webpage or web application.

Just include the "webphone_api.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.

 

Designers

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 “parameters” section at the top at the webphone_api.js file.

 

Features, technology and licensing

The WebPhone is a cross-platform SIP client 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).

 

Feature list

·         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): Java applet, WebRTC, NS (Native Service or Plugin), 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: 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: PCMU, PCMA, G.729, GSM, iLBC, SPEEX, OPUS (including wide-band HD audio)

·         Video codec: H.263, H.264 and VP8 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, barge-in (with NS)

·         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 library

·         Stable API: new releases are always backward compatible so you can always upgrade to new versions with no changes in your code

·         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

 

 

Requirements

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) , Linux, MAC OSX, Android, iOS (app only), 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.

 

Technical details

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.

 

 

 

 

 

 

 

 

 

Engines

NS

Our native VoIP engine implemented as a native 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).

Pros:

·          All features all supported, native performance

Cons

·          Requires install (one click installer)

 

WebRTC

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.

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)

Flash

A browser plugin technology developed by Adobe with its proprietary streaming protocol called RTMP.

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

 

Java Applet

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).

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

 

App

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.

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)

 

P2P and callback

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.

Native Dial

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: Java, WebRTC, NS and Flash. The other engines are to provide support for exotic and old browsers maximizing the coverage for all OS/browser combinations ensuring that enduser has call capabilities regardless of the circumstances.

API

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.

 

GUI

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.

 

Licensing

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 domain(s). 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. 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 license 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

Demo version

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  (usually 2 or 3 months)

·         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.

On request we can also provide test builds with only trial period limitation (will expire after ~3 weeks of usage) and without the above demo limitations.

See the pricing and order your licensed copy from here.

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).

 

Concepts

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, jQuery 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 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)

Quick/Basic skin change

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.

Advanced skinning

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 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

 

 

Web Dialer/Softphone

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).

Possibilities

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_api.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.

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  "j$".

 

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:  j$.mobile.changePage("#PAGE_ID", { transition: "none", role: "page" });

 

Example:  j$.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:  j$.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_api.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 onLoaded callback has been fired.

webphone_api.onLoaded(function ()

{

        webphone_api.onCallStateChange(function (event, direction, peername, peerdisplayname, line)

        {

                //handle any events here. For example to catch the call connect events:

                if (event === 'callConnected')

                {

                        //add your code here

                }                

        });

});

 

 

You can find a similar example of webphone API usage in /samples/basic_example.html.

 

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.

 

 

Click to call

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 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_api.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_api.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 onLoaded() or from the onRegistered() callback.

 

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 onLoaded 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.

 

 

Custom solutions

The most common use case for the webphone is as 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 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_api.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 (AJAX) 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 "onStart" event(url) 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.

 

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).

Integration with third party systems and CRM’s

You can use the webphone library to implement your custom click-to-call solution or use one of the skin templates for click to call.

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_api.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

·         PHP: we are currently working on a few PHP examples and it will be available with the upcoming new release

·         Others: We will extend this list with upcoming new versions. Please let us know if you have some code to share with us.

 

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.

 

Development

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 library) to create any custom VoIP solution, standalone or integrated in any webpage or web application.

Setup

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.

 

Regarding private SIP servers while running the webphone on MAC or Linux:

If you test from Linux or MAC and your SIP server is on local LAN (with a private IP) then you might need local WebRTC capabilities for the WebPhone to work.

Otherwise:

-if your SIP server is on public internet and your webpage is hosted on HTTPS, then WebRTC is always available (in case if the NS or Java engine can’t be used)

-on Windows the NS engine is always available (in case if the WebRTC or Java engine can’t be used)

 

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_api.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).

 

jQuery:

jQuery namespace within the webphone is changed from "$"  to  "j$"

 

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.

API

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 onLoaded callback was fired).

Work-flow

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_api.js file parameters section (you can find this at the top of the 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

Usage

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_api.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).

Simple example

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.onLoaded(function () {

 

                                //Set parameters (Replace upper case worlds with your settings)

//Alternatively these can be also preset in your webphone_api.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>

 

Other examples

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)

Advanced functions

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 onEvents 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.

Parameters


The parameters can be used to customize the user interface or control the settings 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_api.js" file, under "parameters" variable (in "parameters" Javascript object at the beginning of the file)

·         Use the setparameter() API call from JavaScript (Other function calls might also change settings parameters)

·         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 "onStart" 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 which might overwrite server side settings loaded from the webphone_api.js file)

·         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_api.js file. For example:

var 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_api.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_api.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.

·         If you set the parameters in the webphone_api.js file, make sure to add a comma after each parameter line except the last one.

·         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_api.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_api.js?jscodeversion=1234"></script>

·         Prefix parameter name with “ucfg_” if it should prefer client side settings (otherwise server side settings defined in the webphone_api.js will overwrite the client settings). Example: ucfg_aec: 2

·         You might 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.

 

Important settings

The most important parameters are the followings:

·         serveraddress (your SIP server domain or IP:port, usually set statically in the webphone_api.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.

 

SIP account settings

Credentials and other basic SIP parameters:

serveraddress

(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 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

 

username

(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_api.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    For maximum compatibility with third-party software and services, avoid using special and non-ASCII characters.

 

sipusername

(string)

This is the username used for SIP digest authentication (Auth User 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.

Default value is empty.

 

See more details here and here.

password

(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 passord will not be asked from the enduser at login.

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

displayname

(string)

Optional SIP display name.

Specify default display name used in “from” or “contact” SIP headers.

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.

realm

(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)

proxyaddress

(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.

register

(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.

registerinterval

(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).

 

Engine related settings

Library, engine, transport, SIP, media, DTMF, presence and BLF related settings:

engine priority

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 avoid WebRTC engine, just set: enginepriority_webrtc: 1

 

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 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.

 

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!

webrtcserveraddress

(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

wss://subdomain.mydomain.com:80/anypath

ws://10.20.30.40:5065

wss://asterisk.mydomain.com:8088/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 Chrome and Opera require secure websocket (wss). 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.

rtmpserveraddress

(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.

 

stunserveraddress

(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”).

 

turnserveraddress

(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.

turnparameters

(string)

Any TURN URI parameter.

Example: transport=tcp

turnusername

(string)

Username for turn authentication.

turnpassword

(string)

Password for turn authentication.

ice

(string)

Instead of using the above STUN and TURN parameters, you can use this parameter in the following format:

ice: ‘[{ url: 'stun:stun.l.google.com:19302'}, { url:'turn:user@myturnserver.com', credential:'myPassword'}]’

(You can also set multiple STUN and TURN servers if you wish)

A list of public stun servers can be found here.

(There is no need for any ice configuration if you are using the mizu gateway or server as TURN/STUN is built-in and discovered automatically)

icetimeout

(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).

stunturnonlocal

(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

use_rport

(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)

(Usually use_rport and use_fast_stun should have the same value set)

Default is 1

 

upnpnat

(number)

Nat traversal via UpNP supported routers.

0: disable

1: enable

Default is 1

 

use_fast_ice

(number)

Fast ICE negotiations (for p2p rtp routing):

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 the stun should not be disabled

 

use_fast_stun

(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 (recommended)

2=use only for symmetric NAT

3=always

4=use even on public IP

Change if you have NAT issues (depending on your server type and settings)

(Usually use_fast_stun and use_rport should have the same value set)

Default is 1

autodetectwebrtc

(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.

 

android_nativedialerurl

(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).

ios_nativedialerurl

(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).

accessnumber

(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.

 

callbacknumber

(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.

useragent

(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.

customsipheader

(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 (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)

autoprovisioning

(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

checkmicrophone

(number)

Specify whether calls should fail or succeed also without a microphone device.

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 will be displayed for the user)

2: yes (calls will fail if user doesn’t have a microphone device)

Default is 1.

usecommdevice

(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.

checkvolumesettings

(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

allowsipuriasusername

(number)

Used for SIP user name normalization.

0: No: if username is a SIP URI, then the webphone will remove the domain and save only the username part

1: Yes: will not touch the entered user name

Default is 0.

backgroundcalls

(number)

Enable background call listener.

If the WebRTC engine is used, this means push notifications.

If you are using the NS engine, 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: no (disabled)

1: yes (enabled)

Default is 0.

 

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 pushnotifications parameter to 0 (possible values: -1: auto, 0: no, 1: yes).

 

Here you can read more details about VoIP push notifications.

 

transport

(number)

Transport protocol for native SIP.

-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.

 

Note:

-for SIPS TLS/SRTP you should set also the mediaencryption parameter

-these settings will not affect WebRTC since its transport is controlled by the browser: http/https, websocket/secure websocket (ws/wss) and always encrypted media (DTLS/SRTP).

localip

(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)

signalingport

(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)

p2psignaling

(number)

Specify to enable (1) or disable (0) peer to peer signaling routing feature.

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 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.

Default is 1 (p2p for signaling enabled and used when possible).

p2prtp

(number)

Specify to enable (1) or disable (0) peer to peer media routing feature. This is a feature specific to Mizu webphones and it is independent of the SDP negotiations.

You might set to 0 (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).

 

rtpport

(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)

keepaliveival

(number)

NAT keep-alive packet send interval in milliseconds.

Set to 0 to disable.

Default value is 28000 (28 sec)

 

wskeepaliveival

 (number)

Keep-alive interval for the WebRTC websocket in milliseconds.

Set to 0 to disable.

Default value is 30000 (30 sec)

sendrtponmuted

(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.

mediaencryption

(number)

Media encryption method

-1: auto guess (auto set to 1 if TLS)

0: not encrypted (default)

1: auto (will encrypt if initiated by other party)

2: SRTP

Default is -1.

 

Note:

-With SRTP it is recommended to also set the signaling transport to TLS.

-This will not affect WebRTC since WebRTC always uses DTLS/SRTP for the media.

dtmfmode

(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

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

 

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 formats (no In-Band DTMF processing)

o    WebRTC might not honor the dtmfmode settings (as this is handled by the browser in case of WebRTC)

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    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    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.

 

playdtmfsound

(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.

earlymedia

(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.

prefcodec

(string)

Set your preferred audio codec. Will accept one of the followings: pcmu, pcma, g.711 (for both PCMU and PCMA), g.719, gsm, ilbc, speex, speexwb, speexuwb, opus, 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.

 

codec

(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_opus: 0, use_opuswb: 0, use_opusuwb: 0, use_opusswb: 0, use_ilbc: 0, alwaysallowlowcodec: 0

vcodec

(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)

 

Note: WebRTC has support only for H.264 and VP8 from common browsers so you should not disable these codec’s.

video

(number)

Enable/disable video.

                -1: auto (default)

0: disable

1: enable

2: force always

 

Note:

-If you are using the webphone with a custom skin, 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>

-The WebRTC engine is required for video to work (the webphone will handle this automatically by switching to WebRTC on video request if it is available)

audio_bandwidth

(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.

video_bandwidth

(number)

Max bandwidth for video in kbits.

It will be sent also with SDP “b:AS” attribute.

Default is 0 which means auto negotiated via RTCP and congestion control.

video size parameters

(number)

You can suggest the size of the video (in pixels) with the following parameters:

·         video_width

·         video_height

·         video_min_width

·         video_min_height

·         video_max_width

·         video_max_height

 

screensharing

(number)

Enable/disable screen sharing:

0=No (default)

1=Auto (if supported by the platform)

2=Yes (always force)

Default is: 1

 

Softphone skin users: If the screensharing is set, a screen share button will appear on the softphone user interface.

Note: screen sharing is still an experimental feature in WebRTC standards and you might need a browser extension to enable it.

You might also need the followings:

Chrome: start the browser with --enable-usermedia-screen-capturing flag

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

codecframecount

(number)

Number of payloads in one UDP packet.

By default it is set to 0 which means 2 frames for G729 and 1 frame for all other codec.

plc

(boolean)

Enable/disable packet loss concealment

Default is true (enabled)

vad

(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:

-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 and API_VAD for more details.

-If you want to disable audio related notifications (microphone warning on no signal detected) then set the “enablenomicvoicewarning” parameter to 0

aec

(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.

aec2

(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.

agc

(number)

Automatic gain control.

0=Disabled

1=For recording only

2=Both for playback and recording

3=Guess

Default value is 3

silencesupress

(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)

denoise

(number)

Noise suppression.

0=Disabled

1=For recording only

2=Both for playback and recording

3=Auto guess

Default value is 3

jittersize

(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

enablepresence

(number)

Enable/disable presence.

Possible values:

0: disable presence

1: auto (if presence capabilities detected)

2: always enable / force

 

Default is 1.

 

presenceuserlist

(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.

enableblf

(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.

blfuserlist

(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.

 

minserviceversion

(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: completely disable asking for upgrades

-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.2.9.19055 engine executable which was shipped with webphone v.2.9 is 29 (so you might set the “minserviceversion” setting to 29 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

nsupgrademode

(number)

Set how/when to upgrade the NS engine.

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

extraregisteraccounts

(boolean)

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.

autostart

(boolean)

Specify whether the webphone stack should be started automatically on page load.

If set to false 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().

Default is true.

Note: you can set this to false to prevent the auto initialization of the webphone, so you might delay this until actually the user wish to interact with your phone UI (such as pushing your click to call button)

 

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.

needunregister

(boolean)

Set to false to prevent unregister messages to be sent (for example to prevent unregister on web page reload).

Default is true.

 

destroyonpageclose

(number)

Specify what to do on close/refresh.

0: no (do nothing, will not close current call and will not unregister)

1: disconnect current calls

2: disconnect and unregister 

Default is 2

 

resetsettings

(boolean)

Set to true to clear all previously stored or cached settings on startup.

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.

profile

(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 location full path).

extra webrtc options

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.

loglevel

(number)

Tracing 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 5 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.

logtoconsole

(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:

 

callto

(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.

autoaction

(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).

 

voicemailnum

(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).

normalizenumber

(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:

0: no, don’t normalize

1: yes, normalize (default)

 

techprefix

(string)

Add any prefix for the called numbers.

Default is empty.

numpxrewrite

(string)

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.

blacklist

(string)

Block incoming communication (call, chat and others) from these users. (username/numbers/extensions separated by comma).

Default value is empty.

callforwardonbusy

(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.

callforwardonnoanswer

(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.

callforwardalways

(string)

Specify a number where ALL incoming calls should be forwarded.

Default is empty.

calltransferalways

(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.

autoignore

(number)

Set to ignore all incoming calls.

0: don’t ignore

1: silently ignore

2: reject

Default value is 0.

autoaccept

(boolean)

Set to true to automatically accept all incoming calls (auto answer).

Default value is false.

 

Note: the calls are also auto accepted if the received INVITE contains the “x-p-auto-answer: normal" or "x-answer-mode: auto” SIP header.

acceptcall_onsharedevice

(number)

Specify whether to auto accept incoming calls when the user clicks to enable device sharing for WebRTC (the audio device permission browser popup)

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 (Auto accept when possible –if detected share device click)

2: always (Always accept webrtc call on browser share device click)

Default is 1.

beeponincoming

(number)

Will play a short sound on incoming calls.

0: No

1: Yes

Default value is 0

Note: this is not the ringtone.

beeponconnect

(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

redialonfail

(number)

Retry the call on failure or no response.

0: no

1: yes

Default value is 1.

rejectonbusy

(boolean)

Set to true to automatically reject (disconnect) incoming call if a call is already in progress.

Default value is false.

disablesamecall

(number)

Specify whether to enable (possible accidental) outgoing call to a number where there is already a call in progress.

This might happen as a result of API misuse or by user double-click on the call button.

Set to 1 to reject such kind of second call.

Set to 0 to disable this verification and enable all calls.

Default is 1.

allowcallredirect

(number)

Set to 1 to auto-redial on 301/302 call forward.

Set to 0 to disable auto call forward.

Default value is 1.

 

holdtype

(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

 

defmute

(number)

Default mute direction:

0: both

1: mute out (speakers)

2: mute in (microphone)

3: both

4: both

5: disable mute

muteholdalllines

(number)

Auto Mute/Hold all call legs on conference calls.

0=no

1=yes

Default is 0.

automute

(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 other line button click

Default is 0

autohold

(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 other line button click

Default is 0

audiodevicein

(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.

 

audiodeviceout

(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.

 

audiodevicering

(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.

 

volumein

(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.

 

volumeout

(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.

volumering

(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: there is no separate ring device for WebRTC (this is not a webphone limitation, but current browsers doesn’t expose such functionality for WebRTC)

 

androidspeaker

(number)

Control the default playback device on Android phones and tablets.

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 before after first call

3: switch to speakerphone at start

 

Default: 1

transfertype

(number)

Specify transfer mode for native SIP.

-1=default transfer type (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)

 

Default is -1 (which is the same as 6)

 

Note:

·          Unattended means simple immediate transfer (just a REFER message sent)

·          Attended transfer means that there will be a consultation call first

·          If you have any incompatibility issue, then set to 1 (unattended is the simplest way to transfer a call and all sip server and device should support it correctly)

·          Only unattended/blind transfer is supported between SIP and WebRTC (if one endpoint is using native SIP while the other is on WebRTC)

transfwithreplace

(number)

Specify if replace should be used with transfer so the old call (dialog) is not disconnected but just replaced.

This way the A party is never disconnected, just the called party is changed. The A party must be able to handle the replace header for this.

-1=auto

0=no (will create a separate call)

1=yes  (smooth transfer, but not supported by some servers)

Default is -1

 

changesptoring

(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)

ringtimeout

(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.

calltimeout

(number)

Maximum speech time allowed in millisecond.

Default is 10800000 (3 hours)

mediatimeout

(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)

 

bargeinheader

(string)

You can barge-in or spy on the calls by sending a specific SIP header specified by the “bargeinheader” parameter available for NS and Java engines.

For example if you specify the value as “X-barge: yes”, then when your server sends this in the INVITE, the call will be auto-accepted and hidden joining a conference with all calls made by the user/agent.

Default is empty (disabled).

voicerecupload

(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

 

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

 

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_2019_03_12_xxx.mp3 HTTP/1.1

Host: yourdomain.com

User-Agent: webphone

Accept: */*

X-type: fileupload

X-filename: callrecord_2019_03_12_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_2019_03_12_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, NodeJS, Java.

 

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)

·         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

·         If you are 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).

 

 

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)

brandname

(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.

companyname

(string)

Your company name to be displayed in the about box and various other places.

Default is empty.

logo

(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.

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.

colortheme

(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.

language

Set the language for the user interface.

Two character language code (for example en for English or it for Italian).

More details about localization can be found in the FAQ.

featureset

(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.

showserverinput

(number)

This can be used to hide the server address setting from the user if you already preconfigured the server address in the webphone_api.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)

 

useloginpage

(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

chatsms

(number)

0: Auto guess or Ask

1: SMS only

2: Chat only

Default is 0.

showincomingchatas

(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.

conferencerooms

(number)

Enable/disable conference room feature.

0: disabled

1: enabled (via SIP MESSAGE and REFER)

2. enabled (via SIP MESSAGE)

3. enabled (via SIP REFER)

Default is 1.

Note: call conferencing is always available with the NS and Java engines (since these are using a local RTP mixer), however with the WebRTC engine the conferencing feature will be disabled if you set this parameter to 0.

callparknumber

(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.

hasringcounter

(boolean)

Enable/disable the time counter during ring-time.

hasfiletransfer

(boolean)

Set to true to enable file transfer.

filetransferurl

(string)

HTTP URI used for file transfer. By default Mizutech service is used which is provided for free with the web softphone.

displaynotification

(number)

Show notifications in phone notification bar (usually on the top corner of your phone).

0:Never

1:On event

2:Always

Default is 1.

displayvolumecontrols

(boolean)

Always display volume controls when in call.

Default is false.

displayaudiodevice

(boolean)

Always display audio device when in call.

Default is false.

displayvideodevice

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.

displaypeerdetails

(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

savetocontacts

(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.

messagepopup

(string)

Display custom popup for user once.

Default is empty.

 

showtoasts

(boolean)

 

Enable/disable hint popups.

Possible values:

true: show all toasts (default)

false: don't show toasts and popup messages

 

incomingcallpopup

(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

 

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 backgroundcalls parameter to true to catch incoming calls even when the webphone is not running.

Default is 1.

 

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.

closecall_timeout

(number)

The call page will remain active after 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)

header

(string)

Header text displayed for users on top of softphone windows.

Default is empty.

footer

(string)

Footer text displayed for users on the bottom of softphone windows.

Default is empty.

version

(string)

Version number displayed for users.

Default is empty (will load the built-in version number)

showsynccontactsmenu

(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

defcontacts

(string)

Set one or more contacts to be displayed by default in the contact list.

Name and number separated by comma and contacts separated by semicolon:

Example: defcontacts: 'John Doe,12121;Jill Doe,231231'

disableoptions

(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,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

extraoption

(string)

Custom parameters can be set in a key-value pair list, separated by semicolon Ex: displayname=John;

Default is empty.

logsendto

(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)

links

(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

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: onLoad, onStart, callSetup, callRinging, callConnected, callDisconnected, 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. 

 

Parameter security

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).

 

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)

 

Make sure to never hardcode the password into your website (It should not 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)

-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)

-instead of password, use the MD5 and the realm parameters if possible (and this can also passed in encrypted format to be more secure)

-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

-for parameter encoding (encryption/obfuscation) you can use XOR + base64 with your built-in key (ask from Mizutech), prefixed with the “encrypted__3__” string  (you can verify your encryption with this tool using selecting XOR Base64 Encrypt)

-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 some details about mizu VoIP server security.

 

JavaScript API

About

You can use the webphone javascript 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.

 

Basic 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.onLoaded(function () {

 

                                //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.

Functions

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_api.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 by the webphone so they will persist (except if you clear the browser storage and/or cookies).

You can easily clear previously set values using the delsettings () API or by using the setparameter with an empty value.

For example setparameter(‘displayname’,’’);

 

getparameter (param)

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

 

 

start()

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 “false” 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.

 

stop()

Optionally you can "stop" the webphone engine (but this is done automatically on browser close or refresh, so not really needed). Calling the stop() API will also unregister.

 

 

register ()

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)

registerex (accounts)

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.

 

unregister ()

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.

 

call (number)

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.

The number parameter must be a string type!

 

videocall (number)

Initiate a video call to a number, extension, sip username or SIP URI.

 

The WebRTC engine is required for video to work (the webphone will handle this automatically by switching to WebRTC on video request if it is available).

Will failback to a simple voice call if you don’t have a camera device or 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.

If the webphone is used as SDK (not via the “softphone.html”) and video feature have to be used, then you will have to add the following <div> element to your page as the container of the video that will be displayed:

<div id="video_container"></div>

 

The number parameter must be a string type!

 

screenshare (number, screenid)

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)

 

Notes:

o    The number parameter must be a string type!

o    Special permissions might be needed. See also the screensharing parameter for details.

 

hangup ()

Disconnect current call.

 

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.

 

accept ()

Connect incoming call.

 

reject ()

Disconnect incoming call.

(You can also use the hangup() function for this)

 

ignore ()

Silently ignore incoming call.

 

forward (number)

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).

The number parameter must be a string type!

 

hold (state)

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 (state, direction)

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)       

 

mutevideo (state, direction)

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

 

stopscreenshare ()

Stop screen sharing.

 

 

transfer (number)

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 and there are 2 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).

The number parameter must be a string type!

 

conference (number, add)

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:

-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)

-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. More details here.

-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)

-the number parameter must be a string type!

 

 

dtmf (msg)

Send DTMF message by SIP INFO or RFC2833 method (depending on the "dtmfmode" parameter).

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.

Example:

API_Dtmf(-2,"1");

API_Dtmf(-2," 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.

 

sendchat (number, msg)

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.

 

sendsms (number, msg, from)

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.

 

voicerecord (start, url)

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.

 

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).

 

devicepopup ()

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: 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 as-is.

 

getdevice(dev, callback)

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.

Note: WebRTC doesn’t support a separate ringer device at this moment (This is a browser limitation)

 

setdevice(dev, devicename, immediate)

Select an audio device. The devicename should be a valid audio device name (you can list them with the getaudiodevicelist() call)

For the “dev” parameter pass:

0: for recording device

1: for the playback device

2: for ringer device (Will be skipped if the engine is WebRTC and will use the playback device also for ring)

3: for video camera

The "immediate" parameter can have the following values:

0: default

1: next call only

2: immediately for active calls

getvolume(dev, callback)

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).

 

setvolume(dev, volume)

Set volume (percent for the selected device. Default value is 50% -> 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.

-A separate volume for ring is not supported on WebRTC

 

setsipheader(header)

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’);

·          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)

Call this function passing a callback.

Example: getsipheader(“Contact”,mycallback)

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.

 

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)

 

getsipmessage(dir, type, callback)

Will return the last SIP signaling message as specified by the current line and the dir/type parameters.

Call this function passing a callback.

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:

                0: in (incoming/received message)

                1: out (outgoing/sent message)

type:

                0: any

                1: SIP request (such as INVITE, REGISTER, 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

 

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.

 

getlinedetails (line)

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.

 

 

 

getlastcalldetails ()

Returns a 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.

 

getregfailreason ()

Returns a string with the reason about failed connect/registration.

Deprecated! Use the onRegisterFailed callback instead!

setline (line)

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

                -sip 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: 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.

More details about multi-line can be found in the FAQ.

 

getline ()

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)

Get the SIP Call-ID for a line number.

 

callidtoline (callid)

Get the line number for a SIP Call-ID.

 

isregistered ()

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.

 

isincall ()

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.

 

ismuted ()

Return type: boolean

Return true if the call is muted, otherwise will return false.

 

isonhold ()

Return type: boolean

Return true if the call is on hold, otherwise will return false.

 

isencrypted ()

Check if communication channel is encrypted: -1=unknown, 0=no, 1=partially, 2=yes, 3=always

 

checkblf (userlist)

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)

 

checkpresence (userlist)

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.

 

setpresencestatus (status)

Function call to change the user online status with one of the followings strings: Online, Away, DND, Invisible, Offline (case sensitive).

 

getenginename ()

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 below jvoip function or not)

 

listcontacts (all)

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

 

Example:   Name \t Number1|Number2 \t Favorite \t Email \t Address \t Notes \t Website\r\n

 

 

addcontact (fullname, number, email, address, notes, website )

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)

 

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

 

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)

 

 

getworkdir ()

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).

 

delsettings (level)

Delete stored data (from cookie, config file and local-storage).

For the level parameters the following are defined:

1: just settings file

2: delete everything: settings, contacts, call history, messages

 

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.

 

jvoip(name, jargs)

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.

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);

 

getlogs ()

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.

 

getstatus ()

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.

 

others

We have listed all of the commonly used API’s below.

Inspect the webphone_api.js file for the full list of available API’s. Additional (helper or not so important) API’s can be accessed from the \js\lib\api_helper.js.

Events

The following callback functions can be used to receive event from the webphone such as the phone state machine status (registered/call init/call connected/disconnected) and other important events and notifications:

 

onLoaded (callback)

The passed callback function will be called when the webphone was loaded.

You can start working with the webphone library from here. Call any API function only after this callback!

 

onStart (callback)

The passed callback function will be called when the VoIP engine was started.

Webphone is ready to make call here.

Note: you can already initiate calls on the onLoaded callback as those will be queued and executed after onStart.

 

onRegistered (callback)

The passed callback function will be called on registered (connected) to VoIP server (if the webphone has to register).

 

onRegisterFailed (callback)

The passed callback function will be called on connection or registration failure with the reason as a string parameter.

(The callback function will have a String parameter containing the reason of the failed registration)

 

onUnRegistered (callback)

The passed callback function will be called on unregistered (disconnected) from VoIP server.

Note: If user closes the webpage, then you might not have enough time to catch this event.

 

onCallStateChange (callback)

The passed callback function will be called on every call state change.

Parameters:

·         status: can have following string values: callSetup, callRinging, callConnected, callDisconnected

Note:

-the call might change from callSetup state directly into callDisconnected state if it was connected

-callRinging state is optional (it is not a definitive answer for the INVITE transaction so it is not mandatory in SIP)

·         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 number (this might be important only if you wish to handle multi-line management explicitely)

 

A simple usage example can be found here.

 

onPresenceStateChange (callback)

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)

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)

 

onChat (callback)

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

 

onDTMF (callback)

The passed callback function will be called when a DTMF digit is received.

Parameters:

·         dtmf: received DTMF character as string

·         line number

 

onCdr (callback)

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 (includes the call setup time + the ring time)

·         duration: milliseconds elapsed between call connect and hangup (0 for not connected calls. Divide by 1000 to obtain seconds)

·         direction: 1 (outgoing call), 2 (incoming call)

·         peerdisplayname: is the other party display name if any

·         reason: disconnect reason as string

·         line number

 

Note: you can get some more details about the call by using the getlastcalldetails() function.

onDisplay (callback)

Here you can receive important events and notifications (as strings) that should be displayed to the user.

The passed callback function will be called with two string parameters:

-message: a text message intended to be displayed for the user

-title: the title of the "popup/alert". This can be null/empty for some messages

 

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).

 

 

Note:

-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

 

onLog (callback)

The passed callback function will receive all the logs in real time. It can be used for debugging or for log redirection if the other possibilities don’t fit your needs.

 

onEvents (callback)

This function returns ALL events from the webphone including sip stack state, notifications, events and logs.

This is a low level function and you should prefer the above onXXX callbacks instead of using this string typed notifications.

Call this function once and pass a callback, to receive important events (as strings), which should be displayed for the user and/or parsed to perform other actions after your software custom logic. 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.

See the “Notifications” section below for the details.

 

Example:

 

webphone_api.onEvents( function (event)

{

// 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]

// parameters are separated by comma(,)

// the sixth parameter (2) means it is for incoming call. For outgoing call this parameter is 1.

 

// example for detecting incoming and outgoing calls:

 

varevtarray = event.split(',');

 

if (evtarray[0] === 'STATUS' &&evtarray[2] === 'Ringing')

{

        if (evtarray[5] === '1')

        {

            // means it is an outgoing call

            // ...

        }

        else if (evtarray[5] === '2')

        {

            // means it is incoming call

            // ...

        }

}

});

 

You might also check the basic_example.html included in the package.

If you will use this function, then most probably you will catch everything here and don’t need to use the other events functions described below.

 

If you don’t wish to deal with notification strings parsing, then you can use the functions below to catch the important events from the webphone in which you are interested in. Call them once, passing a callback:

 

Notifications

“Notifications” means simple string messages received from the webphone which you can parse with the onEvents(callback) to receive notifications and events from the sip web phone about its state machine, calls statutes and important events.

Skip this section if you are not using the onEvents() function. (You can use the functions such as onRegistered/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 onEvents() function then you will have to parse the received notification 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    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]

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

CHAT,line,peername,text

This notification is received for incoming chat messages.

Line: used phone line

Peername: username of the sender

Text: the chat message body

CHATCOMPOSING,line,peername,composing

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

 

CHATREPORT,line,peername,status,text

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)

 

CDR,line,peername,caller,called,peeraddress,connecttime,duration,discparty

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

START,what

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

 

EVENT,TYPE,txt

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

 

POPUP,txt

Should be displayed for the users in some way.

 

ACTION,txt

Various custom messages. Ignore.

 

LOG,TYPE,txt

Detailed logs (may include SIP signaling).

The following TYPE are defined: EVENT, WARNING, ERROR

 

VAD,parameters

Voice activity.

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 jvoip. 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

 

Other notifications

 

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)

 

FAQ

 

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.

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 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.

For the old “websipphone” (Java Applet based webphone) users:

Please note that this is a separate product. See the upgrade guide about the details. The old java applet based websipphone have been renamed to “VoIP Applet” and we will continue to fully support it as a separate product: https://www.mizu-voip.com/Software/Softphones/VoIPApplet.aspx

You can easily upgrade your old java applet websiphone to this universal webphone by following these steps.

 

What about support?

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:

·         Direct support is provided for the common features (voice calls, chat, dtmf, hold, forward 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) 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 exotic platforms.

·         Direct support is not provided for the issues described in the known limitations section. If you have some specific 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), the servers have to be managed by you and we are not responsible for proper configuration of your servers.

 

What I will receive once I have made the payment for the webphone?

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

Can Mizutech do custom development if required?

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).

Should I have programmer skills to be able to use the webphone?

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)

More details can be found here and in the following FAQ points.

Web server requirements

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.

 

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). You can integrate the webphone 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.
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 have 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: .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

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.

Why HTTPS?

The webphone can work also from unsecure HTTP hosting.

However to take full advantage of the webphone capabilities, we strongly recommend HTTPS hosting (secure HTTP using a domain with a valid TLS certificate).

 

The most important reason is that some browsers (for example Chrome) will not allow media access 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).

 

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 Firefox 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 run 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 webphone is capable for automatic HTTP > HTTPS conversion using a proxy services. In this case it might simply reload itself on HTTPS in some circumstances.

 

Is it working with my VoIP server?

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).

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.

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.

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)

 

Server side and connectivity requirements

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 to use 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 disabled 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, etc) and all OS (Windows, Linux, MAC, Android, etc)

·         Compatible with your existing IP-PBX, VoIP server or any SIP service

·