About

The Mizu WebPhone is a SIP client application implemented as a platform independent java applet and will run in any java enabled browser. Since it is based on the open standard Session Initiation Protocol, it can inter-operate with any other SIP-based networks allowing people to make true VoIP calls directly from webpage.


Quick start

It will cost you less than 10 minutes to deploy the webphone on your website:

1. Check out the webphone presentation on our website if you haven’t done it before.

2. Check the Example.html source code (for the basic functionality you only need to rewrite the “serveraddress” applet parameter to your preferred sip server address)

3. Create a similar html on your website (copy-paste the applet tag from the Example.html anywhere to your webpage and copy the webphone.jar near the html files)

4. For more advanced usage check the other examples and read trough this documentation.


Features

Ø SIP and RTP stack (compatible with any standard VoIP server or device like Cisco, Asterix, softphones, ATA and others)

Ø Standard 100% java applet (no software installation or native components required; runs directly from all browsers under all OS)

Ø VoIP calls with auto QoS

Ø Transport protocols: UDP, encrypted UDP, TCP, TLS, HTTP tunnel*

Ø NAT/Firewall support: stable SIP and RTP ports ,rport support, light STUN protocol and auto configuration

Ø Media protocols: IM (chat), SMS and presence capability

Ø RFC’s: 2543, 3261, 2976, 3892, 2778, 2779, 3428, 3265, 3515, 3311, 3911, 3581, 3842, 1889, 2327, 3550, 3960, 4028, 3824, 3966, 2663, 3022

Ø Supported methods: INVITE ,reINVITE, ACK,PRACK, BYE, CANCEL, UPDATE, MESSAGE, INFO, OPTIONS, SUBSCRIBE, NOTIFY, REFER

Ø Codec: PCMU, PCMA, G.729, GSM,iLBC,SPEEX

Ø Wideband and ultra-wideband codec’s (skype quality)

Ø Stereo output (will convert mono sources to stereo) and PLC (packet loss concealment)

Ø DTMF (INFO method in signaling or RFC2833)

Ø Redial, call hold, mute and transfer (attended and unattended)

Ø Unlimited lines

Ø Balance display, Call timer

Ø Signaling and media tunneling and encryption*

Ø VPN tunneling

Ø Click to call

Ø Server side integration using PHP, .NET, J2EE , etc

Ø JavaScript API

Ø Customizable user interface, skins and languages

Ø Custom features

*http tunneling and encryption works only when used with Mizu VoIP server or tunneling servers


Usage examples

Ø The most convenient dialer that can be offered for VoIP endusers

Ø Buy/sell portals

Ø Social networking websites

Ø Click to call functionality on any webpage

Ø VoIP conferencing in online games

Ø 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

Ø 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

Ø Integration with other web or desktop based software to add VoIP capabilities


Benefits

Ø Compatible with all browsers (IE, Firefox, Safari, Opera, Chrome, etc) and all OS (Windows, Linux, MAC, etc) with Java SE support

Ø Full compatibility with your VoIP server including Class 5 features

Ø Users don’t have to download anything to be able to initiate true VoIP calls

Ø Bypass corporate firewalls, proxies and all VoIP filtering (when encryption and/or HTTP tunneling is turned on)

Ø No need for third party media server. Full SIP functionality is embedded so it can connect directly to your server like any other hardware IP phone or softphone. Not ActiveX based.

Ø Easy to use and easy to deploy (copy-paste HTML code)

Ø Easy integration with your existing infrastructure

Ø Easy integration with your existing website design

Ø Proprietary SIP/RTP stack guarantees our strong long term and continuous support

Ø 100% java code packaged in one single jar file


Requirements

Ø Java SE capable browser (Java S2SE 4+. This can be installed automatically if not found): supported by 96% of the browsers after world-wide statistics

Ø Java Script capable browser when the API is used: supported by 98% of the browsers after world-wide statistics

Ø Microphone and speakers (preferably a headset)

Ø Minimum 400 MHz P3 or similar processor for the advanced codec’s (e.g. G.729 or speex wideband)


User interface

The webphone is shipped with a simple user interface presenting the most commonly used functions.

However you can easily customize the user interface by applet parameters (compact, width, height, color parameters, enable/disable functions etc).

If you need total control on your design then there is a Java Script API which you can use to easily customize the user interface and create your own design. This means that any web developer can easily create any user interface by HTML, DHTML, AJAX, Flash, etc and run the webphone in the background or in compact mode, controlling it by javascript function calls. See the JavaScript API section for more details.

Additionally there is a possibility to create your own Java GUI. If you have Java knowledge, then you can easily create a GUI, send us the java source code and we will reply with your customized webphone. We prefer Netbeans or JBuilder project files with absolute (XY) layout. Your code must compile without errors and needs to be an applet. For this service we may require extra charge.


Deployment

The whole application is built into one file making its deployment fairly easy. The file size is like a small image on your webpage, so it can be downloaded quickly by browsers. To add it to your webpage, you just have to put the webphone.jar on your web server and copy-paste a short code in your html. Any web developer can handle this task in a few minutes.

By default the applet file is named “webphone.jar”. Copy this file in your webpage directory (Usually near the html file in which you would like to be displayed. Otherwise you must enter the correct path).

Then copy paste the applet tag into your html (or compose it dynamically from any server side script like PHP or .NET)

The applet tag is defined as follow (with some basic parameters):

<applet

archive = "webphone.jar"

codebase = "."

code = "webphone.webphone.class"

name = "webphone"

width = "APPLET_SIZE_WIDTH"

height = "APPLET_SIZE_HEIGHT"

hspace = "0"

vspace = "0"

align = "middle"

>

<param name = "bgcolor" value = "APPLET_COLOR">

<param name = "compact" value = "COMPACT_BOOL">

<param name = "register" value = "REGISTER_BOOL">

<param name = "call" value = "CALL_BOOL">

<param name = "serveraddress" value = "SERVER_ADDRESS">

<param name = "username" value = "CALLER_USERNAME">

<param name = "password" value = "CALLER_PASWORD">

<param name = "callto" value = " CALLED_NUMBER">

<b>Display error here or offer java runtime download or alternative dial method (download link to your desktop softphone) b>

</applet>

(uppercase words must be rewritten to meaningful values)

For a working example please check the Example.htm. Enter your VoIP server address (ip or domain) for the serveraddress parameter, then you can open the Example.htm in your browser.

You might also use the “object” tag instead of the “applet” tag in your website.

The most flexible deployment method is by using the deployment toolkit. This can automatically install the JRE if not already installed with the browser. For a simple example please check the “Toolkit.html” example.

<script src="http://java.com/js/deployJava.js"></script>
<script>
var attributes = {codebase:'http://yourdomain.com/path',
code:’ webphone.webphone.class',
archive: webphone.jar',
width:300, height:330} ;
var parameters = {serveraddress: 'yoursipdomain.com', username: 'USERNAME'} ;
deployJava.runApplet(attributes, parameters, 1.4);
</script>

A more modern and flexible deployment method is by using JNLP. For example this allows you to customize also the “applet loading…” screen.
Please check the jnlp.htm for a working example. More details: http://java.sun.com/docs/books/tutorial/deployment/applet/deployingApplet.html

· GUI

You can set any color for the GUI and enable/disable functions by applet parameters. The java applet can even be running in the background, so this will not disturb your existing web design .For more details please read trough the “Appearance Parameters” section in this document. Alternatively you can use the javascript api and create your own GUI. This is documented in the “JavaScript API” section.

· Online/Offline/Busy and other status buttons

The status of the users can be loaded from a database. Based on the user presence you can display the different buttons with your design. This can be easily done with a little server side work (in PHP, .NET or any other language)

· When Java is not installed

Based on online statistics (http://www.thecounter.com/stats/) 94% of the browsers have support for java.

Using the toolkit or the JNLP deployment methods the Java engine is automatically installed on the client device.

You can always present alternative methods for users who don't have Java installed or enabled in their browsers. Most of the softphones will recognize sip uri links placed on your webpage (for example sip://callednumber@sipserver.com) and will start the call automatically. Alternatively you can redirect your users to download the java runtime or offer them a softphone download link in case if they don’t have java enabled. You can also use the JNLP deployment method which can also download the Java runtime automatically if needed.

· Bypass security restriction

To disable the java warning when the applet first loads on user’s device, you can add a valid digital certificate for the applet. This can be purchased by different vendors (trusted certificate authorities). You can check VeriSign for example. The price varies from 20 to 800 USD. Contact us if you have any technical problems (We can sign up your applet if you have purchased such certificate). For more details read the FAQ.

Applet parameters:
 The most easiest way to pass applet parameters is by using the applet tag and set the parameters like:
<param name = "parameter_name" value = "parameter_value">
Alternatively you can use the Java Script API_SetParameter function.
All parameters are passed as strings and will be converted to the proper type internally by the webphone.
Parameters can be also encrypted. See the FAQ for the details.

For a basic usage you will have to set only your VoIP server ip or domain name (“serveraddress” applet parameter)
The rest of the parameters are optional and should be changed only if you have a good reason for it.


Main Parameters

The parameters can be used to control the most important settings and applet behavior like server domain, SIP authentication parameters, called party number and whether a call have to be started immediately as the applet starts or you let the user to enter these parameters manually.

serveraddress

(string)

The domain name or IP address of your SIP server. By default it uses the standard SIP port (5060). If you need to connect to other port, you can append the port after the address separated by colon. Example: mydomain.com:5062

Default value is empty.

username

(string)

this is the A number (username). The instance will authenticate with this username on your server.

When compact is true, then this parameter must be filled properly. Otherwise it can be empty or omitted (the user will have to enter it)

If you need a different name for SIP user name and Auth name then you might have to also use the “sipusername” applet parameter.

Default value is empty.

password

(string)

SIP authentication password. When compact is true, then this parameter (and also the username) must be filled properly. Otherwise it can be empty or omitted (the user will have to enter its password).

Default value is empty.

register

(bool)

Set to true if you would like the softphone to register automatically when started (server domain, username and password must be passed by parameters). Default value is false.

call

(bool)

If set to true then the applet immediately starts the call with the given parameters. The serveraddress, username, password, callto must be set by parameter.

Default value is false.

Usually when this parameter is true, then the “compact” is also set true.

Usually when this parameter is false, then the “compact” is also set false.

callto

(string)

can be any phone number or username that can be accepted by your server. When “call” or “compact” is true, then this parameter should be filled properly. Otherwise it can be empty or omitted (the user will have to enter it)

Default value is empty.


Appearance Parameters

The parameters can be used to control how the applet user interface (if any) will look like.
For more customization you can write your own user interface and use the java script api to control the webphone.

applet_size_width, applet_size_height

(int)

the size of the space occupied by the applet can vary depending on the other parameters.

-if the compact parameter is set to false, than you should set the applet_size_width to 300 and the applet_size_height to 330.

-If the compact parameter is set to true, than you should set the applet_size_width to 240 and the applet_size_height to 50.

You can run this applet in hidden mode, when all parameters are passed from server side scripts. In this way you can set the applet_size_width and applet_size_height to 1.

The applet size can be set also from html.

compact

(bool)

False: the applet will be shown in its full size with username, password input box and dial pad

True: the applet will have only a Hangup/Call button and a call status indicator. In this mode the username, password and callto parameters are already set from parameters, so when the applet is launched it immediately starts dialing the requested number.

Default value is false.

Usually when this parameter is true, than the “call” is also set true.

Usually when this parameter is false, than the “call” is also set false.

multilinegui

(bool)

Set to false to hide line buttons. (The phone will still be able to handle multiple calls automatically)

You can restrict the available virtual lines with the “maxlines” parameter.

Default is false.

lookandfeel

(string)

Controls the basic design settings. The following values are defined:

Ø mizu (on request)

Ø metal

Ø windows

Ø mac

Ø motif

Ø platform

Ø system

Default value is null (system specific design is loaded)

colors

(int)

With these parameters you can customize the colors on the applet.

Default value is empty.

The following applet parameters are defined:

Ø color_background

Ø color_foreground

Ø color_label_background

Ø color_label_foreground

Ø color_edit_background

Ø color_edit_foreground

Ø color_buton_background

Ø color_buton_foreground

Ø color_buton_dial_background

Ø color_buton_dial_foreground

Ø color_other_background

Ø color_other_foreground

There are 3 ways to specify the color parameter:

Ø integer number: This number represents an opaque sRGB color with the specified combined RGB value consisting of the red component in bits 16-23, the green component in bits 8-15, and the blue component in bits 0-7

Ø hex number prefixed with #: representation of the color as a 24-bit integer (htmlcolor)

Ø the name of the color: the following values are defined: black,blue,cyan,darkgray,gray,gren,lightgray,magneta,orange,pink,red, white and yellow

language

(string)

Built-in translations. The following translations are included:

-en: english (default)

-ru: russian

-hu: hungarian

-ro: romanian

-de: deutsch

-it: Italian

-es: spanish

(other languages can be added on your request)

hasconnect

(bool)
Set to false if you don’t need the connect button

hascall

(int)
0: never

1: hangup only

2: always

hashold

(bool)
Set to false if you don’t need the hold button

hasmute

(bool)
Set to false if you don’t need the mute button

hasredial

(bool)
Set to false if you don’t need the redial button

hasaudio

(bool)
Set to false if you don’t need the audio button

hasincomingcall

(bool)
Set to false if you don’t need the popup for the incoming calls

haschat

(int)

0=no

1=API only

2=SMS

3=IM all (default)

hasvolume

(int)

0=no volume controls

1=dynamic (default)

2=vertical

3=horizontal (useful if you disable the multiple lines)
Set to false if you don’t need the volume controls button

volumeicons

(int)

0=no

1=text (if hasvolume is set to 3)

2=icons (if hasvolume is set to 2)

displaysipusername

(bool)
Set to true to display the “Extension” edit box.

Default is false.

When sipusername is set (by applet parameter, user input or javascript api) then it will be used as the sip username and the username field will be used only for authentification. Otherwise the “username” field will be used for both.

displaydisplayname

(bool)
Set to true to display the “display name” input box.

Default is false.


Other Parameters

The parameters are more rarely used or should be used only if you have at least a minimal technical knowledge (VoIP and/or JavaScript)

userport

(int)

Check rport in SIP signaling. 0=don’t ask, 1=use only for symmetric NAT, 2=always, 3=request even on public IP

Change to 0 or 2 only if you have NAT issues (depending on your server type and settings)

(Usually userport and usestun should have the same value set)

Default is 1

usestun

(int)

Stun request on startup. 0=no, 1=use only for symmetric NAT, 2=always, 3=use even on public IP

Change to 0 or 2 only if you have NAT issues (depending on your server type and settings)

(Usually usestun and userport should have the same value set)

Default is 1

changesptoring

(int)

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 start to send in-band ringing (or some announcement)

The following values are defined:

0: do nothing,

1: change status to ring

2: start media receive and playback (and media recording if the “sendearlymedia” applet parameter is set to true)

3: change status to ringing and start media receive and playback (and media recording if the “sendearlymedia” applet parameter is set to true)

Default value is 2.

*Note: on ringing status the webphone is able to generate local ringtone. However 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)

natopenpackets

(int)

Change this option only if you have RTP setup issues with your server(s).

UDP packets to send to open the NAT device and initiate the RTP. Some servers will require at least 5 packets before starting to send the media after the 183 “session in progress” response. In this case set this value to 10 (In this way the server will receive at least 5 packets even on high packet loss networks)

Default is 1

*Note: instead of sending more “fake” packets, you can set the “sendearlymedia” to true to begin the rtp stream immediately.

keepaliveival

(int)

NAT keep-alive packet send interval.

Set to 0 to disable.

Default value is 20000.

sendearlymedia

(bool)

Start to send media when session progress is received

Default is false.

*Note: For the early media to work, the webphone has to open the NAT when SDP is received. This can be done by sending a few fake rtp packets or by starting to send the media immediately when session in progress is received. The fist method consume less bandwidth, but it is not supported by some servers.

setfinalcodec

(int)

Some server cannot handle the final codec offer in the ACK message correctly.

In this case you will have to set this setting to 0, otherwise you will have one way audio.

0=never

1=auto guess (not send in case of OpenSIPS servers)

2=when multiple codecs are received

3=always reply with the final codec in the ACK message

Default value is 1.

proxyaddress

(string)

Outbound proxy address (Examples: mydomain.com, 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.

usehttpproxy

(int)

Used only for HTTP tunneling with Mizu VoIP servers.

0: no

1: same as sip proxy (proxyaddress)

2: system default

3: manual (must be set by the httpproxyurl applet parameter –deprecated after version 3.5)

4: auto

Default value is 4.

httpproxyurl -deprecated

(string)

Used only for HTTP tunneling when usehttpproxy is set to 3 or 4.

Set your http proxy address here. Example: 192.168.1.1:8080

Default value is empty.

This feature is removed after version 3.5 because it is not compatible with older JVM and using the browser capabilities offers better proxy handling.

httpserveraddress

(string)

Useful when the transport parameter is set to 4 (auto) to specify the http tunneling gateway address.

Default value is null (address loaded from the “serveraddress” applet parameter)

transport

(int)

Transport protocol.

0=UDP

1=TCP

2=TLS (beta)

3=HTTP tunneling (both signaling and media. Supported only by mizu server or mizu tunnel)

4=Auto (automatic failowering from UDP to HTTP if needed)

Default is 0.

dtmfmode

(int)

DTMF send method

0=disabled

1=sip INFO method

2=RFC2833 in the rtp

3=both INFO and RFC2833

Default is 1.

transfertype

(int)

0=disabled

1=transfer immediately when the Transf button is pressed and the number entered (unattended transfer)

2=transfer the call only when the second party is disconnected (attended transfer)

3=transfer the call when the webphone 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)

Default is 1.

discontransfer

(int)

Specify if line should disconnect after transfer
0=no (default)

1=on refer sent

2=on refer received

3=on both

4=all

checksrvrecords

(bool)

Set to true if SRV domain record lookups are required. Make sure this module is included with the webphone (ask Mizutech support if needed)

Default is false (disabled)

playring

(int)

Generate ringtone for incoming and outgoing calls.

0=no (you can generate ringtone also by using the JavaScript api to playback a sound file when you receive ringing notifications)

1=play ringtone for incoming calls

2= play ringtone for incoming and outgoing calls. (ringtone for outgoing calls can be generated also by your VoIP sever. When remote ringtone is received, the webphone will stop the local ringtone playback immediately and starts to play the received ringtone or announcement)

Default is 2.

volumein

(int)

Default microphone volume in percent from 0 to 100. 0 means muted. 100 means maximum volume.

Default is 50%.

volumeout

(int)

Default speaker volume in percent from 0 to 100. 0 means muted. 100 means maximum volume.

Default is 50%.

stereomode

(bool)

Set to true for 2 audio channel or false for 1 (mono).

When stereo is set, the webphone will convert also mono sources to stereo output.

Default is false.

plc

(bool)

Enable/disable packet loss concealment

Default is false (disabled).

rtcp

(bool)

Enable/disable rtcp.(RFC 3550)

usegsm

(int)

GSM codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1.

useilbc

(int)

iLBC codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 0.

usespeex

(int)

Narrowband speex codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1 (disabled)

usespeexwb

(int)

Wideband speex codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 2

usespeexuwb

(int)

Ultra wideband speex codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 2

useg729

(int)

G.729 codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1

*Enable only if you have g.729 licenses or licenses are not required in your case (consult your lawyer if you are not sure)

usepcma

(int)

G711alaw codec. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 2

usepcmu

(int)

G711ulaw codec. 0=never, 1=don’t offer, 2=yes with low priority, 3=yes with high priority

Default is 2

codecframecount

(int)

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.

automute

(int)

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

autohold

(int)

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

ackforauthrequest

(int)

If to send ACK for authentication requests (401,407).
0=no

1=yes (default)

Should be changed only if you have compatibility issues with the server used.

favorizecontactaddr

(int)

You may change it if you have compatibility issues with stateless proxies
0=never

1=no

2= conform RFC (default)

3= yes

4=always

prack

(bool)

Enable 100rel (PRACK)

Set to false if you have incompatibility issues.

Default is true.

techprefix

(string)

Add any prefix for the called numbers.

Default is empty.

rejectonbusy

(boolean)

Set to true to reject all incoming call if there is already a call in progress.

Default value is false.

autoaccept

(boolean)

Set to true to automatically accept all incoming calls.

Default value is false.

calltimeout

(int)

Maximum speech time allowed in millisecond.

Default is 10800000 (3 hour)

timer

(int)

You can slow down or speed up the SIP protocol timers with this setting. You may set it to 15 if you have a slow server or slow network.

Default value is 10.

timer2

(int)

Same as “timer” but it affects idle, connect and ring timeout and maximum call durations.
Default value is 10.

mediatimeout

(int)

RTP timeout in seconds to protect again dead sessions.

Calls will be disconnected if no media packet is sent and received for this interval.
Default value is 300 (5 minute)

sendmac

(boolean)

Will send the client MAC address with all signaling message in the X-MAC header parameter.

Default value is false.

waitforclose

(int)

Wait for the SIP engine to proper disconnect in miliseconds. By default it is set to 100. You might increase this value to give more time for the webphone on slow PC’s to send the proper unregistrer message when the applet is closed.

md5

(string)

Instead of using the password parameter you can pass an MD5 checksum: MD5(username:realm:password)

Default is empty.

realm

(string)

Can be set together with the md5 applet parameter. You should be able to obtain it from your VoIP server (usually the server domain name)

Default is empty.

encrypted

(bool)

Specify if the transport will be encrypted (both media and the signaling)

Compatibile only with Mizu VoIP servers.

Automatically turned on when using http tunneling.

Default is false.

authtype

(int)

Some server doesn’t allow “web” or “proxy” authentication.

0=normal

1=only proxy auth

2=only simple auth

sipusername

(string)

Specify default SIP auth username. Otherwise the “username” parameter will be used for authentication or the username specified by the user.

Default is empty.

displayname

(string)

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

Default is empty (username will be displayed for the peers)

pwdencrypted

(int)

Specify if you will supply encrypted passwords via applet parameters or via the javascript api
0=no (default)

1=xor

2=des+base64

3=xor+base64 (this is the preferred method; easiest but still secure enough)

4= base64

This method is deprecated from version 3.4. All parameters can be passed encrypted now by just prefixing them with the “encrypted__X__” string where X means the id of the encryption method used.

autocfgsave

(int)

Sometime is useful to not allow configuration storage on the user device (username,password,etc)

0=disable config storage

1=save only

2=load only

3=save and load (default)

signalingport

(int)

Specify local SIP signaling port to use

Default is 0 (random)

rtpport

(int)

Specify local RTP port base

Default is 0 (random)

registerival

(int)

Specify registration interval in msec.

Default is 90000 (90 sec)

jittersize

(int)

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

loglevel

(int)

Tracing level. Values from 0 to 6.

If you set it to more then 3, then a log window will appear and also will write the logs to a file (if file write permissions are enabled on the client side).

With level 0, the applet will not even display important even notifications for the user. Don’t use this level if possible.

Loglevel 4 means a full log including SIP signaling. Loglevel 5 or 6 should be avoided (this can slow down the applet)

Text logs are sent to the following outputs:

-status display (only level 1 –these are the most important events that needs to be displayed also for the user)

-log window if loglevel is higher than 3

-file if loglevel is higher than 3 (webphonelog.dat in the java user home directory which depends on the OS/java/browser used)

-java console (if the logtoconsole applet parameter is set to true)

Default is 1.

logtoconsole

(bool)

Whether to send tracing to the java console.

Default is false.

capabilityrequest

(bool)

If set to true then will send a capability request (OPTIONS) message to the SIP server on startup. The serveraddress applet parameter must be set correctly for this to work. This method is useful to release the security restrictions when using the applet with the java script API and also to open the NAT devices.

Default value is false.

natkeepalive

(bool)

If set to true then will send a short message (\r\n) to the SIP server on startup. The serveraddress applet parameter must be set correctly for this to work. This method is useful to release the security restrictions when using the applet with the java script API and also to open the NAT devices.

Default value is false.

recaudiobuffers

(int)

Number of buffers used for audio recording.

Default is 7.

recaudiomode

(int)

Audio recording mode. 1 means event based; 2 means device poll.

Default is 2.

useencryption

(bool)
Set to true for encrypted communication (both media and signaling)

Works only with mizu servers.

maxlines

(int)

Maximum port number from 1 to 4. When set to 1, multiline functionality will be disabled.

Default value is 4.

webphonetojs

(String)
Java script function to be called for the notifications.

Default value is “webphonetojs”

jsscriptevent

(int)
If you have a java script function called webphonetojs, you can get notifications about webphone status, line status, events and cdr record.

0=no notifications,1=status and cdr,2=events,3= all logs (depending on loglevel)
Default is 1.

jsfunctionpath

(string)
If your webphonetojs is embedded in other html elements, then you can give the path here. Example: document,externform,innerform2.

By default it is an empty string. This means that the webphonetojs must be placed on the top level (after <body> for example)


JavaScript API

The webphone has an easy to use API and can be easily controlled by external javascript function calls.

You can completely hide the webphone (or run it in compact mode) and present your custom design created with html, css, flash or with any other tool.

The syntax is very simple:

document.applets[0].functionname();

Example:

<SCRIPT LANGUAGE="javascript">

function webphonetojs(message)

{

//this is an optional function if you would like to be notified about webphone events

//this function will be called by the applet

//you will have to parse the message and act accordingly

alert(message);

}

function do_something()

{

document.applets[0].functionname();

}

</SCRIPT>

<input type=button value='applet action' onClick='do_something()'>

Or you might use the following format:
document.getElementById('webphone').getSubApplet().method(params);

document.getElementById('webphone').method(params);

For a working example please check the ”Toolkit_with_JS.htm” that you should find in the demo package.

Important : For the Java Script API to work correctly it is important to let the webphone to send the fist message to the server before you begin controlling it via the API. This can be done by using the AI_ServerInit function or one of the following applet parameters: register, call, capabilityrequest, natkeepalive. (If you already have the username/password information on startup, then you can set the “register” applet parameter to true and let the applet to register automatically. Otherwise the , capabilityrequest or natkeepalive applet parameters should be used. This is a workaround for Java security restrictions which will restrict the applet as it would be unsigned when it is controlled externally from JavaScript.

There are more than 100 public functions in the webphone, but you usually need only the functions prefixed with API_ and documented below:

Public Functions

Most of the functions return a boolean value. True when the call has been executed successfully, otherwise false.

Some of the functions are executed asynchronously. This means that it can return a true value immediately and fail later. For example for API_Call the return value means only that the call was initiated successfully. At this point we don’t know if the call will be successful (connected) or not. You can get the call status by parsing the messages received by the function named “webphonetojs” or you can periodically poll the webphone status with the API_GetStatus function.

The line parameter can mean the channel used. The following values are defined:

Ø -2: all channels

Ø -1: the current channel set previously by API_SetLine or by other functions. Usually this will mean the first channel (1)

Ø 0 : undefined

Ø 1: first channel

Ø 2 : second channel

Ø Etc (you can control the max number of the channels with the maxlines applet parameter)

Most commonly you will have to pass always -1 as the channel number. You will have to use other values only if you will present a GUI were the user can select different lines. Otherwise the webphone can do this automatically allocating new channels when needed.

Function string parameters can be passed in encrypted format. (Read the FAQ for more details regarding the encrypted parameters)

boolean API_ServerInit(String address)

Call this function before to start any communication with this IP. This is required to release the Java security restrictions. Wait 1-2 second before calling the next function like API_Register or API_Call.

boolean API_SetParameter(String param, String value)

Most of the applet parameters can be set with this function except applet gui parameters (like the colors). Some parameters can take effect only when the applet is reinitialized.

This function should be used only in special cases. You should be able to control the applet without to use this function

boolean API_SetCredentials(String server, String username, String password, String authname, String displayname)

Will set the server address (ip:port or domain:port) the SIP username and the password. These values can also be preset by applet parameters. Parameters with empty strings will be omitted. For example if you would like to change only the username and the password, you can write API_SetCredentials(“”,”newusername”, “newpassord”)

If authname is empty, then the username will be used for authentications. The displayname is usually empty (no special displayname will be presented for peers). If other parameters are empty, then they can be specified by user input (If the applet has a visible user interface).

boolean API_SetCredentialsMD5(String server, String username, String md5, String realm)

Instead of passing the password directly you can use MD5 checksum.

In this case the md5 parameter must be the md5 checksum for username:realm:password

The realm parameter is optional but it is recommended for easy error detection. If present and the server realm don’t match with this one, an error message will be displayed by the webphone.

boolean API_Register(String server, String username, String password, String authname, String displayname)

Will connect to the SIP server. This can be also done automatically by applet parameter (“register”). Need to be called only once (subsequent reregistrations are done automatically. When called subsequently, than the old registrar endpoint is deleted, a new one will be created with a new call-id and the webphone will reregister). Parameters can be empty strings if you already supplied them by applet parameters or by the API_SetCredentials call.

If you already passed the server, username and password (or md5) parameters with the API_SetCredentials functions, then you can call this function with empty parameters: API_Register(“”,””,””,””,””);

boolean API_CapabilityRequest(String server, String username)

Will send a OPTION request to the server. Usually you should not use this function.

The server parameter can be empty if you already set it with other API calls or by applet parameter.

The username parameter can be empty (in this case the “From” address will be set to “unknown”)

boolean API_SetLine(int line)

Will set the current channel. (Use only if you present line selection for the users. Otherwise you don’t have to take care about the lines)

boolean API_Call(int line, String number)

Initiate call to a number or sip username.

boolean API_Hangup(int line)

Disconnect current call(s). If you set -2 for the line parameter, then all calls will be disconnected (in case if there are multiple calls in progress)

boolean API_Accept(int line)

Connect incoming call.

boolean API_Reject(int line)

Disconnect incoming call.

boolean API_Transfer(int line, String number)

Transfer current call to number. (Will use the REFER method after SIP standards)

boolean API_TransferDialog()

Instead of calling the API_Transfer function and pass a number, with this function you can let the webphone to ask the C number from the user.

boolean API_Mute(int line, boolean mute)

Mute current call.

boolean API_MuteEx(int line, boolean mute, int what)

Same as API_Mute with an additional “what” parameter with the following meanings:

Ø 0: mute in and out (same effect as API_Mute)

Ø 1: mute in (microphone)

Ø 2: mute out (speakers)

boolean API_Hold(int line, boolean hold)

Hold current call. This will issue an UPDATE or a reINVITE.

boolean API_Dtmf(int line, String dtmf)

Send DTMF message by SIP INFO or RFC2833 method (depending on the “dtmfmode” applet parameter). Please note that the dtmf parameter is a string. This means that multiple dtmf characters can be passed at once and the webphone will streamline them properly. Use the space char to insert delays between the digits.
 Example: API_Dtmf(-2,” 12 345 #”);

boolean API_SendChat(int line, String number, String message)

Send a chat message. (SIP MESSAGE method after RFC 3428)

Number can be a phone number or SIP username/extension number.

boolean API_Chat(String number)

Instead of calling the API_SendChat function and pass a message, with this function you can let the webphone to open its chat form.

Will open the chat form (the “number” parameter can be empty)

boolean API_PlaySound(int start, String file, int looping)

Play any sound file. (At least wave files are supported)

The file must be found near the webphone.jar.

· Start: 1 for start or 0 to stop the playback

· File: file name

· Looping: 1 to repeat, 0 to play once

boolean API_AudioDevice()

Open audio device selector.

boolean API_SetVolumeIn(int val)

Set microphone volume (0-100%)

boolean API_SetVolumeOut(int val)

Set speaker volume (0-100%)

boolean API_ShowLog()

Show a new windows with logs.

boolean API_Unregister()

Will stop all endpoints (unregister and hangup if necessary)

boolean API_Exit()

Will stop all endpoints and terminates the currently running Java Virtual Machine. This function call is optional when you unload the applet or wish to issue a forced termination.

String API_GetVersion()

Return the program version number.

string API_GetStatus(int line)

Returns line status or global status if you pass -2 as line parameter. The possible returned texts are the same like for notifications (listed below)

Example call-flow:

API_ServerInit(“11.12.13.14”); //remove java security restrictions

API_Register(“11.12.13.14”, “username”, “xxxx”); //connect to the server

API_Call(-1, “+363012345678”); //make a new call

//wait for connect message by checking the message received on the webphonetojs function

//notify the user when the call is ringing or connected

API_Mute(-2,true); //called when the user press a button

API_Mute(-2,false); //reenable audio when the user press a button

API_Hangup(-2); //disconnect all calls

Notifications

To receive notifications and events from the webphone you have to create a java script function called webphonetojs that takes one string parameter. The webphonetojs function must be placed in the same html page and same DOM level. If you place it elsewhere, then you must use the jsfunctionpath applet parameter to specify.

The webphone will call this functions when something happens –according to the “jsscripevent” applet parameter (status change, error message, call finished, etc) passing the messages as the function parameter. (If your webphonetojs function is embedded in other html elements, then you can give the path by using the jsfunctionpath applet parameter)

From the java script code you usually will have to parse the received string. The parameters are separated by comma ‘,’. First you have to check the first parameter (until the first comma) to determine the event type. Then you have to check for the other parameters according to the specification below.

The following messages are defined:

STATUS,line,statustext,peername,localname,endpointtype

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 webphone status and once for line status.

For example you can receive the following two messages consecutively:

STATUS,1,Connected,peername,localname,endpointtype

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

Ready

Register…

Registering…

Register Failed

Registered

Accept

Starting Call

Call

Call Initiated

Calling…

Ringing…

Incoming…

In Call (xxx sec)

Hangup

Call Finished

Chat

The following statustext values are defined for individual lines (line set to a positive value representing the channel number):

Unknown

Init

Ready

Outband

Register

Subscribe

Chat

Setup

InProgress

Routed

Ringing

InCall

Speaking

Midcall

Finishing

Finished

Deletable

Error

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.

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.

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

The following status means an outgoing call in progress to 2222 on the second line:

STATUS,2,Speaking,2222,1111,1

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

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)

CHAT,line,peername,text

This notification is received for incoming chat messages.

Line: used phone line

Peername: username of the sender

Text: the chat message body

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

After each call, you will receive a CDR (call detail record) with the following parameters:

Line: used phone line

Peername: other party username, phone number or SIP URI

Caller: the caller party name (our username in case when we are initiated the call, otherwise the remote username, 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=webphone, 2=peer, 3=undefined

EVENT,TYPE,txt

Txt can be any important message or error message text. The TYPE parameter is usually “EVENT”, “WARNING” or “ERROR”. This is followed with the message text.

This kind of message will be received only if you set the “javascriptevents” applet parameter to 2. (by default is set to 1)

Set the javascriptevents applet parameter to receive all messages (you might also increase the loglevel in this case)

Please check the JSAPI.htm source for a working demo.


Examples

In our demo package you should find several HTML examples for the webphone deployment. You can try them by just opening them from your local PC.

VoIP server providers webpage

Applet tag placed on VoIP server providers’ webpage, allowing their customers to make VOIP calls directly from the browser:

<applet

archive = "webphone.jar"

codebase = "."

code = "webphone.webphone.class"

name = "webphone"

width = "300"

height = "330"

hspace = "0"

vspace = "0"

align = "middle"

>

<param name = "serveraddress" value = "sipserverdomain.com">

<b>Java is currently not installed or not enabled.</b>

</applet>

If the user is already logged in on your webpage, then you can make the applet more user-friendly by not asking for their username and password again.

In this case you should generate the html page with the “username” and “password” parameters prefilled (This can be done from your server side scripting, for example from PHP or .NET)

VOIP enabled forums

On your pages where you display the forum posts, near the nicknames you can display a small picture representing the online/offline/busy status of the actual user (presence status). The status of the user can be queried from your SIP server. If you use Mizu Softswitch, you have to initiate the v_userstatus ‘username’ SQL query to the database to know the status of the actual user.

If the agent is online, the button must be clickable and load a different page, iframe, div-ajax, object, frame, flash, javascript:NewWindow or whatever will launch the java applet.

<applet

archive = "webphone.jar"

codebase = "."

code = "webphone.webphone.class"

name = "webphone"

width = "240"

height = "50"

hspace = "0"

vspace = "0"

align = "middle"

>

<param name = "compact" value = "true">

<param name = "call" value = "true">

<param name = "serveraddress" value = "yourdomain.com">

<param name = "username" value = "loggedin_user_username">

<param name = "password" value = "loggedin_user_password">

<param name = "callto" value = "called_user_name">

<b>Display error here or offer java runtime download b>

</applet>

The serveraddress, username, password and callto must be generated properly from your server side scripting language (PHP, .NET or any other)

Workaround, when the browser doesn’t have java enabled

By using the Deployment Toolkit the java VM is automatically downloaded or upgraded if required.

If you are using the old “applet” or “object” methods you should direct the user to download the java runtime or present alternative methods to call. Example:

<applet

archive = "webphone.jar"

codebase = "."

code = "webphone.webphone.class"

name = "webphone"

width = "240"

height = "50"

hspace = "0"

vspace = "0"

align = "middle"

>

<param name = "compact" value = "true">

<param name = "call" value = "true">

<param name = "serveraddress" value = "yourdomain.com">

<param name = "username" value = "loggedin_user_username">

<param name = "password" value = "loggedin_user_password">

<param name = "callto" value = "called_user_name">

<p>

If you don't have Java installed you can install from <b>

<a href="http://www.java.com/en/download/index.jsp">here</a></b>.<br>

You must allow this applet to access your computer (Accept the certificate,

Click on allow blocked content on IE).<br>

Otherwise it cannot access you microphone and cannot initiate phone calls.<br>

If Java doesn't work for you, then click <b>

<a href="sip:// called_user_name@yourdomain.com">here</a></b> to start a call from

your desktop soft phone application.<br>

If you don't have a softphone you can download a free one from <b>

<a href="http://www.mizu-voip.com/Download.aspx">here</a></b></p>

</applet>

Detect java runtime with java-script:

<HTML>

<HEAD>

<SCRIPT LANGUAGE="JavaScript">

onError = errHandler; // Without he parentheses, because we don't want IE to do this. Like this, only NS does.

function appLoaded() {

if (!document.applets[0].isActive)

alert("IE: Applet could not be loaded");

}

function errHandler() {

alert("NS: Applet could not be loaded");

consume();

}

</SCRIPT>

</HEAD>

<BODY onLoad = appLoaded();>

<applet code="webphone.class" archive="webphone.jar" height="50" width="240">

<param name=" webphone" value="/etc/inet/hosts">

</applet>

</BODY>

</HTML>


Version history

Version 1.0

-initial stable release (RFC 3261 and 2543, PCMU, PCMA)

Version 1.2

-new: DTMF with INFO

-new: speex codec

-new: IM (chat) with MESSAGE method

-new: basic presence

-fix: sip signaling message handler

Version 1.4

-new: quick STUN

-new: rtport handling

-new: GSM codec

-new: outbound proxy

-new: applet parameters: signalingport, rtpport, register interval

-fix: registration and call timeouts

-fix: authentication sent with all request

-fix: sip stack initialization on Vista

-improvement: jitter buffer

-improvement: thread priority optimizations

Version 1.6

-fix: sip message parser

Version 1.8

-new: mute, transfer, redial

-improvement: handling record route

-improvement: rtp packet replay to all request -open NAT

Version 1.9

-fix: via branch and to tag was kept persistent across dialogs

-fix: save setting not worked since version 1.6

-fix: redial

-improvement: opening NAT at call begins by sending UDP packets to possible destinations

-improvement: jitter buffer fine-tune and configuration possibilities

-improvement: receiving early media (like ringtones and announcements)

Version 2.0

-fix: handling ACK for 200 OK

-improvement: extended authentication options (qop, auth-int)

Version 2.1

-new: multiple lines (up to 4)

-new: select audio device

-new: volume controls

-improvement: attended transfer

-fix: call transfer Refer-to URI brackets

-fix: auto dial and register

Version 2.2

-new: call hold option

-new: default volume applet parameters

-new: java to javascript API

-new: javascript to java API

Version 2.3

-new: ringtone for incoming and outgoing calls

-improvement: ability to enable/disable/set priority for g711 codec’s

-fix: hold and mute sometimes disabled

-fix: register endpoint timeout

-fix: cdr records not sent to javascript

Version 2.4

-new: more options to enable/disable certain functions

-improvement: call transfer compatibility

-improvement: better handle reinvite requests

-fix: microphone control change bug

Version 2.5

-improvement: multiline status management

-improvement: call hold and call transfer

-improvement: changed some default GUI settings

-fix: some incoming calls was dropped because wrong cseq initialization

Version 2.6

-fix: ring not stopping on call reject/hangup

-fix: call transfer sends wrong refer-to URI

-fix: display registered status when not registered

-improvement: new discontransfer applet parameter

Version 2.7

-fix: route/record-route handling in transfer, hold and disconnect

-fix: cseq sometime is not increased for subsequent register requests

-improvement: OpenSIPS compatibility

-improvement: new color parameters

Version 2.8

-new: authorization name and display name parameters

Version 3.0

-new: g.729 codec

-new: wideband and ultra-wideband codec

-auto convert mono to stereo sound

-improvement: better audio device handling (try to open all existing device on failure)

-fix: some SIP messages don’t contain the URI in message header

Version 3.2

-new: accept header

-new: API_MuteEx function
-new: jnlp documentation and examples

-improvement: allow header now list all supported methods

-improvement: remaining credit display timings

-improvement: display sent dtmf digits

-improvement: support for multiple instances

-fix: sdp body is missing from INFO messages sending DTMF

-fix: removed static variables to improve multithread stability

Version 3.3

-new: deployment toolkit example

-improvement: js and jnlp now accept jre 1.4

-fix: compatibility fix for jre 1.4

Version 3.4

-new: http tunneling

-new: DTMF RFC2833

-new: Toolkit_with_JS.htm deployment example

-new: easy encryption for all applet and java function string parameters

-new: API_SetParameter function

-new: code frame count setting

-improvement: possibility to pass MD5 instead of password

-improvement: js and jnlp now accept jre 1.4

-fix: API_SendDtmf was not able to send more than one DTMF digit at once

-fix: STUN sets external IP even on wrong conditions

Version 3.5

-new: http tunneling using browser http send/receive capabilities to automatically bypass http proxies

-new: plc algorithm (packet loss concealment)

-new: Spanish translation

-new: capability request applet parameter and function call

-new: media timeout option

-new: srv dns record lookup option

- improvement: rtcp option

-fix: final codec offer in ACK caused one way audio problem. Now this can be disabled with the setfinalcodec option.

-fix: sequence number overrun caused media RTP problems after 21 minute

Version 3.6

-new: api_playsound

-new: ackforauthrequest

-new: 100rel PRACK support

-new: earlymediasend applet parameter

-new: logtoconsole applet parameter

-new: autoaccept applet parameter

-new: rejectonbusy applet parameter

-new: sendmac applet parameter

-new: call timeout setting

-new: API_GetVersion

-new: API_Chat

-new: API_TransferDialog

- improvement: show the sip display-name for incoming calls

- improvement: receive chat messages as javascript notifications

-improvement: call to URI (loading the server from URI and not from settings)

-improvement: discparty parameter in CDR records

-improvement: transfertype 3 and 4

-improvement: http tunneling

-improvement: java script event notifications

-fix: background color settings in the chat and audio settings form

-fix: one way audio on some circumstances since version 3.5

-fix: restored compatibility with java 1.4

-fix: authentication with empty parameters (for example empty opaque)


Demo version

We are providing a demo version which you can try and test before any payment. The demo version has all features enabled but with some restrictions to prevent commercial usage. The limitations are the followings:

Ø maximum 10 simultaneous webphone in the same time

Ø will expire after several months of usage (usually 2 or 3 month)

Ø has 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 minute after that you have to restart it or restart the browser

Ø can be shut down from Mizutech license service

We can also send out a demo for our partners with only the trial period limitation (will expire after several months of usage) and without the other limitations.


Licensing

This section is about licensed versions (not the demo version).

The webphone is sold with unlimited client license or restricted number of licenses. 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. We have to hardcode your VoIP server(s) address (IP or domain name) and/or your website(s) address. After successful tests please ask for your final version at support@mizu-voip.com .

Release versions don’t have any limitations (mentioned below in the “Demo version” section) and are customized for your domain. All “mizu” and “mizutech” word are removed and the self signed certificate is with your company name or domain name.

Your final build must be used only for you company needs (including your direct sip endusers).

Title, ownership rights, and intellectual property rights in the Software shall remain with MizuTech and/or its suppliers.
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.

Some audio codecs that can be used with the webphone (e.g. g.729) can be patented in your country and require you to pay royalties to their licensors (patent license per channel). Mizutech doesn’t sell codec patent licenses.

You may:

Use the webphone on any number of computers
Give the access to the webphone for your customers or use within your company
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
Sell “webphone” services for third party VoIP providers and other companies
Reverse engineer, decompile or disassemble the webphone
Modify the software in any way (except modifying the applet parameters and to add digital certificate if needed)
Rent, lease, grant a security interest in, or otherwise transfer purchase rights of the webphone


FAQ

How to get my own webphone?

If you are satisfied with our software functionality and quality then write an email to sales@mizu-voip.com . On your payment we will send your version within one workday. You will have to send us your VoIP server(s) address (ip or domain) and/or your web server(s) address because these have to be hardcoded in your release; otherwise anybody could just download it from your website and use as it owns.

What about support?

We offer free basic (email based) support to all our customers.
For “gold partners” we offer phone and 24/7 emergency support.
Maintenance upgrades are also free.
Let us know if you have any questions or difficulties. Email to support@mizu-voip.com

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

No. The applet 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. Basic Java Script knowledge is required only if you plan to use the Java Script API.

Is there any way to get the source code?

No. The VoIP applet is a close-source application.

Is it working with any VoIP servers?

Yes. The webphone 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.
If you have any incompatibility problem, please contact support@mizu-voip.com with a problem description and a detailed log (loglevel set to 4). For more tests please send us your VoIP server address with 3 test accounts.

Is it working with any mobile device?

No. The webphone works only on devices that have Java Standard Edition. For Java Mobile Edition we have a separate client application that can be used to initiate calls, callbacks, phone to phone calls or send SMS message trough our VoIP server.

Is it working with any browsers?

Yes. We have made tests with all major browsers and we have not found any incompatibility issues. None of the existing users has applet or OS dependent issues.

Are there benefits or drawbacks making SIP calls using Java applet vs a Flash component?

Flash doesn’t have the codec’s commonly used in VoIP (such as g711 (pcmu/pcma), gsm, speex, g.729, g.723, etc) and plugins are not allowed. It has only its proprietary codec, so all implementation will need a separate “media gateway” which will do the conversion. Please note that codec conversion should be avoided in VoIP whenever possible because sound quality loss, high resource utilization, additional costs and additional network complexity.

Can Mizutech do custom development if required?

Yes, please contact us at support@mizu-voip.com .

Can you reduce the size of the applet?

Although the default applet size is very small by default, we can reduce the size of your copy even more by removing some components not used by you. Contact us about the possibilities. You might be required to pay for this additional customization.

What kind of licensing options are available?

We are selling the webphone with unlimited client usage. We have separate pricing options to fulfill all of our customers’ needs and budget.
Alternatively we can offer the applet as a service with small monthly fees, but this may be not so efficient like the one-time payment (because increased bank fees for small amount of transfers)

How to use the webphone user account securely?

The following methods can be used to secure the webphone usage:

-don’t hardcode the password (let the users to enter it)

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

-pass the password parameter encrypted

-instead of password, use the MD5 and the realm parameters

How to encrypt the applet parameters?

You just have to prefix them like:
encrypted__X__encryptedvalue where X means the id of the encryption method used:
1: simple xor (Each webphone has it’s unique key. Ask your key from Mizutech support)
2: des (most secure but more difficult to implement)
3: xor+base64 (this is the preferred method; easy to use and secure enough)
4: base64 (unsecured)
Example: <param name = "password" value = "encrypted__3__d3691adb28b5591">

You can also use the applet to make the encryption for your parameters. For this, launch the applet with “loglevel” set to 4.
An “encrypt” button will appear on the bottom of the screen.

The same format can be used to encrypt the string parameters for the API function calls.

You should restrict the webphone account (usage, routing) from your VoIP server to make the webphone more secure.

Example for XOR encryption

These examples are written in Java but you should be able to find similar functionalities in your preferred language be it JavaScript, PHP, J2EE, .NET or any other programming environment.

public static String strxor(String str, String key) {

try {

String result = null;

byte[] strBuf = str.getBytes();

byte[] keyBuf = key.getBytes();

int c = 0;

int z = keyBuf.length;

ByteArrayOutputStream baos = new ByteArrayOutputStream(strBuf.length);

for (int i = 0; i < strBuf.length; i++) {

byte bS = strBuf[i];

byte bK = keyBuf[c];

byte bO = (byte)(bS ^ bK);

if (c < z - 1) {

c++;

} else {

c = 0;

}

baos.write(bO);

}

baos.flush();

result = baos.toString();

baos.close();

baos = null;

return result;

} catch (Exception e) { Common.PutToDebugLogException(3,"xor",e); }

return str;

}

Example for DES encryption

import javax.crypto.*;

import javax.crypto.spec.*;

import java.security.spec.*;

public class DesEncrypter {

Cipher ecipher;

Cipher dcipher;

String passPhrase = "XXX"; //get from Mizutech

int iterationCount = 3;

// 8-bytes Salt

byte[] salt = {

(byte)0xA9, (byte)0x9B, (byte)0xC8, (byte)0x32,

(byte)0x56, (byte)0x34, (byte)0xE3, (byte)0x03

};

DesEncrypter()

{

try{

KeySpec keySpec = new PBEKeySpec(passPhrase.toCharArray(), salt, iterationCount);

SecretKey key = SecretKeyFactory.getInstance("PBEWithMD5AndDES").generateSecret(keySpec);

ecipher = Cipher.getInstance(key.getAlgorithm());

dcipher = Cipher.getInstance(key.getAlgorithm());

AlgorithmParameterSpec paramSpec = new PBEParameterSpec(salt,iterationCount);

ecipher.init(Cipher.ENCRYPT_MODE, key, paramSpec);

dcipher.init(Cipher.DECRYPT_MODE, key, paramSpec);

} catch (Exception e) { Common.PutToDebugLogException("des ctor",e); }

}

public String encrypt(String str) {

try {

// Encode the string into bytes using utf-8

byte[] utf8 = str.getBytes("UTF8");

// Encrypt

byte[] enc = ecipher.doFinal(utf8);

// Encode bytes to base64 to get a string

return new sun.misc.BASE64Encoder().encode(enc);

} catch (Exception e) { Common.PutToDebugLogException("des encrypt",e); }

return str;

}

public String decrypt(String str) {

try {

// Decode base64 to get bytes

byte[] dec = new sun.misc.BASE64Decoder().decodeBuffer(str);

// Decrypt

byte[] utf8 = dcipher.doFinal(dec);

// Decode using utf-8

return new String(utf8, "UTF8");

} catch (Exception e) { Common.PutToDebugLogException("des decrypt",e); }

return str;

}

}

Parameter encryption explained

The simplest encryption method is the XOR encryption.

Each webphone has an unique key.

For the current key demo version it is “h39idbfqw7116ghh”.

To encrypt any string, you have to XOR it with this key byte by byte.

First char with ‘h’

Second char with ‘3’.

Third char with ‘9’

etc

To verify your work:

Set the “loglevel” applet parameter to 5.

An “encrypt” button will appear which will use the built-in encryption so you can use to encrypt any string with it or to verify your code used to generate the encrypted strings.

To pass a xor encrypted parameter you just have to prefix it with “encrypted_1_”.

For example instead of using

<param name = "username" value = "4444">

You can write the following:

<param name = "username" value = "encrypted_1_XORENCRYPTEDUSERNAME">

The same string format are also accepted on the java script api for the string function parameters.

XOR encryption should be used together with base64 encoding. In this case the encrypted_1_ prefix have to be changed to encrypted_3_

When using base64, first apply the xor, and base64 for the XORed bytes.

NAT settings

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 usestun and userport 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.

I have one way audio

1. Set the “setfinalcodec” applet parameter to 0 (especially if you are using Asterisk or OpenSIPS)
2. Set usestun and userport to 0 (especially if you are using SIP aware routers). If these doesn’t help, set them to 2.
3. Make sure that you have enabled all codec’s
4. 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” applet parameter to 4 for this)

The webphone doesn’t register if I am using the Java Script API

For the Java Script API to work correctly it is important to let the webphone to send the fist message to the server before you begin controlling it via the API. This can be done by using the AI_ServerInit function or one of the following applet parameters: register, call, capabilityrequest, natkeepalive. (If you already have the username/password information on startup, then you can set the “register” applet parameter to true and let the applet to register automatically. Otherwise the , capabilityrequest or natkeepalive applet parameters should be used. This is a workaround for Java security restrictions which will restrict the applet as it would be unsigned when it is controlled externally from JavaScript.

The webphone doesn’t receive incoming calls

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” applet parameter with supplied username and password)

Once the webphone is registered, the server should be able to send incoming calls to it.

The other reason can be if your server doesn’t handle NAT properly.

Please try to start the webphone with usestun parameter set to 0, and if still not works then try it with 2.

If the calls are still not coming, please send us a log (set the applet loglevel parameter to 4)

What is the default codec priority?

Set its priority to 3 and set the priority for all other codes to 2. In this case you preferred codec will be used whenever the other endpoint supports it and other codec’s are used only if otherwise the call would fail.
If the codec’s has the same priority set by applet parameters (2 or 3) than the following priority order will be applied:

1. speex ultrawideband

2. speex wideband

3. G.729

4. PCMU

5. PCMA

6. speex narrowband

7. GSM

(The other endpoint usually will pick up the first codec, or the webphone will pick-up the first in this list from the list of codec’s sent by the other peer)
*Please note that the G.729, GSM and speex narrowband codec’s are disabled by default. Set useg729,usegsm and usespeex to 2 or 3 to enable them. (Make sure you have the proper G.729 licenses)

How to prefer one codec?

Set its priority to 3 and set the priority for all other codes to 2. In this case you preferred codec will be used whenever the other endpoint supports it and other codec’s are used only if otherwise the call would fail.
For example the following parameters will set g.729 as the preferred codec:
 -useg729=3
-usepcmu=2
-usepcma=2
-usegsm=2
-usespeex=2
-usespeexwb =2
-usespeexuwb =2

How to use only one predefined codec?

Enable only one codec by applet parameters and disable all others. In this case the call might fail if the other end doesn’t support the selected codec.
For example the following parameters will force the softphone to use only pcmu:

-usepcmu=3
-usepcma=1
-useg729=1
-usegsm=1
-usespeex=1
-usespeexwb =1
-usespeexuwb =1

I got an upgrade for my feature/issue request, but nothings seems to be changed

Make sure that you are actually using the new version. Browsers can cache java applets so there is a change that you are still using the old version.

Close the webphone page, run the Java console and type 'x' to clear the JAR cache then restart all browsers instances and re-open the webphone page.

You might also clear your browser cache to be sure that the old version is deleted.

See also the “How to prevent browser caching” FAQ.

How to prevent browser caching?

When multiple webphone are used with different parameters, in some environments the browser can cache the previous download and not to apply the new parameters. This can be avoided by using different URL for the applets with different parameters.
Otherwise the applet cache can be disabled as described here and here .

How can I add an address book/contact list?

There is no contact list embedded in the webphone because this can be done very easy with any server side script (.PHP, .NET) and better adopted to your needs.

You can easily use the java script API to add VoIP functionality to your address book or contact list.

I have problems on MAC or/and with browser X

The simplest “applet” tag based deployment might not work properly under MAC but most all the other examples do. Please consult the “Popup.htm” or the “Toolkit.htm” source in the Examples directory. Alternatively you can consider deploying by JNLP.

The Java Script API is not working in my browser

Please check the JSAPI.htm and the Popup.htm source in the Examples directory for a working demo.

Also make sure that jar and jnlp mime types are allowed in your webserver.

More help on interaction between java and javascript:

http://java.sun.com/javase/6/docs/technotes/guides/plugin/developer_guide/java_js.html
http://java.sun.com/products/plugin/1.3/docs/jsobject.html
http://java.sun.com/docs/books/tutorial/deployment/applet/invokingJavaScriptFromApplet.html
http://java.sun.com/docs/books/tutorial/deployment/applet/invokingAppletMethodsFromJavaScript.html

The demo examples are not working on my PC

This issue can happen in some circumstances only if you launch the applet a from local file for testing (not from a web server).
Make sure that the file path is not too large for java. Copy the example directory to the C:\ directory and try again.

How can I use HTTP tunneling?

HTTP over VoIP is not a standardized protocol. This option can be used only with the Mizu VoIP server. To integrate it with your existing VoIP infrastructure you will have to use our VoIP tunneling server (no modification will be needed in your existing servers). We offer free trial install.

For http transport the “transport” applet parameter must be set to 3.

The webphone will use the browser capabilities to send/receive the html messages, thus bypassing all corporate firewalls.

To turn off proxy authentication, insert this line in your jnlp: <property name="javaws.cfg.jauthenticator" value="none" />

How to access the applet from Java Script

Example:

function getMizuApplet()

{

if (theApplet == null) {

theApplet = document.getElementById('webphone');

}

// See if we're using the old Java Plug-In and the JNLPAppletLauncher

try {

theApplet = theApplet.getSubApplet();

} catch (e) {

// Using new-style applet -- ignore

}

return theApplet;

}

// Call API_XXX() via the getMizuApplet() method

getMizuApplet().API_XXX();

For more examples please check the “JSAPI.htm” and the “Toolkit_with_JS.htm” files.

How to customize the applet loader?

You can use the JNLP deployment method with an icon parameter in the information section:
Example:
<information>

<title>Mizu Webphone demo</title>

<vendor>Mizutech</vendor>

<href>"http://www.mizu-voip.com/"</href>

<description>A VoIP client applet</description>

<description kind="short">VoIP client application to initiate phone calls over the internet.</description>

<icon href="http://www.mizu-voip.com/wicon.jpg"/>

<icon kind="splash" href="http://www.mizu-voip.com/wicon.jpg"/>

</information>

<icon>

Describes an icon/image that represents the application. Web Start uses the icons during startup in the download progress popup, for desktop shortcuts and in the Web Start application manager. 64x64 icons are shown in the download progress popup and 32x32 icons are used for desktop icons and in the Web Start app manager. Web Start automatically resizes icons with other dimensions.

Attributes:

href=url , required

Contains a URL to a web location containing an image or an icon. Only JPEG and GIF graphic formats are supported.

version=version , optional

Specifies the version of the image.

width=pixels , optional

Describes the width of the icon in pixels.

height=pixels , optional

Describes the height of the icon in pixels.

kind=default|selected|disabled|rollover, optional

Describes the use of the icon. Default value is default.

depth=number , optional

Describes the color depth of the image in bits-per-pixel. Common values are 8, 16, or 24.

size=bytes , optional

Specifies the size of the image in bytes.

SRV (service) domain record lookup not working?

For applet file size consideration we have decided to not include the handling of the SRV records in the default version. Most of the SIP servers are using A records only. If your server has SRV record instead of A record, then contact our support and we will send another build with this capability.

How can I replace the applet certificate?

To use a certificate that is recognized by Java installations on the internet, you need to get a certificate from a certification authority that have their root certificates shipped and installed with the JDK/JRE. You can list the installed root certificates with the following command: keytool -list -keystore /usr/local/j2sdkXXX/jre/lib/security/cacerts (adapt the path to your installation, press ENTER when asked for a password)

We are providing the java applet with a selfsigned certificate. You can replace this ceritificate with yours that you can purchase from CA companies like VeriSign, Equifax Secure, Entrust, GTE Cyber Trust, Thawte, GeoTrust, BALTIMORE, etc.

You will need to request a "code signing digital certificate for java applet”.

To apply your certificate you can use the jarsigner tool. You can read more details here and here .

Example:

check:

keytool -list -storetype pkcs12 -keystore codesigncert.pfx

get alias:

keytool -list -storetype pkcs12 -keystore codesigncert.pfx -v

sign jar:

jarsigner -storetype pkcs12 -keystore codesigncert.pfx -signedjar orig_webphone.jar result_webphone.jar KEY

Alternatively you can download a GUI for the jarsigner named KeyTool IUI


Resources

You can find more details about java applet deployment here: http://java.sun.com/docs/books/tutorial/deployment/applet/deployindex.html

Mizu WebPhone homepage : http://www.mizu-voip.com/Home/WebPhone.aspx

Demo (running older version): http://www.mizu-voip.com/Home/PublicPhone.aspx
Example html: Example.htm (if you have received it with this document)

For help, contact support@mizu-voip.com

Copyright © 2008-2010 MizuTech


Contents

About 2

Quick Start 2

Features. 2

Usage examples . 3

Benefits. 3

Requirements. 3

User interface. 3

Deployment 4

Main Parameters . 5

Appearance Parameters. 6

Other Parameters . 8

JavaScript API 15

Examples. 19

Version history . 20

Demo version. 23

Licensing. 23

FAQ.. 23

Resources. 30