Telegenta client lib

A browser client library for using Telegenta phone services

Detailed documentation

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

Documentation for a specific version is at https://www.telegenta.com/docs/webclient/<version>/index.html, e.g. https://www.telegenta.com/docs/webclient/3.2.0/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.

Runnable examples live in demos/. They load the browser bundle from ../dist/telegenta.min.js, so run npm run build first, then serve the directory over https. WebRTC requires a secure context; localhost counts as secure, but opening a demo as file://... does not - media permissions are not remembered there, so you will be prompted for the microphone every time.

Example: phone with a provisioning token

demos/phone_client.html is a complete softphone - start/stop, outbound calls, transfer, listen-in, incoming calls and the event client. A hosted copy is published with the docs: https://www.telegenta.com/docs/webclient/latest/demos/phone_client.html

First create a static API token in the admin interface (https://admin.telegenta.com/integration/access-tokens). Open the demo and paste the token in; it then

1. requests a short-lived provisioning token with GET /api/get-call-session/?id=<account id>, and
2. starts the phone with that token:

const opts = {
    // Enable event client
    connectEventService: true,

    // Subscribe to detailed information about call after processing
    useCallDataInfoEvent: true,

    // Enable incoming calls (you must set a phone number to call the account also)
    register: true,

    // Configure client with provision token
    provisionToken: data.provision_token,
};

phoneClient.start(opts);

Issuing the provisioning token from your own backend is the recommended integration: the short-lived token is all that reaches the browser, and your API token stays on the server.

The remaining demos cover narrower cases:

• demos/event_client.html - the event client on its own, without a phone
• demos/calldata_available.html - subscribing to call data after a call completes
• demos/add_phone_number.html - adding a phone number through the API
• demos/embedded_config.html - embedding the admin config pages with a config token

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 and provide your own frontend. Load dist/telegenta.min.js in the browser (global Telegenta) or import the package in your bundler, then handle events and use javascript methods like call, hangup, startRecord, etc.. demos/phone_client.html shows the whole flow end to end.

Migrating from 2.x

If you are migrating from 2.x, there are only few non breaking code changes.

• We no longer support ES5 and CommonJS going forward we will only support ES6 and ESM modules.
• The utility library @Telegenta/common have been deprecated is now merged into phone client package.

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é

Changelog

3.2.0

• Phone.setCallToken(token): replace the call token without restarting (tokens expire after 30 min). With useCallDataInfoEvent, the callDataInfo subscription keeps the token from start(); call start() again to move it to the new token.
• Phone.prepareMedia({ deviceId }) and Phone.setInputDevice(deviceId): microphone selection
• Phone.prepareMedia() without a deviceId resets a microphone previously chosen with setInputDevice()
• Phone.setOutputDevice(deviceId) and Phone.outputDeviceSelectionSupported: speaker selection
• prepareMedia() releases the microphone after the permission probe
• Phone.resumeAudio(): resumes the signal-tone AudioContext; call it from a user-gesture handler, since a phone started on page load gets a "suspended" context and plays no tones. Tones also try to resume it themselves. One AudioContext per Phone is now reused across start()/stop() (previously every start() created a new one that was never closed)
• prepareMedia() now rejects instead of throwing synchronously, and a failed request no longer changes the selected microphone or media-permission state unless the browser actually denied permission (NotAllowedError/SecurityError)
• start() no longer mutates the shared default options between Phone instances
• stop() now always marks the phone stopped
• Phone.register(): re-sends REGISTER without restarting the phone or dropping active calls (throws NotReady if not started) - for recovering a REGISTER refresh that failed for a reason other than bad credentials, which JsSIP does not retry on its own
• connectionStateChange now carries cause and statusCode alongside state when state is REGISTRATION_FAILED (from JsSIP's registrationFailed event), so callers can tell a transient network failure (JsSIP retries on its own) apart from an authentication/authorization failure (401/403) that needs a fresh call session

License

This software is provided for free together with our service