Mizu WebPhone
Contents
Features, technology and licensing. 4
Integration and customization. 14
User interface Skin/Design. 15
Integration with server side applications. 18
Call divert and other settings. 35
User interface related settings. 40
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, Elastix, Avaya, 3CX, Broadsoft, Alcatel, NEC, others), VoIP servers (Mizu, Voipswitch, Cisco, Huawei, others), service providers (Vonage, 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.
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.
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.
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://yourdomain.com/webphone/techdemo_example.html
Note1: 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).
Note2: If you wish to use (also) the WebRTC engine then your site should be secured (HTTPS with a valid SSL certificate). Latest 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)
3. Integrate
The webphone can be used as a turn-key ready to use solution 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)
4. 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.
The easiest way to start is to just enter the required parameters (serveraddress, username, password and any other youm might wish) in the webphone_api.js file.
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).
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 (since the softphone.html is used usually in an iFrame)
· click2call_example.html: a ready to use browser to SIP click to call solution. You might further customize after your needs
· linkify_example.html: can be used to convert all phone number strings on a website to click to call
· custom: you can easily create any custom browser VoIP solution by using the webphone java script library
More details about customization can be found here.
You can find how it works from here.
Another quick start guide can be found here.
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.
See the “User interface Skin/Design” chapter for more details.
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_example.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:
You can find more details in the click to call section.
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.
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.
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).
· 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 (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, P2P and callback
· SIP and RTP stack compatible with any standard VoIP servers and devices like Cisco, Voipswitch, Asterisk, softphones, ATA and others
· Transport protocols: UDP, TCP, HTTP, RTMP, websocket (uses UDP for media whenever possible)
· Encryption: SIPS, TLS, DTLS, SRTP, end to end encryption for webphone to webphone calls
· 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 G.729 - wideband or WebRTC G.711 to G.729 transcoding if needed)
· Call divert: rewrite, redial, mute, hold, transfer, forward, conference
· Call park and pickup, barge-in (with NS)
· Voice call recording
· IM/Chat (RFC 3428), SMS, file transfer, DTMF, voicemail (MWI)
· Multi-line support
· Contact management: flags, synchronization, favorites, block, presence (DND/online/offline/others)
· 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 upgrade 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
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)
· 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)
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.
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)
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)
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
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 not supported by some browser, most notable mobile devices and Chrome which has dropped NPAPI support required for the Java plugin (in this case the webphone will use WebRTC, Flash or Native engine instead of Java)
· Some browsers may ask for user permission to activate the Java plugin
Some platforms don’t have any suitable technology to enable VoIP in browsers (a minor percentage, most notably 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: iOS Safari)
Cons:
· No API support. Not the exactly same HTML user interface (although highly customized based on the settings you provided for the webphone)
These are just “virtual” engines with no real client VoIP stack.
· P2P means server initiated phone to phone call initiated by an API call into your VoIP server. Then the server will first call you (on your regular mobile/landline phone) and once you pick it up it will dial the other number and you can start talking (Just set the “p2p” setting to point to your VoIP server API for this to work)
· Callback is a method to make cheap international calls triggering a callback from the VoIP server by dialing its callback access number. It might be used only as a secondary engine if you set a callback access number (Just set the “callback” setting to point to your VoIP server API for this to work)
These are treated as a secondary (failback) engines and used only if no other engines are available just to be able to cover all uncommon/ancient devices with lack of support for all the above engines which is very rare. However it might be possible that these fits into your business offer and in that case you might increase their priority to be used more frequently.
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.
All the above engines are covered with an easy to use unified Java Script API, hiding all the differences between the engines as described below in the “JavaScript API” section.
The webphone can be used with or without a user interface.
The user interface can be built using any technology with JS binding. The most convenient is HTML/CSS, but you can also use any others such as Flash.
The webphone package comes with a few prebuilt feature rich responsive user interfaces covering the most common usage such as a full featured softphone user interface and a click to call implementation. You are free to use these as is, modify them after your needs or create your own from scratch. For more details check the “User interface Skin/Design” section.
Major changes by release are listed here:
-internal beta version with basic skin and basic call functionality
Version 0.6 (July 3, 2015)
-engines: WebRTC beta and Java Applet v.1.0
-more SIP settings
-early beta version with basic SIP call functionality
Version 0.9 (September 9, 2015)
-call-divert functionalities (voicemail, transfer, others)
-conference
-NS (Native Service or Plugin)
-examples and documentation
-better skinning
-better OS/browser handling
-automatic engine selection
-WebRTC stable incoming and outgoing calls
-upgrade to latest Java Applet and WebRTC engine
-more JavaScript SIP API
-new: flash engine
-WebRTC improvements
-stable API, modules and file structure
-improved auto engine selection
-chat
-app engine
-secondary engines (p2p, native dial, callback)
-custom builds based on customer settings
-callback API for simplified API (use simple call back instead of notification string parsing)
-server API for the webphone state machine (so you can easily catch all important events from server code)
-WebRTC engine upgrade to latest version
-presence (not fully standard compliant yet but working)
-added file transfer
-new missed call/chat notifications
-http vs https bug fixes
-NS engine availability from https
-reset setting parameter and API
-last call detailed statistics
-called number normalization
-one-way audio fix on WebRTC
-WebRTC fix for Android
-many other improvements and bug fixes
-new: audio device selection
-new: favorite or block contact
-new: setsipheader/getsipheader
-improved: capability call special url's on events (server API integration)
-improved: number rewrite rules
-improved: feedback for file transfer
-fix: ns engine unregister on webpage close
-fix: increase cseq for re-invite
-other improvements and bug fixes
-new: WebRTC to SIP gateway (free as both software and service for all our web sip library customers)
-new: TURN (WebRTC works now even if all UDP is blocked and only port TCP 80 is allowed)
-new: auto codec convert when necessary (for example to G.729 from WebRTC)
-new: App engines for iOS and Android
-new: WebRTC on Android
-new: HTTP to HTTPS gateway (used automatically if hosting website is not secure which is required by Chrome for WebRTC)
-new: WebRTC caller-id
-improved: WebRTC NAT handling
-improved: STUN
-improved: end to end encryption
-improved: softphone skin
-fix: java freezing improvements
-fix: WebRTC caller-id
-new: call recording (voicerecupload)
-new: 8 new call-divert related settings and API’s
-new: callcenter integration
-improved: engine selection
-improved: VoIP over TCP using TURN only when necessary
-improved: usage on local LAN’s
-improved: WebRTC (various fixes)
-fix: auto engine select related bugs, unnecessary java popups
-fix: NS engine discover issues
-fix: mute/unmute, hold/unhold
-fix: CTRL+C, CTRL+V in the softphone skin
-more than 20 other bug fixes and small improvements especially engine detect/choose related
-new: video
-new: conference rooms (server assisted)
-new: audio device list, get, set functions
-new: web call-me
-new: peer to peer media auto discover
-new: call forward
-new: auto WebRTC server discovery (for example it can detect automatically if webrtc is enabled in Asterisk and other servers)
-new: softphone skin now can be inserted also in a DIV (previously it was working only in iframe)
-new: callback (you can specify a callbacknumber parameter if your server has a callback access number)
-new: sip outbound proxy setting
-new: call transfer options
-new: CDR records after calls (can be easily posted to server API)
-new: group chat
-improved: webrtc engine
-improved: click to call
-improved: presence
-improved: voicemail
-improved: conference
-improved: voice recording
-improved: android native dialer auto-configuration
-improved: themes (color theme/skinning)
-improved: TURN and STUN handling and auto-discovery
-improved: user interface integration (div, popup, flying, others)
-improved: chat (reliability, smiles, file-transfer, groups)
-improved: NS engine versioning and auto upgrade
-fix: voip engine auto select related issues, settings save/restore
-fix: init delay
-fix: ns engine localhost certificate, https/wss issues
-fix: more than 44 bug-fixes mostly based on customer feedback and additional tests
-the old documentation for this version can be found here
-new: MAC OS WebRTC plugin
-new: multi-line (manage multiple simultaneous calls)
-new: ICE TCP candidate (RFC 6544)
-new: UPNP NAT for NS and Java engines (better NAT handling behind UPNP capable routers)
-new: redial or re-INVITE on fast call failure or on no media with changed stun and codec
-new: auto call forward on no answer (“callforwardonnoanswer” setting)
-new: more settings such as language, disablesamecall, checkvolumelevel, inbounddtmf , outbounddtmf, usecommdevice, etc
-new: stop() and getworkdir() api
-new: auto NS service upgrade in background (only if NS is actually used and only to known good new versions)
-improved: DTMF between SIP and WebRTC (both INFO and RFC 2866 are supported)
-improved: stun and turn (earlier public IP discovery, doesn’t use on local LAN’s)
-improved: more native audio features on Windows
-improved: http/https view/api/download/upload/autoprovisioning (autodetect, https-http proxy and ssl bypass options)
-improved: fast init with no more delays when coming from settings and engine init speedups
-improved: fast cleanup and exit for the java engine
-improved: conference for WebRTC
-improved: NS engine auto upgrade
-improved: iOS app engine via SIP softphone
-improved: various transfer related improvements including WebRTC to SIP call transfer
-improved: usage from behind NAT or firewalls (now capable to use both TURN and TCP candidates if UDP is blocked)
-improved: various other WebRTC-SIP related improvements
-improved: documentation
-fix: embed in webpage related issues and webphonebasedir
-fix: onRegistered to catch all SIP register events
-fix: settings save/load, keep last good VoIP method
-fix: chat between SIP and WebRTC
-fix: file transfer related bugs
-fix: flash VoIP engine only when really necessary (no any other options)
-fix: DNS SRV record timeout handling
-fix: fixed problem with AEC for wideband speex and opus with NS and Java
-fix: audio device list on Windows
-fix: ptime settings for G.729
-fix: reject double outbound calls to same destination
-fix: various GUI related bugs on the softphone skin
-fix: various auto engine detect, prioritization and usage related bugs
-fix: more than 110 other minor fixes and improvements
-new: no need to explicitly set the webphonebasedir anymore as it is always guessed correctly from now
-new: call forward and transfer now works between SIP and WebRTC endpoints
-new: NS self-upgrade in background capability (with no user interaction required)
-new: checkmicrophone setting
-new: global instance (ability to use the same webphone instance on multiple webpages opened in different tabs/windows in the client browser)
-new: call recover with redial on no or bad response
-new: MAC OS webrtc plugin as pkg (webrtcplugin.pkg)
-new: capability to initiate calls even if not registered, registrar disabled or register failed
-new: more call details onCdr such as displayname and call disconnect reason
-improved: better audio/camera recording permission handling
-improved: TURN and TCP candidates (now it works in all circumstances with WebRTC)
-improved: WebRTC-SIP protocol conversion
-improved: WebRTC-SIP codec conversion (for example Opus to G.729 and inverse)
-improved: Android app engine
-improved: better aec and denoise
-improved: update to latest OpenSSL for the WebRTC DTLS and websocket TLS
-improved: settings management (now the server side settings from webphone_js.api are applied immediately and exactly as-is)
-improved: more flexible parameter handling (handle when pass number as string or bool as number and others)
-improved: auto hide disconnected call page after some time
-improved: click-to-call related improvements
-improved: Asterisk WebRTC auto discover
-improved: registerless usage (register=0)
-improved: permissible demo license limitations
-improved: WebRTC trickle ICE
-improved: chat reliability
-improved: number rewrite rules
-improved: call divert now propagated also to server side (will safely handle servers with no such support)
-improved: usage without sipserver (call to sip uri should work; serverless peer to peer functionality)
-fix: click-to-call related bugs
-fix: autostart: 0, start and register only when clicked
-fix: mute() should mute also the speaker if called with parameter 0 or 1; also webrtc mute is fixed now
-fix: on hold fail, call is disconnected, but the disconnect is not discovered by the GUI
-fix: send dtmf while in webrtc call doesn't display any feedback
-fix: keypress events
-fix: loading cached old settings problem
-fix: ERROR, catch on common: ParamAsBool ReferenceError: isNumber is not defined (isNumber is not defined)
-fix: ERROR, catch on notifications: ProcessNotifications, not: STATUS,1,Finished ReferenceError: GetParameter is not defined
-fix: WRTC, ERROR, InvalidAccessError: RTCPeerConnection constructor passed invalid RTCConfiguration
-fix: flash engine offer only if no any other better choice
-fix: java no applethandle after going to settings and back (maybe go to settings and select java engine even if selected)
-fix: settings not always read correctly if webphone is used as SDK and this causes discrepancies in engine selection
-fix: detailed loglevel fixed
-fix: call start while webphone is initializing
-fix: video chat one side only now fixed
-fix: call recording
with WebRTC engine
-new: getsipmessage API
-new: allowcallredirect parameter
-new: playdtmfsound parameter
-new: onDisplay callback
-new: earlymedia parameter
-new: server/user-agent based licensing for the gold version
-new: option to disable all toasts/popups
-new: muteholdalllines parameter
-improvement: multi-line; a lot of improvements regarding line management
-improved: setline() now accepts also peer phonenumber or sip call-id
-improved: conference API add parameter and other conference related
-improved: call transfer and forward between SIP and WebRTC (and inverse)
-improved: more robust un-register
-improved: cookie and indexDB localforage
-improved: call setup without recording device (no microphone)
-improved: NS engine once click installer improvements and auto-configuration
-improved: Safari compatibility
-improved: handle Firefox 52+ no Java/NPAPI support
-improved: playsound API
-improved: get the call disconnect reason on hangup (from SIP disc. code but also from Reason and Warning headers)
-fix: WebRTC-SIP converter blind accept any username/password in registrations (now properly forward as SIP REGISTER with digest authentication)
-fix: ice timeout
-fix: IsRegistered
-fix: don't touch the NS engine if not needed
-fix: globalline defaults to -1 if not multiline
-fix: webphone_api.voicerecord
-fix: getsipheader mixed up bug
-fix: call timer display
-fix: accidental call disconnects
-fix: IE 7 and IE 8 compatibility
-fix: password sometime encoded incorrectly
-fix: username vs sipusername
-fix: SendDtmf ReferenceError: message is not defined
-fix: settings management
-fix: garbage characters in balance display (credit/currency)
-fix: NS engine XP and vista compatibility
-fix: NS engine compatibility with x32 (32 bit) OS versions
-fix: NS engine compatibility with non-english Windows versions
-fix: autologin not working if server/user/password is set
-fix: if username or password is preset then don't display user/pwd input for the softphone skin
-numerous other improvements and minor bug fixes
The webphone is
sold with 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 [email protected]. Mizutech will
deliver your webphone build within one workday after your payment.
Release versions don’t 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 or service customers).
Title, ownership
rights, and intellectual property rights in the Software shall remain with
MizuTech.
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
· 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
· 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), 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)
Let us know if you wish to use the webphone in some other way, not covered by this license.
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:
· maximum 10 simultaneous webphone at the same time
· 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
In short: the demo version can be used for all kind of tests or development, but it can’t be used for production.
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.
The webphone is a flexible VoIP web client which can be used for various purposes such as a dialer on your website, a click to call button for contacts or integrated with your web application (contact center, CRM, social media or any other application which requires VoIP calls).
The webphone can be customized by its numerous settings, webphone API’s and by changing its HTML/CSS.
Deploy:
The webphone can be deployed as a static page (just copy the webphone file to your website), as a dynamic page (with dynamically generated settings) or used as a JavaScript VoIP library by web developers. You can embed the webphone to your website in a div, in an iFrame or on demand, as a module or as a separate page. The webphone settings can be set also by URL parameters so you can just launch it from a link with all the required settings specified.
VoIP platform:
All you need to use the webphone is a SIP account at any VoIP service provider or your own softswitch/IP-PBX.
Free SIP accounts can be obtained from numerous VoIP service providers or you can use our service. (Note that free accounts are free only for VoIP to VoIP calls. For outbound pstn/mobile you will need to top-up your account).
If you wish to host it yourself then you can use any SIP server software. For example FreePBX for linux or the advanced / free VoIP server for windows by Mizutech. We can also provide our WebRTC to SIP gateway (for free with the Advanced or Gold license) if your softswitch don’t have support for WebRTC and you need a self-hosted solution.
Technical settings:
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.
If you wish, you might change also other sip account, call-divert or VoIP engine related settings after your needs.
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.
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.
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 “minimal_example.html”, “basic_example.html” or “techdemo_example.html” (You can also use the provided samples as a template to start with and modify/extend it after your needs)
Just use the “colortheme” parameter to make quick and wide changes.
Then have a look at the “User interface related” parameters (described in the “Parameters” section) and change them after your needs (set logo, branding, translate and others).
We can also send you a web softphone with your preferred skin. For this just set your customization on the online designer form and send us the parameters.
We can also send you fully customized and branded web softphone with your preferences. For this just send us the customization details.
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:
· If you need only minor/color changed, then just change the color theme
· You might also change 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".
· You can also 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
Note: If you are using the webphone as a javascript library then you can customize the “choose engine” popup in "css\pmodal.css".
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.
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.
There are multiple ways to achieve click to call functionality with the sip webphone:
Use the Click2Call template
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 the click2call_example.html.
You can completely customize the click2call example for your needs (change any settings, change the html/css/javascript, use your custom button image).
Launch from URL
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:
A working example with the click to call skin:
This will launch the click to call page and will initiate the call automatically. You can find more examples here.
You can also use any other skins for click to call. For example here is with the softphone skin:
Custom click to call solution
You can easily create your custom click to call solution from scratch by using the webphone as a library/SDK.
A simple click to call example can be found in the webphone package: "click2call_example.html"
The following parameters must be configured in order to make a call: serveraddress, username, password, callto.
A Step by step guide to add click to call button to 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;
</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
Customization options can be found in click2call.js file located in js/click2call/ folder.
The following customizations are available:
- button color (for call and hang up states)
- text displayed on the button (for call and hang up states)
- button width, height and corner radius
- chat window default state: open or collapsed
The styling can be further customized from click2call.css located in css/click2call/ folder.
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=call, 2=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
The click to call can also be used as a floating button on your 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;
var float_distance_from_right = 10;
Floating webphone skin
To float the webphone skin over your web page, just set the following CSS attributes for the container HTML element of the webphone (which can be a DIV or an iframe):
// this aligns the webphone to the bottom-right corner of you page
z-index: 1000; position: fixed; bottom: 0px; right: 0px;
If you wanted for instance to set it in the top-left corner, then the CSS attributes would be:
z-index: 1000; position: fixed; top: 0px; left: 0px;
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.
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.
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 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.
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).
Then you will receive request to this API entry on your app server and you can process them accordingly (load the URL parameters and store in your database).
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.
You can integrate the webphone with your server code using your custom HTTP (AJAX) API URI’s.
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 fetch the result using the following techniques (first available): AJAX/XHTTP, CORS, JSONP and websocket (if available).
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.
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”) 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.
First of all you should deploy the webphone on your webserver (Copy the webphone folder to your webserver and adjust any settings you might need according to your SIP server). You can also launch it from local file system on your dev environment (works with some limitations), but better if you use it from a webserver.
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.
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).
The downloadable demo version has some limitations to disable commercial usage, however if your development process is affected by these then you can request a trial from mizutech with all demo limitation removed.
The public JavaScript API can be found in "webphone_api.js" file, under global javascript namespace "webphone_api".
Just include the "webphone_api.js" to your project or html and start using the webphone API.
The API reference can be found here.
A minimal implementation can be achieved with less than 5 lines of code
on your website. See the minimal_example.html (found in the webphone package)
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>
See the html files in the webphone 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).
o a basic example for incoming calls is implemented in the incoming_example.html
o click2call.html is a ready to use click to call implementation
o softphone.html implements a fully features browser softphone
You can also try the same examples from our online demo.
You are free to use/modify any of these file and adjust it after your needs or create your own solution from scratch.
For a general implementation we would recommend to start with the “techdemo_example” and modify/improve it after your needs.
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 need to 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 getEvents callback for this but it is recommended to use the others such as the onCallStateChange to handle the web VoIP phone events.
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 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
Note: all of these are 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, see the “JavaScript API” section below in this documentation.
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)
· 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)
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 URI (or IP:port)
username: 'webphonetest1', //the username is usually specified by the enduser and not need to be set here
password: 'webphonetest1', //the password is usually specified by the enduser and not need to be set here
displayname: 'John Smith', //optional display name
brandname: 'BestPhone', //your brand name
rejectonbusy: true, //will reject incoming call if user already in call
ringtimeout: 50, //disconnect the call after 50 sec on no answer
loglevel: 5, //enable detailed logs
};
Usually you might set some parameters in the above webphone_api.js file (the common parameters applicable for all users), then you use one of the other methods to specify instance specific parameters (for example user credentials for auto login).
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.
· 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.
· 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
· Parameters can be also encrypted or obfuscated. See the “Parameter security” section for the details.
Credentials and other SIP parameters:
(string)
The address of your SIP server (domain or IP + port).
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
This is the single most important parameter (along with the username/password but those can be also entered by the user).
Default value is empty.
(string)
This is the SIP username (used for authentication and as A number/Caller-ID for the outgoing calls).
Default value is empty.
Note:
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.
o Even if you don’t need a username and/or your server accepts all calls without authentication, you must set some 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.
(string)
SIP authentication password.
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 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
(string)
Optional SIP display name.
Specify default display name used in “from” or “contact” SIP headers.
Default value is empty (the “username” field will be displayed for the peers).
See more details here.
(string)
Optional parameter to set the SIP realm if not the same with the serveraddress or domain.
Rarely required. (Only if your VoIP server has different realm setting as its domain and it strictly enforces that realm)
Default value is empty. (By default the serveraddress will be used without the port number)
(string)
Outbound SIP proxy address (Examples: mydomain.com, proxy.mydomain.com:5065, 10.20.30.40:5065)
Leave it empty if you don’t have a stateless proxy. (Use only the serveraddress parameter)
Default value is empty.
(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.
(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 if 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; some servers doesn’t accept such short re-registration periods). Also you should not set it longer then 3600 (one hour).
(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).
(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 or SIP URI acceptable by your VoIP server.
Default value is empty.
(number)
Useful for click-to-call to specify what to do if you pass the “callto” parameter
0: nothing (do nothing, just preset the destination number; the user will have to initiate the call/chat)
1: call (default. Will auto start the call to “callto”)
2: chat (will show the chat user interface presenting a chat session with “callto”)
3: video call (will auto start a vide call)
Note: the other SIP related settings can be found in the “Engine related settings” below (such as dtmfmode or codec).
Library and engine related settings:
By default the webphone will choose the “best” suitable engines automatically based on OS/browser/server support. This algorithm is optimized for all OS and all browsers so you can be sure that your users will have the best experience with default settings, however, if you wish, you can influence this engine selection algorithm by setting one or more of the following parameters:
· enginepriority_java
· enginepriority_webrtc
· enginepriority_ns
· enginepriority_flash
· enginepriority_app
· enginepriority_p2p
· enginepriority_accessnum
· enginepriority_nativedial
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)
For example if you wish to prioritize the NS engine, just set: enginepriority_ns=3
The engines also have a built-in default priority number assigned which can range from 0 to 100. You can change also these values 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
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.
(string)
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).
Examples:
ws://mydomain.com
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: 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.
More details about webrtc can be found in the FAQ.
(string)
Optional setting to indicate the address (domain name or IP address + port number) of your flash service if any (flash media + RTMP). If not set, then the mizu flash to sip service might be used (rarely used in normal circumstances). Format: yourdomain.com:rtmpport
Example: 10.20.30.40:5678
Default value is empty.
(string)
STUN server address in address:port format (RFC 5389)
You can set to “null” to completely disable STUN.
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”).
(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
TURN is required 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.
(string)
Any TURN URI parameter.
Example: transport=tcp
(string)
Username for turn authentication.
(string)
Password for turn authentication.
(number)
Timeout for ICE address gathering (STUN/TURN/others) in milliseconds.
Default is 3000 (3 seconds).
You might increase in special circumstances if you are using some slow STUN/TURN server or decrease if peer address is public (like if your SIP or WebRTC server is on public IP always routing the media, so calls will work also without STUN).
(number)
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.
(boolean)
Offer native softphone to install if no suitable engine found.
This is useful for browsers which doesn’t have any built on capability for VoIP nor it allows external plugins such as iOS/Safari.
Download links can be configured with "android_nativedialerurl" and "ios_nativedialerurl" listed below, otherwise the default will be used (auto provisioned apps from Mizutech with your branding, customization and settings as you define it for the webphone).
Default is true.
(string)
Android native softphone download URL if any. (Optional setting to allow alternative softphone offer on Google Play).
Note: Android browsers has support also for WebRTC so this might be selected only with old phones or if you disable WebRTC.
Default is empty (which means the default app).
(string)
iOS native softphone download URL if any. (Optional setting to allow alternative softphone offer on Apple App Store).
The safari browser under iOS doesn’t offer any plugin for VoIP so the webphone can use its native softphone (will be auto provisioned from your webphone settings).
Default is empty (which means the default app).
(string)
Set this if your IP-PBX has an access number where users can call into from PSTN and it can forward their call on VoIP (IVR asking for the target number).
This can be used when no other engines are working (no suitable environment, no internet connection).
Default is empty.
(string)
Set this if your server has a callback access number where users can ring into and will receive a call from your server (possibly with an IVR which might offer the possibility to specify the destination number via DTMF).
This can be used when no other engines are working (no suitable environment, no internet connection) and it is very useful in situation where call from the server is cheaper than user call to server.
Default is empty.
(string)
This will overwrite the default User-Agent setting.
Do not set this when used with mizu VoIP servers because the server detects extra capabilities by reading this header.
Default is empty.
(string)
Set a custom sip header (a line in the SIP signaling) that will be sent with all messages. Can be used for various integration purposes and usually has a key:val format. For example: myheader:myvalue.
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',).
Default is empty.
(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.
(number)
Transport protocol for native SIP.
0: UDP (User Datagram Protocol. The most commonly used transport for SIP)
1: TCP (signaling via TCP. RTP will remain on UDP)
2: TLS (encrypted signaling)
3: HTTP tunneling (both signaling and media. Supported only by mizu server or mizu tunnel)
4: HTTP proxy connect (requires tunnel server)
5: Auto (automatic failover from UDP to HTTP if needed)
Default is 0.
Note: this will not affect WebRTC since webrtc transport is controlled by the browser: http/https, websocket/secure websocket (ws/wss) and DTLS/SRTP for the media.
(String)
Specify local IP address to be used.
This should be used only on devices with multiple ethernet interface to force the specified IP.
Default is empty (autodetect)
Note: This setting is not applicable for WebRTC (In case of WebRTC this is handled entirely by the browser internal WebRTC stack)
(number)
Specify local SIP signaling port to use.
Default is 0 (a stable port which is selected randomly at the first usage)
Note: This is not the port of your server where the messages should be sent. This is the local port of the signaling socket.
Note: This setting is not applicable for WebRTC (In case of WebRTC this is handled entirely by the browser internal WebRTC stack)
(number)
Specify local RTP port base.
Default is 0 (which means signalingport + 2)
Note: If not specified, then VoIP engine will choose signalingport + 2 which is then remembered at the first successful call and reused next time (stable rtp port). If there are multiple simultaneous calls then it will choose the next even number.
Note: This setting is not applicable for WebRTC (In case of WebRTC this is handled entirely by the browser internal WebRTC stack)
(boolean)
Send rtp even if muted (zeroed packets)
Set to true only if your server is malfunctioning when no RTP is received.
Default value is false.
(number)
Media encryption method
0: not encrypted (default)
1: auto (will encrypt if initiated by other party)
2: SRTP
Default is 0.
Note: this will not affect WebRTC since WebRTC always uses DTLS/SRTP for the media.
(number)
DTMF send method
· 0: disabled
· 1: sip INFO method
· 2: auto detect (RFC2833 in the RTP if RTP stream is working and peer announced telephone-event payload), otherwise it will send (also) SIP INFO.
· 3: both INFO and RFC2833
· 4: RFC2833 (will not send SIP INFO even if there is no RTP stream negotiated)
Default is 2.
Note:
Received DTMF are recognized by default in both INFO or RFC2833 formats (No In-Band DTMF processing)
You can also use the “inbounddtmf” and “outbounddtmf” to suggest server side dtmf types. These can be set only to 1 or 2.
(number)
Specify whether the webphone should generate local DTMF tone when DTMF is sent.
0=no
1=if one digit
2=always (also when multiple digits are sent at once)
Default is 1.
(number)
Start to send media when session progress is received.
0: no
1: reserved
2: auto (will early open audio if wideband is enabled to check if supported)
3: just early open the audio
4: null packets only when sdp received (NS only)
5: yes when sdp received
6: always forced yes
Default is 2.
(string)
Set your preferred audio codec. Will accept one of the followings: pcmu, pcma, g.711 (for both PCMU and PCMA), g.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.
(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)
(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.
(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>
(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.
(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
(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.
(number)
Enable/disable acoustic echo cancellation
0=no
1=yes except if headset is guessed
2=yes if supported
3=forced yes even if not supported (might result in unexpected errors)
Default is 1.
(number)
Automatic gain control.
0=Disabled
1=For recording only
2=Both for playback and recording
3=Guess
Default value is 3
(number)
Although the jitter size is calculated dynamically, you can modify its behavior with this setting.
0=no jitter,1=extra small,2=small,3=normal,4=big,5=extra big,6=max
Default is 3
(number)
Enable/disable presence.
Possible values:
0: disable
1: auto (if presence capabilities detected)
2: always enable / force
(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)
(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.
Do not set to 0 because that will disable also the important notifications presented for the users.
More details about logs can be found here.
(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
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)
These parameters are used for call auto-answer, forward, transfer, number rewrite and similar tasks:
(number)
Normalize called phone 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)
(string)
Add any prefix for the called numbers.
Default is empty.
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.
(string)
Block incoming communication (call, chat and others) from these users. (username/numbers/extensions separated by comma).
Default value is empty.
(string)
Specify a number where incoming calls should be forwarded when the user is already in a call. (Otherwise the new call alert will be displayed for the user or a message will be sent on the JS API)
Default is empty.
(string)
Forward incoming calls to this number if not accepted or rejected within 15 seconds.
Default is empty.
(string)
Specify a number where ALL incoming calls should be forwarded.
Default is empty.
(string)
Specify a number where ALL incoming calls should be transferred to.
This might be used if your server doesn’t support call forward (302 answers) otherwise better to set this on server side because the call will not reach the webphone when it is offline/closed, so no chance for it to forward the call.
Default is empty.
(number)
Set to ignore all incoming calls.
0: don’t ignore
1: silently ignore
2: reject
Default value is 0.
(boolean)
Set to true to automatically accept all incoming calls (auto answer).
Default value is false.
(boolean)
Specify whether to auto accept incoming calls when the user clicks to enable device sharing for WebRTC (the audio device permission browser popup)
-true: accept webrtc call on browser share device click (default)
-false: do nothing (user will have to click the “Accept” button to accept the incoming call or you must call the accept() API)
(number)
Will play a short sound when calls are connected
0: Disabled
1: For auto accepted incoming calls
2: For incoming calls
3: For outgoing calls
4: For all calls
Default value is 0
(number)
Retry the call on failure or no response.
0: no
1: yes
Default value is 1.
(boolean)
Set to true to automatically reject (disconnect) incoming call if a call is already in progress.
Default value is false.
(number)
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.
(number)
Set to 1 to auto-redial on 301/302 call forward.
Set to 0 to disable auto call forward.
Default value is 1.
(number)
Auto Mute/Hold all call legs on conference calls.
0=no
1=yes
Default is 0.
(number)
Specify if other lines will be muted on new call
0=no (default)
1=on incoming call
2=on outgoing call
3=on incoming and outgoing calls
4=on other line button click
Default is 0
(number)
Specify if other lines will be muted on new call
0=no (default)
1=on incoming call
2=on outgoing call
3=on incoming and outgoing calls
4=on other line button click
Default is 0
(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 Applet 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 Applet 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)
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)
Note: only unattended/blind transfer is support between SIP and WebRTC (if one endpoint is using native SIP while the other is on WebRTC)
(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
(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” applet parameter is set)
4: change status to ringing and start media receive and playback (and media recording if the “earlymedia” applet parameter is set to true)
5: play early ringback and don’t stop even if incoming early media starts
Will call startRingbackTone() on 180 and 183 and do NOT stop on early media receive.
Default value is 2.
*Note: on ringing status the web phone is able to generate local ringback tone. However with the default settings this locally generated ringtone playback is stopped immediately when media is started to be received from the server (allowing the user to hear the server ringback tone or announcements)
(number)
Maximum ring time allowed in millisecond.
Default is 90000 (90 second)
You can also set separate ring timeout for incoming and outgoing calls with the “ringtimeoutin” and “ringtimeoutout” settings.
(number)
Maximum speech time allowed in millisecond.
Default is 10800000 (3 hours)
(number)
RTP timeout in seconds to protect again dead sessions.
Calls will be disconnected if no media packet is sent and received for this interval.
You might increase the value if you expect long call hold or one way audio periods.
Set to 0 to disable call cut off on no media.
Default value is 300 (5 minute)
(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).
(string)
Voice record upload URL.
With this setting you can setup VoIP call recording (voice 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.
The files can be uploaded to your FTP server (any FTP server with specified user login credentials) or HTTP server (in this case you need a server side script to save the uploaded data to file using http PUT or multipart/form-data POST)
Default value is empty (no voice call recording).
Example:
ftp://user01:[email protected]/voice_DATETIME_CALLER_CALLED
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: ftp://user01:[email protected]/voice_DATETIME_CALLER_CALLED.wav
You can use the following keywords 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
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.
Note:
1. You can also use the voicerecord API to turn on/off the voice recording at runtime (if not all calls have to be recorded)
2. Voice call recording usually can be performed also on the server side. Check your PBX/softswitch documentation for this.
Most of these apply only to the Softphone user interface which is shipped with the webphone to further customize the web softphone user interface and behavior (Softphone.html)
(string)
Brand name of the softphone to be displayed as the title and at various other places such as SIP headers.
Default is empty.
(string)
Your company name to be displayed in the about box and various other places.
Default is empty.
(string)
Displayed on login page.
Can be text or an image name, ex: "logo.png" (image must be stored in images/folder)
Default is empty.
(number)
You can easily change the skin of the supplied user interfaces with this setting (softphone, click to call).
Possible values:
1. Default
2. Light Blue
3. Light Green
4. Light Orange
5. Light Purple
6. Dark Red
7. Yellow
8. Blue
9. Purple
10. Turquoise
11. Light Skin
12. Green Orange
Default is 0.
More details about design changes.
Set the language for the user interface.
Two character language code (for example en for English or it for Italian).
More details about localization can be found in the FAQ.
(number)
User interface complexity level.
0=minimal
5=reduced
10=full (default)
15=more (for tech user)
You might set to 5 for novice users or if only basic call features have to be used.
Default is 10.
(number)
This can be used to hide the server address setting from the user if you already preconfigured the server address in the webphone_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)c
(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
(number)
0: Auto guess or Ask
1: SMS only
2: Chat only
Default is 0.
(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.
(number)
Enable/disable conference room feature.
0: disabled
1: enabled (if supported by the server)
Default is 1.
(string)
Can be used to add call park and call pickup (will be sent as DTMF for call park and user need to call to pickup number to later reload the call from the same or other device).
If set, then it will be displayed on the call page as an extra option.
(boolean)
Enable/disable the time counter during ring-time.
(boolean)
Set to true to enable file transfer.
(string)
HTTP URI used for file transfer. By default Mizutech service is used which is provided for free with the web softphone.
(number)
Show notifications in phone notification bar (usually on the top corner of your phone).
0:Never
1:On event
2:Always
Default is 1.
(boolean)
Always display volume controls when in call.
Default is false.
(boolean)
Always display audio device when in call.
Default is false.
(string)
Specify where to display the information returned by scurl_displaypeerdetails.
It can be used display details about the peers from your CRM such as full name, address or other details.
(Useful in call-centers and for similar usage)
Possible values:
0: show on call page (instead of contact picture)
1: on new page
div id: display on the specified DIV element
(number)
Whether to (automatically) add new unknown called numbers to your contact list.
0:No
1:Ask
2:Yes (will not ask for a contact name)
Default is 1.
(boolean)
Whether to display a popup about incoming calls in certain engines.
Set to false to disable (in this case make sure that you handle the incoming call alert from your HTML/JS if required).
Default is true.
(string)
Header text displayed for users on top of softphone windows.
Default is empty.
(string)
Footer text displayed for users on the bottom of softphone windows.
Default is empty.
(string)
Version number displayed for users.
Default is empty (will load the built-in version number)
(string)
Display custom popup for user once.
Default is empty.
(number)
This is to allow contact synchronization between mobile and desktop.
-1=don't show
0=show Sync option in menu and Contacts page (if no contacts available)
1=show in menu only
Default is 1
(string)
Set one or more contacts to be displayed by default in the contact list.
Name and number separated by comma and contacts separated by semicolon:
Example: defcontacts: 'John Doe,12121;Jill Doe,231231'
(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: disabledsett: 'theme,email,Call forward,callforwardonbusy,callforwardonnoanswer,callforwardalways,VIDEO'
(string)
List of settings options to be disabled or hidden when using the softphone skin.
Example: hidesettings: 'theme,email,callforwardonbusy,callforwardonnoanswer,callforwardalways,autoaccept,autoanswer_forward,forward,autoignore'
(string)
Custom parameters can be set in a key-value pair list, separated by semicolon Ex: displayname=John;
Default is empty.
(number)
Specify allowed actions on the logs page.
0: no options (users will still be able to copy-paste the logs)
1: upload (default)
2: email launch (the email address set by the “supportmail” parameter or [email protected] if not set)
(strings)
The webphone GUI can load additional information from your web server application or display some content from your website internally in a WebView or frame. You can integrate the included softphone user interface with your website and/or VoIP server HTTP API (if any) by using the following parameters:
· advertisement: Advertisement URL, displayed on bottom of the softphone windows.
· supportmail: Company support email address.
· supporturl: Company support URL.
· newuser: New user registration http request OR link (if API then suffix with star *)
· forgotpasswordurl: Will be displayed on login page if set.
· homepage: Company home page link.
· accounturi: Company user account page link.
· recharge: Recharge http request (pin code must be sent) or link.
· p2p: Phone to phone http request or link.
· callback: Callback http request or link (For example: http://yourdomain.com/callback?user=USERNAME)
· sms: SMS http request.
· creditrequest: Balance http request, result displayed to user.
· ratingrequest: Rating http request, result displayed for user on call page.
· 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.
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)
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 it 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.
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)
-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.
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.
<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.
Use the following API calls to control the webphone:
Any additional parameters must be set before start/register/call is called.
Return type: string
Will return value of a parameter if exists, otherwise will return empty string.
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 parameter should be set before you call this method (preset in the js file or by using the setparameter() function). See the “Parameters” section for details.
Optionally you can "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)
Un-register from your SIP server (will send a REGISTER with Expire header set to 0, which means de-registration).
Unregister is called also automatically at browser close so usually there is no need to call this explicitly.
Initiate call to a number, 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).
Initiate a video call to a number, sip username or SIP URI.
(Will failback to a simple voice call if video is not supported by peer, by the server or gateway. It should always work between WebRTC endpoints if peers has a camera device)
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.
Connect incoming call.
Disconnect incoming call.
(You can also use the hangup() function for this)
Silently ignore incoming call.
Forward incoming call to the specified number (phone number, username or extension)
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)
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.
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.
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)
-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)
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 #");
Send a chat message. (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 ASCI or UTF-8 text or html encoded.
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)
Start/stop voice recording.
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.
Open audio device selector dialog (built-in user interface).
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 or 1 for the playback or ringer 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.
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
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)
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)
The "immediate" parameter can have the following values:
0: default
1: next call only
2: immediately for active calls
Call this function, passing a callback and will return the volume (percent) for the selected device.
The dev parameter can have the following values:
0 for the recording (microphone) audio device
1 for the playback (speaker) audio device
2 for the ringback (speaker) audio device
The callback will be called with the volume parameter which will be 0 (muted), 50 (default volume) or other positive number.
Note: the reason why this needs a callback (and doesn’t just returns the volume as the function return value is because for some engines the volume will be requested in an asynchronous way so it might take some time to complete).
Set volume (percent for the selected device. 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
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 this with the customsipheader parameter.
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 per line: if the current line is set and there is an active call on that line
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)
· 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:’);
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 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)
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.
Call this function passing a callback with a string parameter where you will receive additional information about the previously disconnected calls.
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.
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.
Return type: boolean
Return true if the webphone is registered ("connected") to the SIP server.
Note: you can track the phone state machine also with the events callbacks or check this FAQ.
Return type: boolean
Return true if the webphone is in call, otherwise false.
Note: you can track the phone state machine also with the events callbacks.
Return type: boolean
Return true if the call is muted, otherwise will return false.
Return type: boolean
Return true if the call is on hold, otherwise will return false.
Check if communication channel is encrypted: -1=unknown, 0=no, 1=partially, 2=yes, 3=always
Will receive presence information as events: PRESENCE, status,username,displayname,email (displayname and email can be empty)
Userlist: list of sip account username separated by comma.
Function call to change the user online status with one of the followings strings: Online, Away, DND, Invisible, Offline (case sensitive)
Returns the currently used engine name as string: "java", "webrtc", "ns", "app", "flash", "p2p", "nativedial".
Can return empty string if engine selection is in progress.
Might be used to detect the capabilities at runtime (for example whether you can use the below jvoip function or not)
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
You should call this on logout (not at start) if for some reason you wish to delete the stored phone settings.
If engine is Java or the NS Service plugin, then you can access the full java 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 API function: API_Call(number) can be called like this: webphone_api.jvoip('API_Call', [number]);
Returns a string containing all the accumulated logs by the webphone (the logs are limited on size, so old logs will be lost after long run).
More details about logs can be found here.
Returns the webphone global status. The possible returned texts are the same like for getEvenetsnotifications.
You might use the events described below instead of polling this function.
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:
The passed callback function will be called when the webphone was loaded.
You can start working with the webphone library from here.
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.
The passed callback function will be called on registered (connected) to VoIP server (if the webphone has to register).
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.
The passed callback function will be called on every call state change.
Parameters:
· status: can have following values: callSetup, callRinging, callConnected, callDisconnected
· direction: 1 (outgoing), 2 (incoming)
· peername: is the other party username (or phone number or extension)
· peerdisplayname: is the other party display name if any
A simple usage example can be found here.
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
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
Note: you can get some more details about the call by using the getlastcalldetails() function.
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).
If you call this function, then the webphone will not display these messages anymore (You can silently ignore them, handle somehow or just display to the user).
If you don’t setup a callback for this, then the notifications will be displayed as auto-hiding popups.
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)
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.
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 onXXX callback instead of using 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.getEvents( 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” means simple string messages received from the webphone which you can parse with the getEvents(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 getEvents() 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 getEvents() 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:
Where line 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 phone status and once for line status.
For example you can receive the following two messages consecutively:
STATUS,1,Connected,peername,localname,endpointtype,peerdisplayname,[callid]
STATUS,-1,Connected
You might decide to parse only general status messages (where the line is -1).
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)
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
CallID: SIP session id
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]
This notification is received for incoming chat messages.
Line: used phone line
Peername: username of the peer
Presence: presence status string; one of the followings: CallMe,Available,Pending,Other,CallForward,Speaking,Busy,Idle,DoNotDisturb,Unknown,Away,Offline,Exists,NotExists,Unknown
This notification is received for incoming chat messages.
Line: used phone line
Peername: username of the sender
Text: the chat message body
This notification might be received when the other peer start/stop typing (RFC 3994):
Line: used phone line
Peername: username of the sender
Composing: 0=idle, 1=typing
This notification is received for the last outgoing chat message to report success/fail:
Line: used phone line
Peername: username of the sender
Status: 0=unknown,1=sending,2=successfully sent,3=failed to send
Text: failure reason (if Status is 3)
After each call, you will receive a CDR (call detail record) with the following parameters:
Line: used phone line
Peername: other party username, phone number or SIP URI
Caller: the caller party name (our username in case when we are initiated the call, otherwise the remote username, displayname, phone number or URI)
Called: called party name (our username in case when we are receiving the call, otherwise the remote username, phone number or URI)
Peeraddress: other endpoint address (usually the VoIP server IP or domain name)
Connecttime: milliseconds elapsed between call initiation and call connect
Duration: milliseconds elapsed between call connect and hangup (0 for not connected calls. Divide by 1000 to obtain seconds.)
Discparty: the party which was initiated the disconnect: 0=not set, 1=local, 2=peer, 3=undefined
Disconnect reason: a text about the reason of the call disconnect (SIP disconnect code, CANCEL, BYE or some other error text)
This message is sent immediately after startup (so from here you can also know that the SIP engine was started successfully).
The what parameter can have the following values:
“api” -api is ready to use
“sip” –sipstack was started
Important events which should be displayed for the user.
The following TYPE are defined: EVENT, WARNING, ERROR
This means that you might receive messages like this:
WPNOTIFICATION,EVENT,EVENT,any text NEOL \r\n
Should be displayed for the users in some way.
Various custom messages. Ignore.
Detailed logs (may include SIP signaling).
The following TYPE are defined: EVENT, WARNING, ERROR
Voice activity.
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. 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
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
“PRESENCE” peer online status
“SERVERCONTACTS” contact found at local VoIP server
“NEWUSER” new user request
“ANSWER” answer for previous request (usually http requests)
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 build within one workday on your payment.
The pricing can be found here. For the payment we can accept PayPal, credit card or wire transfer.
Contact Mizutech at [email protected]with the following details:
-your VoIP and/or web server(s) address (ip or domain name or URL)
-your company details for the invoice (if you are representing a company)
For the old “websipphone” (Java Applet based webphone) users:
Please note that this is a separate product and purchase or upgrade cost might be required. 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 the steps described below in the “How to upgrade from the old java applet websipphone” FAQ.
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 [email protected] with any issue you
might have.
Please include the followings with your message:
· exact issue description
· screenshot if applicable
· 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.
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, Chromium, Konqueror). The webphone should work also with other OS/browsers, but we are not testing every release against exotic platforms.
You will receive the followings:
· the web phone software itself (the webphone files including the engines, javascript API, html5/css skins and examples)
· the ready-to-use/turn-key softphone skin and click to call button
· latest documentations and code examples
· invoice (on request or if you haven’t received it before the payment)
· support on your request according to the license plan
Yes.
You can fully customize the webphone yourself by its numerous configuration options. However if you have some specific requirement which you can’t handle yourself, please contact us at [email protected]. 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).
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).
· A webserver (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
· Optional if you need better control on WebRTC: WebRTC capable SIP server or WebRTC-SIP gateway (both options are freely available)
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.
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, 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: .dmg MIME type: application/x-apple-diskimage
· 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)
The webphone works with any SIP capable voip server/softswitch/PBX including Asterisk, FreePBX, Huawei, Cisco, Mizu, 3CX, Voipswitch, Brekeke and many others. You don’t necessarily need to have your own SIP server to use the webphone as you can use any SIP account(s) from any VoIP provider.
The web phone is
using the SIP protocol standard to communicate with VoIP servers and
sofswitches. Since most of the VoIP servers are based on the SIP protocol today
the webphone should work without any issue. Some modules (WebRTC and Flash)
might require specific support by your server or a gateway to do the
translation to SIP, however these modules are optional, gateway software are
available for free and also mizutech includes its own free tier service (usable
by default with the webphone).
If you have any incompatibility problem, please contact [email protected] 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.
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)
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
· Works also behind corporate firewalls (auto tunnel over TCP/HTTP 80 if needed)
· Combines modern browser technologies (WebRTC, opus) with VoIP industry standards (G.729, conference, transfer, chat, voice recording, etc)
· Easy to use and easy to deploy (copy-paste HTML code)
· Easy integration with your existing infrastructure since it is using the open SIP/RTP standards
· Easy integration with your existing website design
· Proprietary SIP/RTP stack guarantees our strong long term and continuous support
· Support for all the common VoIP features
· Unlike NPAPI based solutions, the webphone works in all browsers (NPAPI is not supported anymore in Chrome and Firefox also plans do drop it)
· Unlike pure WebRTC solutions, the webphone works in all browsers (webrtc doesn’t work in IE, Edge, Safari only with extra plugin downloads)
· Unlike pure WebRTC solutions, the webphone is optimized for SIP with fine-tuned settings (TURN, STUN and others)
· As a browser phone
· Integration with other web or desktop based software to add VoIP capabilities
· A convenient dialer that can be offered for VoIP endusers since it runs directly from your website
· Callcenter VoIP client for agents/operators (easy integration with your existing software)
· Ready to use web VoIP client without the need of any further development
· SIP API for your favorite JS framework such as React, jQuery, Angular, Ember, Backbone or any others or just plain/vanilla JS
· Embedded in VoIP devices such as PBX or gateways
· Click to call functionality on any webpage
· VoIP conferencing in online games
· Buy/sell portals
· WebRTC SIP client or WebRTC softphone
· Salesforce help button
· Social networking websites , facebook phone
· Integrate SIP client with jQuery, Drupal, joomla, WordPress, angularjs, phpBB, vBulletin and others as a web plugin, module or API
· As an efficient and portable communication tool between company employees
· VoIP service providers can deploy the webphone on their web pages allowing customers to initiate SIP calls without the need of any other equipment directly from their web browsers
· Customer support calls (VoIP enabled support pages where people can call your support people from your website)
· VoIP enabled blogs and forums where members can call each other
· VoIP enabled sales when customers can call agents (In-bound sales calls from web)
· Java Script phone or WebRTC SIP client
· Web dialer for Asterisk and FreePBX
· Turn all phone numbers into clickable links on your website
· Integrate it with any Java applications (add the webphone.jar as a lib to your project)
· HTTP Call Me buttons
· Remote meetings
· HTML5 VoIP
· Web VoIP phone for callcenter agents integrated with your callcenter frontend
· Asterisk integration (or with any other IP-PBX)
· Convert any SIP link (sip: URI) on web to clickable (click to call) links and replace native/softphone solutions with a pure web solution
· "css" folder: - style sheets used in skin (GUI). The style of the skin can be changed by editing "mainlayout.css" file
· "css/themes" folder: jQuery mobile specific cascading style sheets and images used by the softphone and click to call skin templates
· "images" folder: images used by the includes skins (GUI)
· “js” folder: this is for javascript
· "js/softphone" folder: GUI files. For every jQuery mobile "page" there is an equivalent JavaScript file, which handles the behavior of the page. Also there is a string resource file (stringres.js) which contains all the text displayed to the user.
· "js/lib" folder: the webphone core library files
· "oldieskin" folder: old webphone skin, which is used only in old browsers, ex: IE 6
· "sound" folder: contains sound files (for example ringtone and keypad dtmf sounds)
· “native” folder: platform specific native binaries (the webphone might load whichever needed if any, depending on the engine used)
· the root folder contains the following files:
o "favicon.ico": web page favicon
o "index.html": a start page for the examples
o "oldapi_support.js": backward compatibility with old skin. Useful for cases where the webphone was integrated using the "old" JavaScript VoIP API.
o “iframe_helper.js”: can be used if you wish to access the webphone in a separate iframe
o “minimal_example.html”: shortest implementation to make a call
o "basic_example.html": simple usage example of softphone SDK
o “incoming_example.html”: simple example to handle incoming call
o "softphone.html": GUI html file for a full featured web phone (customize this after your needs by just changing the settings)
o “click2call.html”: a ready to use click to call implementation (customize this after your needs by just changing the settings)
o "webphone_api.js": the public Javascript API of the web phone
It is possible to delete the unneeded files (for example you can delete the softphone and the oldieskin folders if you are using the webphone as an API), however you should not bother too much about these and just leave all the files on your server. This can’t have any security implications; the webphone will use only the required files for your use-case.
No, the webphone can be used on their own as a fully self-hosted solution, connecting to your VoIP server directly (Java, NS and App), via WebRTC or via Flash so you will have a solution fully owned/controlled/hosted by you without dependency on our services.
With other words: if all our server will be switched off tomorrow, you will be still able to continue using our webphone softphone.
However please note that by default the webphone might use some of the services provided by mizutech to ease the usage and to make it a turn-key solution without any extra settings to be required from your side. Most of these are used only under special circumstances and none of these are critical for functionality; all of them can be turned off or changed. The following services might be used:
· Mizutech license service: demo, trial or free versions are verified against the license service to prevent unauthorized usage. This can be turned off by purchasing a license and your final build will not have any DRM and will continue to work even if the entire mizutech network is down.
Note: this is not used at all in paid versions
· WebRTC to SIP gateway: if your server doesn’t have WebRTC capabilities but you enable the WebRTC engine in the webphone then it might use the Mizu WebRTC to SIP gateway service. Other possibilities are listed here.
Note: this might be used only if you are using the webphone WebRTC engine but your server doesn’t have support for WebRTC nor you have a WebRTC-SIP gateway.
· Flash to SIP gateway: rarely used (only when there is no better engine then Flash). Just turn it off (by setting the “enginepriority_flash” parameter to 0) or install your own RTMP server and specify its address.
Note: usually Flash is not used at all as there are better built-in engines which are supported by more than 99.9% of the browsers.
· STUN server: by default the webphone might use the Mizutech STUN service. You can change this by changing the “stunserveraddress” to your server of choice (there are a lot of free public STUN services or you can run your own: stable open source software exists for this and it requires minimal processing power and network bandwidth as STUN is basically just a simple ping-pong protocol sending only a few short UDP packets and it is not a critical service).
Note: you can use the webphone without any STUN service if your SIP server has basic NAT handling capabilities and it is capable to route the RTP if/when needed.
· TURN server: by default the webphone might use the Mizutech TURN service which can help firewall/NAT traversal in some circumstances (rarely required). You can specify your own turn server by setting the “turnserveraddress” parameter (if TURN is required at all).
Note: you can use the webphone without any TURN service if your SIP server has basic NAT handling capabilities and it is capable to route the RTP if/when needed.
· JSONP: if you set some external API to be used by the softphone skin (such as for user balance or call rating requests) and your server can’t be contacted directly with AJAX requests due to CORS, then the API calls might be relayed by the Mizutech JSONP or websocket relay. To disable this, make sure that the domain where you are hosting the web phone plugin can access your domain where your API is hosted.
Note: this might be used only in very specific circumstances (when you integrate the webphone with your own API, but your own API can’t be accessed by the webphone via normal AJAX GET/POST requests)
· HTTPS proxy: with the WebRTC engine if you are using the webphone from Chrome and your website is not secured (not https) then the webphone might reload itself via the Mizu HTTPS proxy. To disable this, host your webphone on HTTPS if you wish to use WebRTC from Chrome. API requests can be also routed via this service (such as credit or rating requests) if you are running the webphone on HTTPS but defined your SIP server API as HTTP (otherwise browser blocks requests from secure page to insecure resources)
Note: this might be used only if your website is not on HTTPS (no SSL certificate) and you are using the webphone with the WebRTC engine in Chrome.
· Tunneling/encryption/obfuscation: In some conditions the webphone might use the Mizu tunneling service to bypass VoIP blockage and firewalls. This is usually required in countries where VoIP is blocked (such as UAE or China) or behind heavy firewalls with DPI and you can turn it off by setting the “usetunneling” parameter to 0.
Note: this is a special feature which needs to be turned on by mizutech support, otherwise it is not enabled by default.
· Auto upgrade: the native components can auto-upgrade itself from Mizutech download service. This is enforced only from known old versions to know good versions (only if the new version is already used by other customers a few weeks). You can disable this by setting the “autoupgrade” to 6. (You can also set the “autoupgrade” to 5 which will also disable the upgrade of the built-in SSL certificates, but this should be avoided and upgrading the certificates can’t do any harm to your webphone. This is just to avoid expiring ssl certificates)
Note: this might be used only if you use the webphone NS engine and can be turned off.
Note: if you are using the webphone on a local LAN then these services are not required and are turned off automatically (so the webphone will not try to use these if your VoIP and/or Web server are located on local LAN / private IP).
If you need to white-list (or block for some reason) our servers, here
is the address list associated with the above services:
www.mizu-voip.com, mnt.mizu-voip.com,
rtc.mizu-voip.com, usrtcx.webvoipphone.com, usrtc.webvoipphone.com, www.webvoipphone.com
88.150.148.180, 88.150.148.182, 88.150.183.87, 204.12.197.100, 204.12.197.98,
88.150.194.53
The webphone can be configured by its parameters or dynamically via the setparameter API.
There are many ways to set its parameters. You can statically hardcode them in the webphone_api.js file, pass as URL parameters or load from a server API by setting the scurl_setparameters to point to your API (HTTP AJAX URL).
For more details see the beginning of the Parameters chapter.
WebRTC is just one of the important engines built into the webphone. The webphone works also without this engine if not available in your environment. Otherwise the webphone will automatically detect WebRTC and will use if available.
If you need more control, you have several options to deal with WebRTC:
1. Don’t use WebRTC at all. There are other engines built into the web sip phone which can be used most of the time. There are only a few circumstances when the only available engine would be WebRTC. (Although WebRTC is convenient for enduser since it doesn’t need any browser plugin in browsers where it is supported). To completely disable WebRTC, set the enginepriority_webrtc setting to 0.
2. Check if your VoIP server already has WebRTC support. Most modern VoIP server already has implemented WebRTC (including mizu VoIP server, Asterisk and others) or you might just need to add/enable a module on your server for this, so chances are high that your VoIP server can handle WebRTC natively. Just set the webrtcserveraddress setting to point to your server websocket address
3. Use the free Mizutech WebRTC to SIP service tier. This is enabled by default and it might be suitable for your needs if you don’t have too much traffic over WebRTC (the webphone will automatically start to boost the priority for other engines when you are over the free quote)
4. Use the mizutech WebRTC to SIP gateway software. We are providing this software for free for our webphone customers. (You just have to setup this near your SIP server)
5. Use any third party WebRTC to SIP gateway: There are few free software which is capable to do this task for you, including Asterisk and Dubango. (However if you don’t have any of these installed yet, then we recommend our own gateway as mentioned above)
6. Use the Mizutech WebRTC to SIP paid service. We provide dedicated WebRTC to SIP conversion services for a monthly fee if required.
The webphone can be used as a WebRTC softphone by increasing the enginepriority_webrtc to 3 or 4 (in this case it will use the other engines only when WebRTC is not supported by the browser).
Note: Latest Chrome and Opera browsers requires secure connection to allow WebRTC for both your website (HTTPS) and websocket (WSS).
First of all it is important to mention that the browser web phone works just fine without Flash.
Chances are high that you don’t need Flash at all even if available. In the rare circumstances when the only usable engine would be Flash only, the webphone can automatically use the Mizutech Flash to SIP free service. In case if somehow you wish to drive all your traffic over Flash, then you can install a Red5 server (open source free software) to handle the translation between RTMP and SIP/RTP, then set the rtmpserveraddress to point to your flash media server and increase the value of the enginepriority_flash setting.
These engines doesn’t need any special server side support and they works with old legacy SIP (all SIP servers) without any extra settings or software. When the browser VoIP plugin uses one of these engines, there is a direct connection between the engine (running in the user’s browser) and your VoIP server, without involving any intermediary relay (RTP can also flow directly between the endusers, bypassing your server. This is up to your server settings and its NAT handling features). If you wish to force the usage of Java (which can offer top quality VoIP), then make sure to install the JRE from here (if not already installed on your system) and use Firefox or IE as Chrome doesn’t have Java applet support.
The webphone is fine-tuned for Asterisk out of the box and no changes are needed to work. However if you have some special requirement, such as using the built-in WebRTC module in Asterisk, check these articles:
· Setup Web SIP client for Asterisk
WebRTC is becoming a trendy technology but it has a lot of disadvantages and problems:
· It is a moving target. The standards are not completed yet. Lots of changes are planned also for 2016. Edge just start to add a different “ORTC” implementation
· Incompatibility. WebRTC has known incompatibility issues with SIP and there are a lot of incompatibilities even between two WebRTC endpoint as browsers has different implementation and different codec support
· Not supported by all browsers. No support in Edge, IE and Safari. No support on iOS and MAC (except with extra plugin downloads). No support on older Android phones.
· Lack of popular VoIP codec such as G.729 which can be solved only by expensive server side transcoding
· It is a black-box in the browser with browser specific bugs and a restrictive API. You have little control on what is going in the background
· A WebRTC to SIP gateway required if your VoIP server don’t have built-in support for WebRTC
· Adds unneeded extra complexity. The server has to convert from the websocket protocol to clear SIP and from DTLS to RTP
Luckily the Mizu webphone has some more robust engines that can be used without these limitations and by default will prioritize these over WebRTC whenever possible, depending on available browser capabilities and user willingness. (Small non-obtrusive notification might be displayed for the enduser when a better engine is available or if a user can upgrade with one-click install).
One of the main advantages of the Mizu webphone is that it can offer alternatives for WebRTC, so you can be sure that all your VoIP users are served with the best available technology, regardless of their OS and browser.
However we do understand that WebRTC is comfortable for the endusers as it doesn’t require any extra plugin if supported by the user browser. The mizu browser hone takes full advantage of this technology and we provide full support for WebRTC by closely following the evolution of the standards.
With a WebRTC only client you would miss all the benefits that could be offered by a standard SIP/RTP client connecting directly to your VoIP server with native performance, full SIP support with all the popular VoIP codecs and without the need for any protocol conversion, directly from enduser browser.
-Not all the listed features are available from all engines (the webphone automatically handle these differences internally)
-Some platforms currently have very limited VoIP support available from browsers. The most notable is iOS where the default browser (Safari) lacks any VoIP support. The webphone tries all the best to work around about these by using its secondary engines offering call capabilities for also for users on these platforms
-Android chrome uses the speaker (speakerphone) for audio output (this is hardcoded in their WebRTC engine and hopefully they will change this behavior in upcoming new versions). This affects only the WebRTC engine and you will have normal audio output if using the App engine on Android.
-Some features might not work correctly between WebRTC and SIP. This is not a webphone limitation, but it depends completely on server side (your softswitch or gateway responsible for WebRTC-SIP protocol conversion). Presence doesn’t work between WebRTC and SIP using the Mizu public WebRTC gateway
-For chat/IM to work your server have to support SIP MESSAGE as described in RFC 3428 (Supported by most SIP servers. See also Asterisk patch or FreePBX settings)
-Video is implemented only with the WebRTC engine (the webphone will auto-switch or auto-offer WebRTC whenever possible on video request)
-Some features require also proper server side support to work correctly. For example call hold, call transfer and call forward. See your VoIP server documentation about proper setup
-The webphone doesn’t work when Private Browsing is enabled (because no outbound WebSocket connections are allowed when private browsing is enabled)
There are many browser and OS related bugs either in the browser itself or in the plugins used for VoIP (native/webrtc/java/flash). Most of the issues are handled automatically by the webphone by implementing workarounds for a list of well-known problems. Rarely there is no any way to circumvent such issues from the webphone itself and needs some adjustment on server or client side.
Some chrome versions only use the default input for audio. If you have multiple audio devices and not the default have to be used changing on chrome, Advanced config, Privacy, Content and media section will fix the problem.
Some linux audio drivers allow only one audio stream to be opened which might cause audio issues in some circumstances. Workaround: change audio driver from oss to alsa or inverse. Other workarounds: Change JVM (OpenJDK); Change browser.
Incoming calls might not have audio in some circumstances when the webphone is running in Firefox with the WebRTC engine using the mizu WebRTC to SIP gateway (fixed in v.1.8).
If the java (JVM or the browser) is crashing under MAC at the start or end of the calls, please set the “cancloseaudioline” parameter to 3. You might also set the "singleaudiostream” to 5. If the webphone doesn’t load at all on MAC, then you should check this link.
One way audio problem on OSX 10.9 Maverick / Safari when using the Java
engine: Safari 7.0 allows users to place specific websites in an "Unsafe
Mode" which grants access to the audio recording. Navigate to "Safari
->Preferences -> Security (tab) and tick "Allow Plug-ins"
checkbox. Then depending on safari version:
-from the Internet plug-ins (Manage Website Settings)" find the site in
question and modify the dropdown to "Run In Unsafe Mode".
-or go to Plug-in Settings and for the option "When visiting other
websites" select "Run in Unsafe Mode". A popup will ask again,
click "Trust"
You will be asked to accept the site's certificates or a popup will ask again,
click "Trust". Alternatively, simply use the latest version of the
Firefox browser.
Note that this java related issue is not a real problem since the webphone uses
WebRTC plugin by default on MAC (Java might be used only if you explicitly
configured the webphone browser plugin to prefer java over WebRTC)
Java in latest Chrome is not supported anymore (the webphone will
select WebRTC by default).
If for some reason you still wish to force Java, then in versions prior
September 1, 2015 it can still be re-enabled:
Go to this URL in Chrome: chrome://flags/#enable-npapi (then mark activate)
Or via registry: reg add HKLM\software\policies\google\chrome\EnabledPlugins /v
1 /t REG_SZ /d java
(By default the webphone will handle this automatically by choosing some other engine such as WebRTC unless you forced java by the engine priority settings)
Symptoms:
· If your html can’t find the webphone library files you might see the following errors in your browser console:
o Failed to load resource: …/js/lib/api_helper.js
o ReferenceError: webphone_api is not defined
· If not supported by browser or your webserver doesn’t allow the required mime types, then the page hosting the webphone might load, but you will not be able to make calls (VoIP engine will not start)
Fixes:
· Missing library: Make sure that you have copied all files from the webphone folder (including the js and other sub-folders)
· Browser support: Make sure that your browser has support for any of the implemented VoIP engines: either Java or WebRTC is available in your browser or you can use the NS engine (on Windows, MAC and Android) or the app engine (on Android and iOS)
· Web server mime settings: Make sure that the .jar and .exe mime types are allowed on your webserver so the browsers are able to download platform specific native binaries
· HTTPS: Set a SSL certificate for your website for secure http, otherwise WebRTC will not work in chrome
· Lib not found: If your webphone files are near your html (in the same folder) then you might have to set the webphonebasedir parameter to point to the javascript directory
webphonebasedir
This
setting is deprecated after 1.9 as the webphone should automatically detect its
library path automatically.
If the html page, where you are including the webphone, is not in the same directory as the webphone, then you must set the "webphonebasedir" as the relative path to the webphone base directory in relation to your html page.
The base directory is the "webphone" directory as you download it from Mizutech (which contains the css,js,native,... directories).
For example if your page is located at http://yoursite.com/content/page.html and the webphone files are located at http://yoursite.com/modules/webphone then the webphonebasedir have to be set to '../modules/webphone/'
The webphonebasedir parameter must be set in the webphone_api.js file directly (not at runtime by webphone_api.webphonebasedir).
Default is empty (assumes that your html is in the webphone folder).
· NS engine download not found: you might have to set the nativepluginurl parameter to point to the ns installer file.
nativepluginurl
(string)
This setting is deprecated after 1.9 as the webphone should automatically detect its library path automatically.
The absolute location of the Native Service/Plugin installer. In most of the cases this is automatically guessed by the webphone, but if for some reason (for example: you era using URL rewrite) the guessed location is incorrect, then it can be specified with this parameter.
The Service/Plugin installer is located in webphone package "native" directory.
Example:
“https://mydomain.com/webphopne/native/WebPhoneService_Install.exe”
Default value is empty.
Make sure that:
-you have set your SIP server address:port correctly (from the user interface or “serveraddress” parameter in the webphone_api.js file)
-make sure that you are using a SIP username/password valid on your SIP server
-if you are using the WebRTC engine with the Mizu WebRTC SIP gateway service, make sure that your firewall or fail2ban doesn’t block the gateways. You should white-list rtc.mizu-voip.com and usrtc.webvoipphone.com
-make a test from a regular SIP client such as mizu softphone or x-lite from the same device (if these also doesn’t work, then there is some fundamental problem on your server not related to our webphone or your device firewall or network connection is too restrictive)
-send us a detailed client side log if still doesn’t work with loglevel set to 5 (from the browser console or from softphone skin help menu)
Make a
test call first from a simple SIP client such as mizu softphone or x-lite
By default only the PCMU,PCMA, G.729 and the speex ultra-wideband
codec’s are offered on call setup which might not be enabled on your server or
peer UA.
You can enable all other codec’s (PCMA, GSM, speex narrowband, iLBC and G.729 )
with the use_xxx parameters set to 2 or 3 (where xxx is the name of the codec: use_pcma=2, use_gsm=2, use_speex=2,use_g729=2,use_ilbc=2).
Some servers has problems with codec negotiation (requiring re-invite which is
not support by some devices). In these situations you might disable all codec’s
and enable only one codec which is supported by your server (try to use G.729
if possible. Otherwise PCMU or PCMA is should be supported by all servers)
If you receive the “ERROR, Already in call with xxx” error on outbound call attempts and you wish to enable multiple calls to/from the same number, set the disablesamecall parameter to 0.
If still doesn’t work send us a detailed client side log with loglevel set to 5 (from the browser console or from softphone skin help menu)
-Call disconnection immediately upon setup can have many reasons such
as codec incompatibility issues, NAT issues, DTLS/SRTP setup problems or audio
problems. If you are not sure, send a detailed log to [email protected]
-If the calls are disconnecting after a few second, then try to set the
“invrecordroute” parameter to “true” and the “setfinalcodec” to 0.
-If the calls are disconnecting at around 100 second, then most probably you
are using the demo version which has a 100 second call limit.
In short:
Yes, the webphone works fine on private networks by default, without the need of any configuration changes.
Note: It is completely normal to use the webphone on LAN’s (browser client with private IP). This FAQ refers to the case when the SIP server (set by the “serveraddress” parameter where the webphone will register to) or Web server (from where you load your webpage embedding the webphone) is located on private IP.
Details:
The webphone can be
used also on local LAN’s (when your VoIP server and/or Web server are on your
private network).
-The NS and Java engines will connect directly to your server as a normal SIP
softphone does.
-For WebRTC to work you will need a WebRTC to SIP gateway on your LAN or your
PBX have to support WebRTC, otherwise this engine will not be picked up (this
is handled automatically). You should also host your webpage on https (SSL
certificate installed on your Web server) for WebRTC to work in Chrome.
-The webphone could use the Mizutech STUN, TURN, JSONP and HTTPS gateway
services by default, however these are not required on local LAN’s (the
webphone will detect this automatically and will not try to use these services
while on local LAN).
With other worlds,
if you wish to work with the webphone on local LAN and your VoIP server doesn’t
have WebRTC support or your webserver doesn’t have SSL installed for the domain
you are using (HTTPS), we recommend to:
-use the NS engine on Windows (this should be preferred and auto-selected
anyway for these circumstances)
-use Firefox with Java on other platforms (because the built-in Java applet
engine will provide top quality VoIP for you)
The webphone can be used also without internet connection with some
limitations. An easy workaround for all this would be to enable at least CA
verifications (SSL certificate verifications) to the internet, however if this
is not possible then the following applies:
-WebRTC in Chrome needs https (secure http), which will work only with a local
policy, otherwise the browser will not be able to verify the SSL certificate
against public CA. If you can’t setup a local CA or browser rule for this, just
disable WebRTC (or use Firefox instead of Chrome if you need WebRTC without
certificate).
-Java applets need to be signed and on startup the JVM will have to pass the
code verification signature. Workaround: Just disable the Java engine or add
the applet location to the exception site list
-The NS engine can be used from unsecured http in local LAN’s with no issues
(on https you need to add the localhost.daplie.com to the browser security
exception list)
These circumstances will be automatically handled by the webphone, always selecting the best suitable engine if it has at least one available and unless you change the engine priority related settings.
If you are using the webphone in a controlled environment (where you have control over the clients, such as call-centers) then you might force the NS or Java engines by disabling or lowering the priority for the WebRTC engine (enginepriority_webrtc = 1). This is because NS and Java are more native for SIP/RTP and might have better quality, more features and lower processing costs on your server. The big advantage of WebRTC is that it can work without any extra plugin download/install, however in a controlled environment you can train your users (such as the callcenter agents) to allow and install the NS engine when requested and this one-time extra action will reward with long term quality improvement.
In case if you wish to include the webphone globally to your websites to be present on all pages (such as a “call to support” widget flying on the bottom-right side of your page), make sure to don’t let the webphone to auto-initialize itself automatically with each page load/reload because this might slow-down the responsivity of your website.
For this just set the “autostart” parameter to “false”.
In this call you can delay the VoIP engine initialization to the point when the enduser actually wish to interact with your VoIP US (such as clicking on your click to call button).
You just have to include the “webphone_api.js” to your page and create multiple VoIP UI elements.
For example you might have a contact list (or people list) displayed on your page, with a “Dial” button near each other. You don’t even need to initialize the webphone on your page load (set the “autostart” parameter to “false”). Just use the webhone_api.call(number) function when a user click on the dial button and the webphone will initialize itself on the first call.
The softphone user interface (softphone.html) can’t be included multiple times in a page (if you really need multiple phone UI on your page, then use separate iFrame for them).
Below are a few (both recommended and NOT recommended) methods to load the webphone into your webpage:
1. Load "webphone_api.js" using a script tag in the <head> section of your web page. This is actually not “on demand”, the webphone will be loaded when the page is loaded.
2. Load "webphone_api.js" on demand, by creating a <script> DOM element. Below is an example function which loads the script into the <head> section of the page:
function insertScript(pathToScript)
{
var addScript = document.createElement( "script" );
addScript.type = "text/javascript";
addScript.src = pathToScript;
document.head.appendChild( addScript );
}
3. The webphone can also be loaded into an iframe on demand. To have access to the webphone API in the iframe from the parent page, you have to follow the below two steps:
a. set the iframe's "id" attribute to "webphoneframe", for example: <iframe id="webphoneframe" src="softphone.html" width="300" height="500" frameborder="0" ></iframe>
b. include the "iframe_helper.js" file into your parent html page <head> section
Not recommended:
1. The web phone can be loaded on demand using document.write(), but it is a bad practice to call document.write() after the page has finished loading.
2. The web phone can also be loaded using any AMD (Asynchronous Module Loader). This is not recommended, because webphone also uses AMD (Require JS) to load its modules, so it won't improve performance, but it can lead to conflict between AMD loaders.
The webphone is a client side software and pages/tabs in your browser are separate entities, so a new page doesn’t know anything about an old one (except via server side sessions, but it is impossible to transfer live JavaScript object via your server in this way).
There is no way to
keep the webphone session alive between page loads.
Instead of this, you should choose one of the followings:
· run the webphone in a separate page (on its own dedicated page, so the enduser can just switch to this window/tab if needs to interact with the webphone)
· run the webphone in an frame
· load your content dynamically (Ajax)
If this functionality is a must for your project, check the following FAQ for the possibilities.
There might be situations when you might wish to use the same webphone instance on multiple pages (opened in different browser tab or windows).
For example to start a call on a page, open a second page and be able to hangup the call on this second page.
First of all, it is important to note that the webphone is client side software (it is impossible to implement a voip client which would run on the server side).
This means that from the browser perspective, each of the pages are treated completely separately (Only your web server knows that those belongs together called a “session”). Each page load or reload will completely re-initialize also the webphone (if the webphone is included in the page). With other worlds: multiple pages opened from your domain doesn’t know about each other at all and one page can’t access the other one (except if you send some ajax message via your web server, but this kind of message passing is useless in this case since you can't transfer the whole webphone javascript object).
This means that you should avoid the above use-case and just launch the webphone on a separate page in this case, so the enduser can switch to the page dedicated for the webphone if need to interact with a call (make a call, hangup current call or other operations such as mute, conference, dtmf).
Here are a few ways to implement such functionality:
· Simple data sharing: If you just want to share some details across your pages, then you can do it via cookies or from pure javascript using the window.name reference. (This can be used only for simple data sharing, but not to share live JavaScript objects such as the webphone)
· NS engine: It is possible with the NS engine to have the webphone survive page (re)loads or opening new pages on your website. Contact mizutech if you are interested in this (works only with the NS engine)
· Using a global webphone object: There is way to share a global webphone instance across the opened pages: using the window.opener property which is a reference to the window that opened the current window. This means that you can access your global webphone object from secondary opened pages via the opener reference (Find an example for this below)
· Avoid this use-case and just launch the webphone on a separate page in this case, so the enduser can switch to the page dedicated for the webphone if need to interact with a call (make a call, hangup current call or other operations such as mute, conference, dtmf).
Here is a simplified example to access the webphone object via window.opener:
//Important: Set the “autostart” parameter to “false” in the webphone_api.js parameters section to avoid auto initialization of the webphone on all pages where included (we will start the webphone explicitly when needed)
//store the wopener variable to be used here and also on subsequent pages (useful if we open a third page from the second and so)
var wopener = window; //set to this document
if(window.opener && window.opener.webphone_api)
{
wopener = window.opener; //set to parent page document
}
if(wopener.wopener && wopener.wopener.webphone_api)
{
wopener = wopener.wopener; //the parent page might also loaded from its own parent, so load it from there
}
//create a reference to the webphone so we can easily access it on this page via this variable
var wapi = webphone_api;
//Initialize your webphone if not initialized yet
if(wopener && wopener.webphone_api)
{
//load the wapi instance from the parent page in this case
wapi = wopener.webphone_api;
//check if already initialized
if(wapi.isstarted != 1)
{
wapi.isstarted = 1;
//we are staring the engine here, however you can delay the start if you wish to the point when the user actually wish to use the phone such as making a cal; wapi.start();
}
//else already initialized by parent
}
else if(wapi && wapi.isstarted != 1)
{
//we are the first page
wapi.isstarted = 1;
wopener = window; //set the wopener to point to this page
wapi.start();
}
//use the phone api on this page
function onCalllButtonClick()
{
if(wapi) wapi.call();
else alert('error: no webphone found (webphone_api.js not included?)');
}
You can find a better/fully working example in the webphone package: multipage_example.html.
Sometimes you might have to change the settings for each session (for example changing the user credentials).
In these situations it might happen that the webphone is still using the old setting (which you have set for the previous session and not for the current one).
Usually this might happen if the webphone is already started and registered with the old parameters before it loads the new parameters (For example before you call the setparameter() API with the new values).
To prevent this, you should set the "autostart" parameter to "false" in the webphone_api.js
You can also set the “register” parameter to "0".
The use the start() and/or register() functions only after the webphone were supplied with the new parameters.
Note:
The webphone is also capable to load it’s parameters from the URL. Just us the format required (wp_username, wp_password and others).
It is not needed to call the register() after start() because the start() will automatically initiate the register if the server/username/password is already preset when it starts and if you leave the register parameter at 1.
Certain operations (such as file download controls) might trigger window.unload events which might trigger webphone unregistrations.
You might have to prevent these event being triggered by your controls by using this technique (It can be applied to any element such as <div>,<a>,<button>)
For RTP statistics increase the log level to at least 3 and then after
each call longer than 7 seconds you should see the following line in the log:
EVENT, rtp stat: sent X rec X loss X X%.
If you set the “loglevel” parameter to at least “5” than the important rtp and
media related events are also stored in the logs.
You can also access the details about the last call from the softphone skin
menu “Last call statistics” item.
In the SIP protocol the client endpoints have to send their (correct) address in the SIP signaling, however in many situations the client is not able to detect it’s correct public IP (or even the correct private local IP). This is a common problem in the SIP protocol which occurs with clients behind NAT devices (behind routers). The clients have to set its IP address in the following SIP headers: contact, via, SDP connect (used for RTP media). A well written VoIP server should be able to easily handle this situation, but a lot of widely used VoIP server fails in correct NAT detection. RTP routing or offload should be also determined based in this factor (servers should be always route the media between 2 nat-ed endpoint and when at least one endpoint is on public IP than the server should offload the media routing). This is just a short description. The actual implementation might be more complicated.
With the WebRTC engine make sure that the STUN and TURN settings are set correctly (by default it will use mizu services which will work fine if your server is on the public internet).
For NS and Java engines you may have to change the webphone
configuration according to your SIP server if you have any problems with
devices behind NAT (router, firewall).
If your server has NAT support then set the use_fast_stun and use_rport
parameters to 0 and you should not have any problem with the signaling and
media for webphone behind NAT. If your server doesn’t have NAT support then you
should set these settings to 2. In this case the webphone will always try to
discover its external network address.
Example configurations:
If your server can work only with public IP sent in the signaling:
-use_rport 2 or 3
-use_fast_stun: 1 or 2
If your server can work fine with private IP’s in signaling (but not when a
wrong public IP is sent in signaling):
-use_rport9
-use_fast_stun: 0
-optionally you can also set the “udpconnect” parameter to 1
Asterisk is well known about its bad default NAT handling. Instead of detecting
the client capabilities automatically it relies on pre-configurations. You
should set the "nat" option to "yes" for all peers.
More details:
http://www.voip-info.org/wiki/view/NAT+and+VOIP
http://www.voip-info.org/wiki/view/Asterisk+sip+nat
http://www.asteriskguru.com/tutorials/sip_nat_oneway_or_no_audio_asterisk.html
Use the following settings if you have 2 voip servers:
· serveraddressfirst: the IP or domain name of the first server to try
· serveraddress: the IP or domain name of the next server
· autotransportdetect: true
· enablefallback: true
In this way the webphone will always send a register to the first server first and on no answer will use the second server (the “first” server is the “serveraddressfirst” at the beginning, but it can change to “serveraddress” on subsequent failures to speed up the initialization time)
Alternatively you can also use SRV DNS records to implement failover or load balancing, or use a server side load balancer.
The WebRTC functionality highly depends on your OS/browser and server side WebRTC –SIP module. Check the followings if the webphone is using the WebRTC engine and you have difficulties:
· Make sure that your browser has support for WebRTC and it works. Visit the following test pages: test1, test2, test3
· Make sure to run the webphone from secure http (https) otherwise WebRTC will not work in Chrome and Opera
· If you have set the “webrtcserveraddress” parameter to point to your server or gateway, make sure that your server/gateway has WebRTC enabled and test it also from some other client such as sipml5: config; test
· You might contact mizutech support with a detailed log about the problem
· If you are unable to fix webrtc in your setup then you might disable the webrtc engine by setting the enginepriority_webrtc parameter to 0 or 1.
See the other possibilities here.
You might receive similar popups or the calls just fails if you are using the WebRTC engine but haven’t enabled the browser to use your microphone/camera device or denied it previously (Technically the WebRTC getUserMedia() function call will fail in this case).
Normally before WebRTC calls your browser should popup a box asking to allow microphone access. You should click on the Ok/Yes/Allow/Share/Always Share button there.
However if you
clicked on No/Not/Don’t Share/Deny/Always Deny button sometime before then the
browser might not popup with this qu
estion again.
· In this case you should see a red icon in your browser address bar and click on “Allow” from there.
· You can also allow a website from your browser security/privacy settings.
(In Chrome: settings -> show advanced settings -> privacy section -> content settings -> microphone -> manage exceptions).
· In some situations the browser might not ask for permission, just silently fails. This happens in Chrome if your website is not on secure https (Chrome doesn’t allow WebRTC from http) or if you are using an invalid or self-signed certificate (yes, Chrome might just silently fail with self-signed certificates).
· Also you must use wss (secure websocket) for your WebRTC server WebSocket connection, otherwise Chrome will fail on unsecure ws.
· In some situations the browser might not ask for permission, just silently fails. This happens in Chrome if your website is not on secure https (Chrome doesn’t allow WebRTC from http) or if you are using an invalid or self-signed certificate (yes, Chrome might just silently fail with self-signed certificates).
Also you must use wss (secure websocket) for your WebRTC server WebSocket connection, otherwise Chrome will fail on unsecure ws.
· Chrome also might fail if you try to run WebRTC from html launched from local file system
The workaround for this is to lauch with --allow-file-access-from-files parameter
(Something like this on windows: "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --allow-file-access-from-files C:\path\softphone.html)
· Also test your browser webrtc capabilities from here and here.
The webphone is capable to handle the situation when calls are beeing connected without a microphone device. This is useful only if the user needs to listen for some audio such as an IVR.
The only exception is if you use it’s WebRTC engine with Firefox since Firefox require the MediaStream to have a valid MediaStreamTrack, but this is returned from getUserMedia() which fails on Firefox if the user don't have a microphone with the following error:
WRTC, ERROR, InternalError: Cannot create an offer with no local tracks, no offerToReceiveAudio/Video, and no DataChannel.
This is a bug in Firefox already reported also by others as you can see here and here.
This situation is handled automatically by the webphone or you can force calls to always pass or always fail via the checkmicrophone setting.
Call quality is influenced primarily by the followings:
· The engine used (Java and NS tends to have the best quality)
· Codec used to carry the media (wideband has better quality)
· Network conditions (check your upload speed, packet loss, delay and jitter)
· Hardware: enough CPU power and quality microphone/speaker (try a headset, try on another device)
· AEC and denoise availability
If you have call quality issues then the followings should be verified:
· whether you have good call quality using a third party softphone from the same location (try X-Lite for example). If not, than the problem should be with your server, termination gateway or bandwidth issues.
· make sure that the CPU load is not near 100% when you are doing the tests
· make sure that you have enough bandwidth/QoS for the codec that you are using
· change the codec (disable/enabled codec’s with the “codec” parameter)
· deploy the mediaench module (for AEC and denoise). (Or disable it if it is already deployed and you have bad call quality)
· webphone logs (Check audio and RTP related log entries. Also check the statistics after call disconnect.)
· wireshark log (Check missing or duplicated packets)
1. Review your server NAT related settings
2. Set the “setfinalcodec” parameter to 0 (especially if you are using Asterisk or OpenSIPS)
3. Check stun and turn settings (might be used for WebRTC if your server is not on the public internet, doesn’t route the RTP or you need peer to peer media routing)
4. Set use_fast_stun, use_fast_ice and use_rport to 0 (especially if you are using SIP aware routers). If these don’t help, set them to 2.
5. If you are using Mizu VoIP server, set the RTP routing to “always” for the user(s)
6. Make sure that you have enabled all codec’s
7. Make a test call with only one codec enabled (this will solve codec negotiation issues if any)
8. Try the changes from the next section (Audio device cannot be opened)
9. If you still have one way audio, please make a test with any other softphone from the same PC. If that works, then contact our support with a detailed log (set the” loglevel” parameter to 5 for this)
If you can’t hear audio, and you can see audio related errors in the
logs (with the loglevel parameter set to 5), then make sure that your system
has a suitable audio device capable for full duplex playback and recording with
the following format:
PCM SIGNED 8000.0 Hz (8 kHz) 16 bit mono (2 bytes/frame) in little-endian
If you have multiple sound drivers then make sure that the system default is workable or set the device explicitly from the webphone (with the “Audio” button from the default user interface or using the “API_AudioDevice” function call from java-script)
To make sure that it is a local PC related issue, please try the webphone also from some other PC.
You might also try to disable the wideband codec’s (set the use_speexwb and use_speexuwb parameters to 0 or 1).
Another source for this problem can be if your sound device doesn’t support full duplex audio (some wrong Linux drivers has this problem). In this case you might try to disable the ringtone (set the “playring” parameter to 0 and check if this will solve the problem).
If these don’t help, you might set the “cancloseaudioline” parameter to 3 and/or the "singleaudiostream” to 5.
Depending on your server configuration, you might not have ringback
tone or early media on call connect.
There are a few parameters that can be used in this situation:
· set the “changesptoring” parameter to 3
· set the “natopenpackets” parameter to 10
· set the “earlymedia” parameter to 3
· change the “use_fast_stun” parameter (try with 0 or 2)
One of these should solve the problem.
Make sure that your softswitch has support for IM and it is enabled. The webphone is using the MESSAGE protocol for this from the SIP SIMPLE protocol suite as described in RFC 3428.
Most Asterisk installations might not have support for this by default. You might use Kamailio for this purpose or any other softswitch (most of them has support for RFC 3428).
If subsequent chat messages are not sent reliably, set the “separatechatdiag” parameter to 1.
To be able to receive calls, the webphone must be registered to your server by clicking on the “Connect” button on the user interface (or in case if you don’t display the webphone GUI than you can use the “register” parameter with supplied username and password, or via the register() JavaScript SIP API)
Once the webphone is registered, the server should be able to send incoming calls to it.
Other common causes include:
-NAT: if your browser webphone is behind NAT, check if your server can handle NAT’s properly (via rport and other settings). As a workaround you might try to start the webphone with use_fast_stunparameter set to 0 and if still not works then try it with 2.
-call fork: if you are registered from multiple locations with the same credentials then your server must be able to support call fork to ring on all devices. Otherwise make sure to use the same credentials only from one location and one protocol (don’t mismatch SIP and WebRTC logins)
-make sure that autoignore or DND (do not disturb) are not set
-check if your server is sending the INVITE to the proper IP:port (from where it received the latest valid REGISTER from the webphone)
If the calls are still not coming, send a detailed log from the webphone (set the loglevel parameter to 5) and also from the caller (your server or remote SIP client)
This depends on the circumstances and there is no such thing as the "best codec". All commonly used codec's present in the webphone are well tested and suitable for IP calls with optimized priority order by default, regarding to environment (client device, bandwidth, server capabilities).
This means that usually you don’t need to change any codec related settings except if you have some special requirement.
Between webphone users (or other IP to IP calls) you should prefer wideband codec's (this is why you just always leave the opus and speex wideband and ultra wideband with the highest priority if you have calls between your VoIP users. These will be picked for IP to IP calls and simply omitted for IP to PSTN calls).
Otherwise G.729 provides both good quality and low bandwidth if this codec is available for you.
G.711 (PCMU/PCMA) is always supported and they offer good call quality using some more bandwidth then G.729.
The
other available codec’s are iLBC and GSM. These offers a good
compromise between quality and bandwidth usage if the above mentioned opus and
G.729 is not supported by your server or the other peer.
To calculate the bandwidth needed, you can use this
tool. You might
also check this blog entry: Codec misunderstandings
With the webphone you don’t need to change the codec settings except if you have some special requirement. With the default settings the webphone is already optimized and will always choose and negotiate the “best” available codec.
The webphone is a favorite VoIP client for callcenter as it can be easily integrated with any frontend or CRM and it can be used for both inbound and outbound campaigns. The integration usually consists of database lookup for caller/callee details on incoming/outgoing calls so the agent can see all the details about the customer.
There are multiple ways to implement such kind of database/CRM lookups:
-From JavaScript catch the call init from the onCallStateChange callback (on status = callSetup) and load the required data by an AJAX call to your backend
-Via the “scurl_displaypeerdetails”: implement a HTTP API on your server which will return the peer details and set the scurl_displaypeerdetails webphone setting to point to this API URL
-If your backend has VoIP client integration capabilities, then just implement its specification. For example here is a tutorial about integrating the webphone with salesfoce
There are many other things what you can do for a better integration, such as processing cdr records or recording the calls however most of these can be easily controlled by the webphone parameters or implemented via the API.
We recommend use the NS and/or the Java VoIP engine in call-centers since these provides native call processing, connecting directly to your SIP server without the need of any extra layer such as WebRTC. More details here.
The “P2P” term is misleading sometimes and it can have the following meanings:
· Server assisted phone to phone calls. This means that both endpoints will be called by the server and once connected, the server interconnects the 2 endpoint. It can be useful when the client device doesn’t have internet connection or doesn’t have any platform to enable VoIP, such as an old dumb phone. Exactly for this concept we refer with the P2P engine.
· Peer to peer connection: useful to bypass the server for media or both media and signaling (peer to peer media routing is more important here).
· Sometimes it might refer to peer to peer encryption (or end to end E2E encryption) which means that the server (if used) is a passive party from the encryption point of view and is unable to decrypt the streams between the endpoints (just forwards the stream if needed)
The webphone also has support for peer to peer encrypted media with direct streaming (this is done via ICE techniques with automatic failback to routing via server if a direct path can’t be found.)
These terms might be also misleading especially for user with no VoIP/SIP knowledge.
Register or registration provides a way for the SIP clients to connect/login to the server so the server will learn the client address and will be able to route calls and other message to it. It is implemented by sending a REGISTER message by the SIP signaling. The server might or might not challenge the request with an authentication request (in this case the client will send a second REGISTER with a hash of its credentials). On credentials we refer to the sip username/password.
However:
· Register is optional and is not really needed if your client will make only outbound calls (not used to accept calls or chat)
· You can configure your server to not require registrations (actually most server doesn’t require it by default, however in some servers the default configuration is to not allow calls if there was no previous successful registration)
· For the webphone you can set the “register” parameter to 0 to skip registration (so the webphone will not send REGISTER requests)
· Disabling registration is not a security treat since the server will do the same authentication for each call as it does for registrations (so the clients will not be able to make calls if their credentials are incorrect)
· You can also configure your server to allow blind registrations. This means that the client might send the REGISTER with any credentials (any username/password) and it will be unconditionally accepted
· You can also configure your server to allow blind calls. This means that the client might send the INVITE with any credentials (any username/password) and it will be unconditionally accepted (the call will be routed)
· If your server accepts blind registrations and calls then you can set the webphone password parameter to any value since it will not be checked or used anyway. (You can set it to “nopassword” as a special value to hide it from settings and login forms)
· There are situations when even the username doesn’t matter (if you wish to make only unconditional outbound calls or calls to ivr). However you must also set the username parameter to some value or allow the user to enter something since it is required for the SIP messages. You might set it to “Anonymous” in this case.
Sometime you might use a separate username/password combination on your website then on your SIP server. In this case you can auto-provision the webphone with the sip credentials if the user is already logged in on your website to avoid typing a different username/password. This can be implemented multiple ways:
· by dynamically generating the webphone settings from a server script (set the username/password from the server since there you already know the signed in user details and you can grab the SIP credentials from your softswitch database)
· implement a custom API which returns the sip credentials and set it’s URI as the “scurl_setparameters” parameter (webphone will call scurl_setparameters URI and wait for the (key/value) parameters in response and once received it will start the webphone)
· handle it from JavaScript (use the setparameter() API to set the username/password)
· implement some alternative authentication method on your SIP server (for example based a custom SIP header which you might set from the web session using the setsipheader() API call)
Depending on the settings, the webphone will automatically register upon startup or you can explicitly connect to the server by calling the register() API.
To find out whether the webphone is successfully registered or not, you can use the isregistered() API to query the status at any time.
You can also receive notifications about the registration status via the followings callbacks:
· onRegistered: callback called on successful registration
· onUnRegistered: callback called after “logoff”
· onDisplay: callback called when register fails with the message containing one of the following text:
o Connection lost
o No network
o No response from server
o Server lost
o Authentication failed
o Rejected by server
o Register rejected
o Register expired
o Register failed
For outgoing calls the Caller ID (CLI/A number display) is controlled by the server and the application at the peer side (be it a VoIP softphone or a pstn/mobile phone).
You can use the following parameters to influence the caller id display at the remote end:
o username (this is used for both SIP username and authentication username if sipusername is not set)
o sipusername (if this parameter is set, then the “sipusername” will be used for authentication and the “username” parameter as the SIP username)
o displayname (SIP display name)
If you set all these parameters, then it will be sent in the SIP signaling in the following way (see the uppercase worlds):
INVITE sip:[email protected] SIP/2.0
From: "DISPLAYNAME" <sip:[email protected]>;tag=xyz
Contact: "DISPLAYNAME"<sip:[email protected]>
Remote-Party-ID: "DISPLAYNAME" <sip:[email protected]>;party=calling;screen=yes;privacy=off
Authorization: Digest username="SIPUSERNAME",realm="sipdomain.com" …
Some VoIP server will suppress the CLI if you are calling to pstn and the number is not a valid DID number or the webphone account doesn’t have a valid DID number assigned (You can buy DID numbers from various providers).
The CLI is usually suppressed if you set the caller name to “Anonymous” (hide CLI).
If required by your SIP server, you can also set a Caller Identity header as a “customsipheader” parameter. (P-Preferred-Identity/P-Asserted-Identity/Identity-Info)
For incoming calls the webphone will use the caller username, name or display name to display the Caller ID. (SIP From , Contact and Remote-Party-ID fields).
Here is a simple example:
webphone_api.onCallStateChange(function (event, direction, peername, peerdisplayname, otherdetails)
{
if (event === 'callSetup')
{
if (direction == 1)
{
// means it is an outgoing call
}
else if (direction == 2)
{
// means it is an icoming call
document.getElementById('icoming_call_layout').style.display = 'block'; // display Accept, Reject buttons
/*
<div id="icoming_call_layout">
<button onclick="webphone_api.accept();">Accept</button>
<button onclick="webphone_api.reject();">Reject</button>
</div>
*/
}
}
// end of a call, even if it wasn't successfull
if (event === 'callDisconnected')
{
document.getElementById('icoming_call_layout').style.display = 'none'; // hide Accept, Reject buttons
}
});
More details and examples can be found here.
If you have changed any parameter in the webphone_api.js, make sure that you see the latest version if you open the js file directly in the browser like: www.yourdomain.com/webphonefolderpath/webphone_api.js
If you don’t see the recent settings that means that the old version was cached by your browser, by your webserver or some intermediary proxy.
The webphone might store/cache previous settings in cookie and indexDB "localforage".
Refresh the browser cache by pressing F5 or Ctrl+F5.
In Firefox you can clear all settings related to the webphone by pressing ALT, then select “Show All History” from the “History” menu, then right click to your domain and select “Forget About This Site”.
Make sure that you don’t have some caching proxy on the path. A sure way to bypass all caching is to change the server folder (deploy in a “test2” directory and launch from there). If you are using the NS engine, then you might need to upgrade the webphone service.
Once a parameter is set, it might be cached by the browser phone and used even if you remove it later.
To prevent this, set the parameter to “DEF” or “NULL”. So instead of just deleting or setting an empty value, set its value to “DEF” or “NULL”. “DEF” means that it will use the parameter default value. For number values instead of removing or commenting them out, you might change to their default value instead.
Also check this FAQ if you made a recent upgrade but still seems that the old version is running.
If still doesn’t work, you should check from another PC (to make sure that nothing is preinstalled/cached on your PC).
If still doesn’t work, send a detailed log to Mizutech support.
First you should backup your existing webphone folder.
Extract the zip supplied by Mizutech and replace all the files in your webphone folder with the new content, but make sure to:
-preserve the settings: if you have set the webphone configuration to the webphone_api.js parameters, make sure to set them also in the new file
-don’t overwrite other files where you made changes if any (for this reason it is not recommended to make any changes in the webphone files)
Although the webphone_js.api file is rarely changed, we don’t recommend writing code in this file. Use your separate js files for your project and just include the webphone_api.js instead of using it for custom code.
Also make sure to adjust the minserviceversion if you have this set to any value, otherwise you might have to upgrade the NS service manually or the new webphone will continue to use the old version (which is not a problem most of the time, but we don’t recommend to use very old outdated versions).
Note: new versions of the webphone is always backward compatible and backward API compatibility is always ensured except occasional minor/compatible changes so you can upgrade without any changes in your code. However each you version contains changes in the VoIP engines so you should always verify if it fulfills your needs and downgrade to the previous version if you encounter any issues (Then you might try the upcoming release again to see if your issue were fixed).
Make sure that you are actually using the new version. Refresh the browser cache by pressing F5 or Ctrl+F5. Make sure that you don’t have some caching proxy on the path. A sure way to bypass all caching is to change the server folder (deploy in a “test2” directory and launch from there). If you are using the NS engine, then you might need to upgrade the webphone service.
If your webphone is using the NS engine, then it might be possible that the PC is running an old version. This can be updated in the following ways:
-manually as described below
-set the minserviceversion parameter. If higher than the current installed version then it will ask the user to upgrade (one click install)
Note: the NS service version for v.1.9 softphone is 7 (so you can set the “minserviceversion” setting to 6 to force the latest version for all users, but this is already enforced by default)
-auto-upgrade: the core of the ns engine is capable to auto upgrade itself if new versions are found (you can disable this by setting the “autoupgrade” parameter to 6)
(In the NS service there is a built-in SSL certificate for localhost. This is also capable for auto-upgrade when new certificates are found unless you set the “autoupgrade” to 5)
Also check this FAQ if your new settings are not applied.
If still doesn’t work, you should check from another PC (to make sure that nothing is preinstalled/cached on your PC).
If still doesn’t work, send a detailed log to Mizutech support.
In some situation under Windows OS the webphone might install an NT service named “Webphone” (This is the NS service plugin and it is installed only on user opt-in)
· Disabling: If you don’t wish to use the NS engine, you can just disable the service (set startup type to Manual and Stop the service) or set the enginepriority_ns to 0
· Uninstalling: The service has its own uninstaller, so you can easily uninstall it from the Add/Remove Programs control panel. It can be also removed with the –uninstall parameter. Example: C:\Program Files (x86)\WebPhoneService\WebPhoneService.exe –uninstall.
· Re(installing): The install can be done from the softphone skin by just going to menu -> settings -> advanced settings -> sip settings -> voip engine -> select the NS engine. That should offer the download of the new version (if the service is not already running, so if you need to install a new version, then you should uninstall or stop it first).
You can also (re)install/upgrade manually by running the “WebPhoneService_Install.exe” from the webphone\native folder. (You can also download it from your webserver: http://yourdomain.com/path_to_webphone/native/WebPhoneService_Install.exe or from the webphone package provided by mizutech). Just run the executable and it will install the NS engine automatically (this should work even if the service is already running as it will automatically update your old version)
Note: this is relevant only for our old customers using the old java applet based webphone.
This new webphone has an easy to use API, however if you wish to keep your old code, you can do so with minimal changes as we created a compatibility layer for your convenience. Follow the next steps to upgrade to our new webphone:
1. The root folder of the new webphone is the folder, in which "webphone_api.js" and "softphone.html" files are located.
2. Copy the contents of the new webphone root folder, in the same folder where the old webphone's .html file is (merge "images" and "js" folders, if asked upon copy process).
3. In the <head> section of the .html file, where the old webphone is, replace line:
<script type="text/JavaScript" src="js/wp_common.js"></script>"
with the following lines:
<script type="text/JavaScript" src="webphone_api.js"></script>
<script type="text/JavaScript" src="oldapi_support.js"></script>
Note: Don't remove or add any webphone related Javascript file imports.
"jquery-1.8.3.min.js " file will be imported twice, but that is how it supposed to be, in order for the upgrade to work correctly.
For old webphone customers: please note that this new webphone is a separate product and purchase or upgrade cost might be required. The old java applet webphone have been renamed to “VoIP Applet” and we will continue to fully support it. More details can be found in the wiki.
Auto-provisioning or auto-configuration is a simple way to configure IP-phones for SIP servers used on local LAN.
The exact same behavior can be easily achieved by using the webphone with dynamic parameters.
First you should set the parameters common for all instances (all users) on your webserver in the webphone_api.js file.
Then you just have to set account related settings (per user settings) at runtime using one of the method specified in the Parameters chapter (by URL, via a server API by scurl_setparameters, or from javascript by the setparameter API).
The web sip phone can be easily localized for multiple languages.
The "language" parameter, is a 2 character language code string, for example: "en" for English and "hu" for Hungarian.
To add another language, just take the list of English strings from stringres.js, translate them to the desired language and add an underscore followed by the two character language code suffix, to every string entry like below:
Desired language: Italian
Language code will be: it
- set the language API parameter: language: 'it',
- after translating all strings from English to Italian, copy them back to stringres.js adding the "_it" suffix:
String resource example:
For english: my_page_title: 'Phone',
For italian: my_page_title_it: 'Telefono',
Contact support if you have any difficulties with this. We will send you the file to be translated and once you translate it, we will apply to your webphone build.
Webphone comes with a few prebuilt skins, which can be changed from Settings -> Theme.
The look and feel of the webphone skin can further be customized by altering any of the predefined themes found in: js\softphone\themes.js.
Open the themes.js file (it is located in webphone/js/softphone folder) with your favorite text editor.
In the "themelist" variable are stored the current webphone themes, you can edit for example the theme_1 after your needs. Please note that the theme_0 (default theme) can't be modified from this file.
From the variables names should be obvious they meaning (bg - means background), the colors are defined in RGB hex.
mainlayout.css: color to replace: #1d1d1d with urlparam: bgcolor
wphone_1.0.css: color to replace: #333 with urlparam: buttoncolor
wphone_1.0.css: color to replace: #373737 with urlparam: buttonhover
wphone_1.0.css: color to replace: #22aadd with urlparam: tabselectedcolor
mainlayout.css: color to replace: #31b6e7 with urlparam: fontctheme
mainlayout.css: color to replace: #ffffff with urlparam: fontcwhite
wphone_1.0.css: color to replace: sans-serif with urlparam: fontfamily
After you modify a variables value, you need to reload your webphone otherwise the modifications will not any effect.
You will also need to set the “colortheme” parameter to match your theme index.
You can create new themes easily by searching for existent dialer skins and after you find one that it is close to your needs just pick the preferred colors
using a software like Color Pic or you can search for a color matching tool to help you in building better color schemes.
The webphone can load its settings also from the webpage URL and perform various actions such as initiate a call. All the listed parameters can be used, prefixed with “wp_”.
Example to trigger a call with the softphone by html url parameters:
Example to trigger a call with the click to call by html url parameters:
Example trigger chat by html parameters
http://www.yourwebsite.com/webphonedir/softphone.html?wp_serveraddress=YOURSIPDOMAIN&wp_username=USERNAME&wp_password=PASSWORD&wp_sendchat=TEXT&wp_to=DESTINATION&wp_autoaction=2
Note: you should use clear password only if the account is locked on your server (can’t call costly outside numbers). Otherwise you should pass it encrypted or use MD5 instead.
See also click to call.
Just set your phone number in your email signature as a link (URL anchor) to the webphone click to call: http://www.yourwebsite.com/webphonedir/click2call_example.html?wp_serveraddress=YOURSIPDOMAIN&wp_username=USERNAME&wp_password=PASSWORD&wp_callto=YOURNUMBER
In this way the phone number in your email signature will become a clickable link which will trigger the webphone and will call your number automatically on SIP.
Instead of the click2call_example.html, you can also use the softhone.html (or your custom webphone html).
For account username/password you should just create a special extension on your SIP server which is not authenticated and allows unrestricted calls to local extensions only (not to outbound/paid).
More details about click to call can be found here.
Multi-line means the capability to handle more than one call at the same time (multiple channels).
By default you don't need to do anything to have multi-line functionality as this is managed automatically with each line on the first “free” line.
If you have multiple ongoing calls, then the active call will be the last one you make or pickup.
User interface:
Multi line functionality is enabled by default in the webphone.
Once the enduser initiate or receive a second call, the webphone will automatically switch to multi-line mode.
If you are using the softphone skin (the softphone.html) its user interface will display the separate calls in separate tabs, so the user can easily switch between the active calls.
Actually the followings user interface elements are related to to multi line:
· on the Call page, once you have a call, you can initiate more calls from Menu -> New call
· for every call session, a line button will appear at the top of the page so the users can change the active line from there
· the line buttons for managing call sessions, will also appear in case another incoming call arrives
· you can easily transfer the call from line A to line B
· you can easily interconnect the active lines (create conference calls)
Disable multi-line
You can disable multi-lien functionality with the following settings:
-set the “multilinegui” webphone parameter to 0
-set the "rejectonbusy" setting to "true"
Other related parameters are the "automute" and "autohold" settings.
JavaScript library/API
When the webphone is used as an SDK, the lines can be explicitly managed by calling the setline/getline API functions:
- webphone_api.setline(line); // Will set the current line. Just set it before other API calls and the next API calls will be applied for the selected line
- webphone_api.getline(); //Will return the current active line number. This should be the line which you have set previously except after incoming and outgoing calls (the webphone will automatically switch the active line to a new free line for these if the current active line is already occupied by a call)
For example if there are multiple calls in progress and you wish to hangup one of the calls, then just call the webphone_api.setline(X) before to call webphone_api.hangup().
The active line is also switched automatically on new outgoing or incoming calls (to the line where the new call is handled).
Channels
The following line numbers are defined:
o -2: all (some API calls can be applied to all lines. For example calling hangup(-2) will disconnect all current calls)
o -1: current line (means the currently selected line or otherwise the “best” line to be used for the respective API)
o 0: undefined
o 1: first channel
o 2: second channel
o …
o N: channel number X
Some behaviors will automatically change when you have multiple simultaneous calls. For example the conference API/button will automatically interconnect the existing parties or the transfer API/button will transfer the call from the current line to the other line.
Note: If you use the setline() with -2 and -1, it will be remembered only for a short time; after that the getline() will report the real active line or “best” line.
API usage example:
webphone_api.call(‘1111’); //make a call
webphone_api.call(‘2222’); //make second call
//setup conference call between all lines
webphone_api.setline(-2); //select all lines
webphone_api.conference();
//disconnect the second call
webphone_api.setline(‘2222’);
webphone_api.hold(true);
//put first call on hold
webphone_api.setline(‘1111’);
webphone_api.hold(true);
The best engine is selected by the webphone automatically based on circumstances (client device, OS, browser, network, server):
However the preferred engine can influenced on 3 levels:
-Choice presented to the user in some circumstances on startup (This is not always presented. The webphone will go with the best engine when there is a definitive winner, without asking the user)
-Engine settings in the user interface, so the enduser might change its own preferred engine
-Engine priority options in the configuration. You can set this in the “webphone_api.js” (enginepriority_xxx settings as discussed in this documentation Parameters section)
There should be very rare circumstances when the default engine selection algorithm should be changed. The web sip lib always tries to select the engine which will disturb the user the less (minimizing required user actions) and offers the best performance.
For example don't be inclined to disable Java for the sake of its age. Users will not be alerted to install Java by default. However if Java is already enabled in the user browser then why not to use it? Java can offer native like VoIP capabilities and there should be no reason to disable it.
We spent a considerable amount of work to always select the best possible engine in all circumstances. Don't change this unadvisedly, except if you have a good reason to use a particular engine in a controlled environment.
This is a question often asked by our customers about how to optimize the webphone library for best call quality. The answer is rather simple for this question:
The best settings are the default settings. The default settings are optimized and should be preferred in almost all use cases except if you have some uncommon needs. You should change the default settings only if you have a good reason to do so. See also the “best codec“ section.
The easiest way to specify parameters for the webphone is to just enter them in the webphone_api.js file (parameters variable at the top of the file).
However if you need to integrate the webphone with your server (for example with a CRM) you might have to set different parameters regarding the session (for example different user credentials based on the currently logged-in user). There are 3 ways to do this:
1. With the client side JavaScript using the webphone setparameter API (get the parameters from you webapp or via ajax requests)
2. Just generate the URL (iframe or link) dynamically from your server side scripts with the parameters set as required (wp_username, wp_password and other URL parameters).
3. Set the “scurl_setparameters” setting to point to your server side http api which will have to return the details once called by the webphone.
This will be called 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.
See the beginning of the parameters section for all other possibilities.
The webphone can generate detailed logs for debugging purposes.
For this just set the “loglevel” setting to 5 (or enable logs from the user interface if any; this is already set to 5 by default in the demo versions).
Once enabled, you can see the logs in the browser console or in the softphone skin help menu (if you are using this GUI). If the Java engine is being used, then the logs will appear also in the Java console. You can also use the API: getlogs() and the onLog(callback) functions.
When contacting Mizutech support with any issue, please always attach the detailed logs: just send the output of the browser console (or you can find the same from the softphone skin help menu if you are using the softphone.html).
On Firefox and Chrome you can access the logs with the Ctrl+Shift+J shortcut (or Cmd+Shift+J on a Mac). On Edge and Internet Explorer the shortcut key is F12.
WebRTC engine detailed logs
If the webphone is using the WebRTC engine then the browser console output will contain the most important logs.
If you are using the softphone skin, then better if you check the logs from the skin help menu because the number of lines are limited in the browser console.
If you have voice issues (no voce, one side voice, delays) then you should get a detailed log. With Chrome this can be done by launching it like:
"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --enable-logging --v=4 --vmodule=*libjingle/source/talk/*=4 --vmodule=*media/audio/*=4
Then you can find the logs at: C:\Users\USER\AppData\Local\Google\Chrome\User Data\chrome_debug.log
Java engine detailed logs
If the webphone is using the Java engine, then a log window will appear if the “loglevel” is set to “5” and the “canopenlogview” to “true”.
Grab the logs also from this window (Ctrl+A, Ctrl+C, Ctrl+V) or from the Java console.
NS engine detailed logs
If the webphone library is using the NS engine on Windows, then some more detailed logs can be obtained from
C:\Program Files (x86)\WebPhone_Service\WebPhone_Servicelog.dat
and C:\Program Files (x86)\WebPhone_Service\content\native\webphonelog.dat.
(C:\Program Files (x86)\WebPhone_Service is the default data directory which might be different on your PC.
It might be located in the C:\Users\USER\AppData\Roaming\WebPhone_Service directory if the account doesn’t have write access to Program Files).
If there is no *log.dat file, just send the “wphoneout.dat” file or all the *.dat files if you are not sure (from both the app directory and from /content/native folder).
ERROR and WARNING messages in the log
If you set the loglevel higher than 1 than you will receive messages that are useful only for debug.
Most of ERROR and WARNING message cannot be considered as faults in this case.
Some of them will appear also under normal circumstances and you should not take special attention for these messages.
If there are any issue affecting the normal usage, please send the detailed logs to Mizutech support ([email protected]) in a text file attachment.
Why I see RTP warning in my server log
The
webphone will send a few (maximum 10) short UDP packets (\r\n) to open the
media path (also the NAT if any).
For this reason you might see the following or similar Asterisk log entries:
“WARNING[8860]:
res_rtp_asterisk.c:2019 ast_rtp_read: RTP Read too short” or “Unknown RTP
Version 1”.
These packets are simply dropped by Asterisk which is the expected behavior.
This is not a webphone or Asterisk error and will not have any negative impact
for the calls. You can safely skip this.
You might turn this off by the “natopenpackets” parameter (set to 0). You might also set the “keepaliveival” to 0 and modify the “keepaliveival” (all these might have an impact on the webphone NAT traversal capability).
How to find which engine was tried?
To find all engine related log, like which engines are supported, selected/recommended engine, just search for "engine".
Also, before every engine start, all the engine priorities are logged, search for: "enginepriority"
How to find which engine is was finally selected?
To find out which engine was started, search for: "start engine:"
If WebRTC engine is selected, how to find the websocket URL, sip server and ice settings.
Search for: "Webrtc connection details:". There you will find all the above details.
When sending logs to Mizutech support, please attach them as text files (don’t insert in email body).
Homepage: https://www.mizu-voip.com/Software/WebPhone.aspx
Download: https://www.mizu-voip.com/Portals/0/Files/webphone.zip
Pricing: https://www.mizu-voip.com/Support/Webphonepricing.aspx
Contact [email protected]
Copyright © 2008-2017 Mizutech SRL