Telegenta client lib

A browser client library for using Telegenta phone services

Detailed documentation

Please go to: https://www.telegenta.com/docs/index.html

Why this library?

There are many great implementations of WebRTC based SIP clients and most work really well, but we found there are still many things which must handled before you can actually start using them and it just requires a lot of domain specific knowledge and time to get everything working.
If you want to provide a good phone service in you application, you will (probably) need to deal with the following issues:

1. Supporting all browsers takes time and needs extensive regular testing because of inconsistencies in browser WebRTC implementations
2. Handling media and devices in the browser requires rarely used knowledge (MediaDevices and WebRTC API)
3. Features like recording, show number, call privacy are provider specific and not standardized, you will need to develop your own support for this
4. It is almost impossible to use WebRTC on "server side" generated frameworks (like PHP), if you click a link and page is reloaded, your call is terminated
5. Browsers support multiple tabs and you risk having multiple calls at the same time, you need to handle this scenario
6. The SIP account credentials can be viewed by everybody, using browser developer console (F12) making them susceptible to abuse and fraud
7. Unless all your agents uses the same credentials (pretty bad security practise), you'll need to handle and maintain individual accounts, which can take a lot of your time
8. Make sure you don't accidentally close the window, click a link or reload the page during active calls

As you start developing, you will probably find more issues (these are just the most common). They all require your time and developer resources, making the case less and less attractive.

Using this library and api service you will have at least one solution to all these challenges, providing you a quick way to get up and running.
We also provide a simple embedded html client, which you can use as a "starting point", just include it in your project and you are ready to go. The client has no external requirements (like jQuery and Bootstrap) - only our client library of cause.

Getting started

Before starting, you will need an account on telegenta.com, to create sip accounts and api tokens.

Example 1: Simple phone with static account

In this example we will use a normal SIP User account, as it does not require you to use our API service.

Log into the administration frontend (https://admin.telegenta.com) and create a "SIP User account", this will provide you with credentials (username and password). Once you have these open the embedded html client provided with this library /embedded_client/index.html and modify the credentials:

// SIP account username and password
var USERNAME='your username';   
var PASSWORD='your password';

window.onload = function () {
...      

Now open the file (index.html) in your browser. After you have been prompted for permission to use the audio devices, you should have a working phone.
Note: If you are viewing a file using "file://index.html", it is not considered a secure connection by the browser and media permissions are not remembered, so you will be prompted every time you open the file.
However, once you move the file to a secure webserver (https), this will no longer be an issue.

Example 2: Using SIP Flex accounts

When using SIP flex accounts, you need to use our API service to retrieve account information first.
This approach solves the authentication problem and provides you with short-lived sip accounts used in client sessions. For this example we need a backend service and we provide a simple example in PHP using the built in Webserver.

First go to the admin interface and create following 2 items:

1. SIP Flex account with "flex account identification" set to 'test'
2. A static api token (https://admin.telegenta.com/integration/access-tokens).

Now open the file /embedded_client/server.html and insert the API token at the top of the file:

// Your API Token
$api_auth_token = '<your api token>';

// The flex account identification (this is set when configuring your flex accounts)
// It possible to have multiple sip flex accounts with different configurations
$flex_identification = 'test';
...

Once you have added the token, you can start the php Webserver (requires php v5.4+) like this:

cd embedded_client
php -S localhost:9000

Now open the URL http://localhost:9000/server.php and you should see the phone and be able to perform calls. Note: If you use any other host than localhost, you won't be able to call because the built in php webserver does not support secure (https) connections and this is required by the browser to use WebRTC. If needed, you can tunnel to
localhost using your ssh client for testing.

Approaching the integration

Every application is different, so it can be hard to come up with one solution that fits all.
Depending on how much flexibility you need, you can choose between the following options:

1. Use an existing WebRTC client like JsSIP, SipML, SipJs, etc..
   We believe in using standard protocols as much as possible and it will work nicely, but you need to address most of the issues we listed above in the previous section yourself.

2. Use our free library (lib/telegenta.min.js) and provide your own frontend
   This way you just need to handle events and use javascript methods like call, hangup, startRecord, etc..

3. Use our complete embedded phone client with frontend.
   We have made a simple phone with frontend, which can be easily included in your own project. Just grab the index.html, style.css and embedded_phone.js and insert it into your own project.
   We named the JS and CSS to try and avoid any potential conflicts.
   You only need to provide it with credentials or provisioning token (as in the example above) from you backend and you are set to start calling.

Migrating from 1.7.x

If you are migrating from 1.7.x release into 2.x, some code breaking changes needs to be handled.

• Library now supports multiple sessions, which means call now returns session object instead of uuid and incoming call event will contain new session as well. If you still need the call uuid, the session object has a UUID property

• Many sessions specific methods like hangup(), startRecording(), sendDTMF(), etc. have been moved to the session object

• calldataAvailable event no longer exists and has been split into two new separate events:

  • session.callEnded : local event containing simple call information
  • phone.callDataInfo : Remote server event containing detailed call information (billing info and recording url).

• Incoming calls will now create a new session, which must be handled by 'incomingCall' event

• Audio device selection hs been remove from 2.x release (will be added later) audioInputDeviceList(), audioOutputDeviceList(), setAudioInputDevice(), setAudioOutputDevice(), supportsDeviceSelection() has been removed

• New methods to handle sessions have been added, to facilitate switching between calls and transferring them

  • hold() : Hold call
  • unHold() : Unhold call
  • transfer() : Transfer call from one session to another (assisted transfer)

• RemoteAudioElement no longer needed, will be created automatically

• Session IDLE state removed and autoIdleTime is replaced with autoRemoveSessionTime

• Remember to update "@telegenta/common" npm

• Phone state "RINGING" changed named to "INCOMING" because it was ambiguous with outgoing calls

• Added option to play ringing tone on incoming calls (playRingOnIncoming)

Acknowledgements

This library uses the JsSIP library (www.jssip.net) created by José Luis Milàn, Iñaki Baz Castillo and Saúl Ibarra Corretgé

License

This software is provided for free together with our service