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