Приклад інтеграції Webitel та Single Page Application

Owned by Olga Zaritska
May 08, 2023
8 min read

Цей документ описує основи інтеграції Webitel з будь-яким односторінковим веб-додатком (SPA).

Основні пункти інтеграції:

Важливо!

Webitel та SPA повинні використовувати HTTPS-з'єднання з дійсними SSL-сертифікатами, які підписані відомими ЦС.

Загальні налаштування інтеграції Webitel:

Для цілей інтеграції, вам потрібно зберегти на боці SPA наступні 4 налаштування:

  1. Кінцева точка Webitel REST API. Наприклад: https://cloud.webitel.com/api/
  2. Кінцева точка Webitel Web Socket. Наприклад: wss://cloud.webitel.com/ws/
  3. Токен інтеграції Webitel.
  4. Домен користувачів Webitel. Внутрішній домен Webitel, наприклад: my-company.lo

Створення користувача та збереження токена інтеграції.

  1. Name - ім'я користувача.
  2. Login - логін користувача. Він може співпадати з розширенням користувача.Password - випадковий рядок.
  3. Extension - внутрішній телефонний номер користувача.
  4. Product license key - ліцензійний ключ продукту (користувачі без ліцензії не можуть увійти в Webitel).
  5. WebRTC device - пристрій WebRTC (користувачі без пристрою не можуть використовувати дзвінки WebRTC з браузера).

Створення пристрою.

Ми створимо пристрій WebRTC для нашого майбутнього користувача, використовуючи кінцеву точку Webitel REST API та токен інтеграції.

POST https://cloud.webitel.com/api/devices
{
  "name": "device for user 1",
  "account": "sipUser1",
  "password": "BNZdVLryFwcB"
}

У відповіді ми отримаємо тіло з новим ідентифікатором пристрою:

{
    "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"
    }
}

Створення користувача.

Тепер ми створимо користувача з пристроєм WebRTC, використовуючи кінцеву точку Webitel REST API та токен інтеграції:

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"
        }
    ]
}

У відповіді ми отримаємо тіло з новим ідентифікатором користувача:

{
    "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"
    }
}

Створення токену користувача.

Останнє, що нам знадобиться, – токен інтеграції для нового користувача:

POST https://dev.webitel.com/api/users/10457/tokens

{
    "token": "",
    "usage": "integration app"
}

У відповіді ви отримаєте токен для користувача:

{
    "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"
    }
}

Таким чином, всередині вашої SPA, для кожного користувача вам потрібно зберігати:

  1. Ідентифікатор користувача (user ID).
  2. Ідентифікатор пристрою (device ID).
  3. Токен користувача (user token).

Використання клієнтської бібліотеки Webitel JavaScript для дзвінків WebRTC або функціоналу Click-To-Call.

Webitel має свою власну бібліотеку на JavaScript, яка підтримує наступні функції:

  • Ініціювання дзвінка;
  • Відповідь на вхідний дзвінок (тільки з використанням WebRTC);
  • Утримування дзвінка;
  • Перенаправлення дзвінка;
  • Надсилання DTMF-сигналу;
  • Завершення дзвінка.

Ви можете знайти приклад web-phone за цим посиланням: 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
}

Якщо вам не потрібні дзвінки за допомогою WebRTC, і ви будете використовувати апаратний телефон, ви можете використовувати Click-To-Call HTTP REST API: https://swagger.webitel.com/#/CallService

Створення агента колл-центру для розширеної функціональності маршрутизації дзвінків (необов'язково).

Якщо ви використовуєте черги колл-центру та авто-набір номерів (дайлер), вам потрібно створити агента для кожного користувача. Ви можете створити його за допомогою REST API-інтерфейсу Webitel та токену інтеграції: https://swagger.webitel.com/#/AgentService/AgentService_CreateAgent

Використання Webitel REST API для синхронізації історії дзвінків (необов'язково).

Якщо ви хочете отримати історію всіх дзвінків з Webitel на SPA, ви можете використовувати точку доступу Webitel REST API та токен інтеграції: https://swagger.webitel.com/#/CallService/CallService_SearchHistoryCall

Також ви можете отримати записи дзвінків: https://swagger.webitel.com/#/MediaFileService/MediaFileService_ReadMediaFile

Робота з дайлером (необовʼязково).

Ця частина описана на сторінці: Webitel REST API Usage Examples.