Webitel and Single Page Application integration example
This document describes the bases of the integration Webitel with any web based single page application (SPA).
The main points of the integration are:
Important
Webitel and SPA must use HTTPS connections with a valid SSL certificates, signed by the known CA.
General webitel integration settings
For integration purpose, you need to store on the SPA side the 4 settings:
- Webitel REST API endpoint. An example, https://cloud.webitel.com/api/
- Webitel Web Socket endpoint. An example, wss://cloud.webitel.com/ws/
- Webitel integration token.
- Webitel users domain. Internal webitel domain, an example, my-company.lo
Creating a user and store an integration token
First, you must create a user that will use Webitel from an SPA. The main user properties are:
- Name – name of the user.
- Login – login for the user. It can be the same as a user's extension.
- Password – random string.
- Extension – user's extension (internal phone number).
- Product license key – users without license can't log in into Webitel.
- WebRTC device – users without a device can't use WebRTC calls from the browser.
Creating a device
We will create WebRTC device for our future user using Webitel REST API endpoint and integration token
POST https://cloud.webitel.com/api/devices { "name": "device for user 1", "account": "sipUser1", "password": "BNZdVLryFwcB" }
In response, we will get the body with new device ID:
{ "id": "7287", "name": "device for user 1", "account": "sipUser1", "password": "BNZdVLryFwcB", "user": {}, "logged_in": "1682943253855", "created_at": "1682943253855", "created_by": { "id": "130", "name": "Administrator" }, "updated_at": "1682943253855", "updated_by": { "id": "130", "name": "Administrator" } }
Create a user
Now, we will create a user with WebRTC device, using Webitel REST API endpoint and integration token:
POST https://dev.webitel.com/api/users { "name": "User1", "email": "user1@gmail.com", "username": "2020", "password": "dl75lfLcOLLL", "extension": "2020", "roles": [ { "id": 4 } ], "device": { "id": "7287" }, "license": [ { "id": "95309f22-0d7c-4fb9-baab-9911898019c4" } ], "devices": [ { "id": "7287" } ] }
In response, we will get the body with new user ID:
{ "id": "10457", "name": "User1", "email": "user1@gmail.com", "username": "2020", "password": "$2a$06$nHfkK0hnD1PV9DnVF2gAaObQgkTSP8hpPYsL91kGupeL3gegO12Di", "extension": "2020", "device": { "id": "7287", "name": "device for user 1" }, "devices": [ { "id": "7287", "name": "device for user 1" } ], "license": [ { "id": "95309f22-0d7c-4fb9-baab-9911898019c4", "prod": "CALL_CENTER", "issued_at": "1682943766016", "expires_at": "1735682336000" } ], "created_at": "1682943766011", "created_by": { "id": "130", "name": "Administrator" }, "updated_at": "1682943766011", "updated_by": { "id": "130", "name": "Administrator" } }
Create user token
The last one, we will need an integration token for the new user:
POST https://dev.webitel.com/api/users/10457/tokens { "token": "", "usage": "integration app" }
In response, you will get the token for the user:
{ "id": "fa9a1f17-66df-4b30-a18f-f3c47a069615", "token": "8kfujojttpdgjj4e15snbmmcua", "usage": "integration app", "user": { "id": "10457" }, "created_at": "1682944048425", "created_by": { "id": "130", "name": "Administrator" }, "updated_at": "1682944048425", "updated_by": { "id": "130", "name": "Administrator" } }
So, inside your SPA, for each user, you must store:
- user ID
- device ID
- user token
Using Webitel client JavaScript library for WebRTC calls or Click-To-Call functionality
Webitel has own JavaScript library that supports:
- Originate a call
- Answer on inbound call (with WebRTC only)
- Hold
- Transfer the call
- Send DTMF
- Hangup the call
You can find the example of the web-phone by this link: https://git.webitel.com/projects/WEP/repos/vue-phone-example/browse
import {Client, CallActions} from "webitel-sdk/esm2015/socket"; let instance = null; function getConfig() { const token = localStorage.getItem('token') const endpoint = localStorage.getItem('ws-endpoint') if (!token || !endpoint) { return null } return { token, endpoint } } export function resetConfig() { localStorage.setItem('token', '') localStorage.setItem('ws-endpoint', '') } export function setConfig(token, endp) { localStorage.setItem('token', token) localStorage.setItem('ws-endpoint', endp) } export async function logout() { resetConfig() if (instance) { await instance.disconnect() instance = null } } export async function socket(store) { if (instance) return instance const conf = getConfig() if (!conf) { store.commit('login') return } const client = new Client({ endpoint: conf.endpoint, // Webitel Web Socket endpoint token: conf.token, // User token registerWebDevice: true, // enable WebRTC debug: true, }) store.commit('initWs', client) try { await client.connect() // open socket await client.auth() // auth } catch (e) { store.commit('login') resetConfig(); return } client.subscribeCall((action, call) => { /* call props: id - call id destination - destination number direction - direction from - from number to - to number variables - additional call metadata methods: call.answer({}) - answer the call call.hangup() - hangup the call call.hold() - hold call.unHold() - unlold call.reporting({success: true/false}) - send the call reporting (for the CallCenter) */ switch (action) { case CallActions.Ringing: // new inbound call store.commit('newCall', call) break; case CallActions.Active: // answered call case CallActions.Hold: // case CallActions.Hangup: // ended call case CallActions.Bridge: // case CallActions.LocalStream: // local webrtc stream (call.localStreams масив MediaStream) case CallActions.PeerStream: // remote webrtc stream (call.peerStreams масив MediaStream) store.commit('updateCall', call) break case CallActions.Destroy: // call was destroyed store.commit('removeCall', call) break; default: store.commit('updateCall', call) break; } }) try { // Call Center agent change the status const agent = await client.agentSession() store.commit('initAgent', agent) } catch (e) { console.error(`this user not agent`) } window.cli = instance = client return client }
If you don't need the WebRTC calls, and you will use hardware phone, you can use Click-To-Call HTTP REST API: https://swagger.webitel.com/#/CallService
Creating a call center agent for advanced call routing functionality (optional)
If you use call center queue and auto dialers, you need to create an agent for each user. You can create it with Webitel REST API endpoint and integration token: https://swagger.webitel.com/#/AgentService/AgentService_CreateAgent
Using Webitel REST API for calls history synchronization (optional)
If you what to get the history of the all calls from webitel to SPA, you can use Webitel REST API endpoint and integration token: https://swagger.webitel.com/#/CallService/CallService_SearchHistoryCall
Also, you can get a call record of the calls: https://swagger.webitel.com/#/MediaFileService/MediaFileService_ReadMediaFile
Working with an auto dialer system (optional)
This part is described on the page Webitel REST API Usage Examples