Using RTCKit API

In order to use RTCKit, you need to include additional JavaScript libraries. RTCKit uses swfobject library to facilitate cross-browser interaction with Adobe Flash Player.
<head>
    <script src="http://rtckit.com/api/swfobject.js"></script>
    <script src="http://rtckit.com/api/rtckit.js"></script>

Web-page container for Flash WebPhone

Somewhere inside your web page body, you need to define a container for embedding. The container's dimensions need to be at least 217x140 pixels in order to fit standard Flash dialog about permission to use camera and microphone. Due to limitations of Flash technology the container cannot be placed inside a <form> tag.

<div id='webPhoneContainer' style='width: 217px; height: 140px'>
Error: You do not have Flash Player 10.1 or above
</div>

WebPhone creation

It is good practice to first check that WebPhone is supported on user's browser:

if (!RTCKit.webPhone.isAvailable())
    alert('WebPhone is not available!');

You begin by embedding WebPhone and connecting to RTCKit servers. Connection is done asynchronously and a callback function is executed on successful connection. The same function is also called when webPhone is disconnected for some reason (e.g. Wi-Fi signal lost).

RTCKit.webPhone.embed({
    container: 'webPhoneContainer', // id attribute of the container element
    video: true         // enable/disable video calls
});

RTCKit.webPhone.onConnectStateChanged = function(connectInfo) {
    if (connectInfo.connected)
        alert('WebPhone connected');
    else
        alert('WebPhone lost connection: network down?');
}

RTCKit.webPhone.connect(); // connect to RTCKit server

RTCKit.webPhone.isConnected(); // check connection status

SIP registration

After successful connection it is possible to register on any SIP or Jingle VoIP provider. If you need to call landlines, mobiles or your any SIP servers without SIP-registration, then you can register without a provider using 'phone' protocol. The results of asynchronous registration are passed to a callback function.

// called on success/failure
RTCKit.webPhone.onRegStateChanged = function(regInfo) {
    alert(regInfo.registered);  // regisration state (boolean)
    alert(regInfo.info);        // error message (if any)
}

// Regisration
RTCKit.webPhone.register({
    protocol:  'sip',
    registrar: 'talkpad.ru',    // SIP registrar, host[:port]
    username:  'alice',
    password:  'password',
    display:   'Alice B.'       // display name (optional)
    auth:   authToken           // authorization token (see below)
});

// Jingle registration
RTCKit.webPhone.register({
    protocol: 'jingle',
    domain:   'gmail.com',      // XMPP server
    username: 'alice',
    password: 'password',
    auth:   authToken           // authorization token (see below)
});

// Phone registration (calls to landlines and mobiles)
RTCKit.webPhone.register({
    protocol: 'phone',
    auth:   authToken           // authorization token (see below)
});

// cancel registration
RTCKit.webPhone.unregister();

// check registration status
RTCKit.webPhone.isRegistered();

Authorization

For security reasons it is necessary to restrict numbers, to which calls can be made. For example, this is needed when you allow placing your call widget on an arbitrary web site. To do this, you need to find out your public and private keys on 'Authorization' page, and then generate an authorization token:

var authToken = {
    // public key (not private!)
    key: 'jGNnCmH0UKw0Rs5N74',
    
    // where calls can be made: * - any string, comma - OR
    mask: '*@talkpad.ru,*@sipnet.ru',
    
    // time, when token expires in UNIX format
    expires: 1322646919,
    
    // signature: SHA1(mask + expires + private_key) in hex format
    signature: '85360fd34149e6dcdb538ec3834488fd2fb8c19c'
}

Authorization token is used during registration.


Managing calls

After a successful registration it is possible to make calls. As always, call functions are asynchronous and results are passed to a callback.

RTCKit.webPhone.onCallStateChanged = function(callInfo) {
    alert(callInfo.uri);        // SIP URI or Jingle ID
    alert(callInfo.state);      // call state ('IDLE', 'INCOMING',
                    // 'OUTGOING', 'CONNECTED')
    alert(callInfo.display);    // display name of remote caller (if any)
    alert(callInfo.info);       // reason for call termination (if any)
    alert(callInfo.video);      // call type (voice or video)
}

// SIP call (voice or video)
RTCKit.webPhone.call({uri: 'sip:bob@talkpad.ru', video: true});

// Jingle call
RTCKit.webPhone.call({uri: 'username@gmail.com'});

// call to landline or mobile
RTCKit.webPhone.call({uri: '12081234567'});

// hangup
RTCKit.webPhone.hangup();

// answer an incoming call (and choose to enable video)
RTCKit.webPhone.answer({video: true});

// tone dialing (DTMF)
RTCKit.webPhone.dial({digits: '12345', method: 'inband'});
// tone dialing methods 'inband', 'info' and 'rfc2833' are supported

// current call state ('IDLE', 'INCOMING', 'OUTGOING', 'CONNECTED')
RTCKit.webPhone.callState();

Phone number encryption

Phone numbers can be encrypted for privacy reasons. This can be done for mask field in authorization token and for uri of outgoing call (except for Jingle protocol).

Encryption uses AES algorithm with 256-bit key in CBC mode. The encryption key is the first 32 bytes of your private key, which can be obtained in personal cabinet or using HTTP API. Initialization vector is all zeros. If the length of input string is not a multiple of 16, zero bytes need to be appended at the end.

// call enctypted number
RTCKit.webPhone.call({uri: 'aes:617017418c6290acce410f9689c452d0'});

WebPhone logs

WebPhone logs are used mainly for debugging and are passed to log handler:

RTCKit.webPhone.onLogMessage = function(message) {
    alert(message.level);       // level ('info' or 'error')
    alert(message.text);        // log message text
}

Microphone and webcam settings

Flash Player's security policy requires the user to grant permission to use microphone and webcam for calls through the following security dialog:

Permission is asked automatically during first call, however it is also possible to do it manually:

// ask user permission to use microphone and webcam
RTCKit.webPhone.showMicDialog();

// advanced dialog with 'remember' option
RTCKit.webPhone.showSettings();

// event about user's choice
RTCKit.webPhone.onMicStateChanged = function(micInfo) {
    alert(micInfo.allowed);
}

// get current status
alert(RTCKit.webPhone.getMicState().allowed);
You can control volume and microphone gain using these functions:
RTCKit.webPhone.getVolume();
RTCKit.webPhone.setVolume(50); // between 0 and 100

RTCKit.webPhone.getMicGain();
RTCKit.webPhone.setMicGain(80); // between 0 and 100
You can also get a list of available microphones and change active microphone:
RTCKit.webPhone.listMicrophones(); // returns an array of microphone names

RTCKit.webPhone.getMicIndex(); // zero-based index of active microphone
RTCKit.webPhone.setMicIndex(0); // in above array

Example

RTCKit.webPhone.embed({container: 'container'});

RTCKit.webPhone.onConnectStateChanged = function(connectInfo) {
    if (connectInfo.connected) {
        RTCKit.webPhone.register({
            registrar: 'talkpad.ru',
            username: 'rtckit',
            password: 'rtckit'
        });
    }
};

RTCKit.webPhone.onRegStateChanged = function(regInfo) {
    if (regInfo.registered)
        RTCKit.webPhone.call({uri: 'sip:echo@talkpad.ru'});
};

RTCKit.webPhone.connect();