Пример интеграции Webitel и Single Page Application

Этот документ описывает основы интеграции Webitel с любым одностраничным веб-приложением (SPA).

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

1 Общие настройки интеграции Webitel:
2 Создание пользователя и сохранение токена интеграции.
3 Использование клиентской библиотеки Webitel JavaScript для звонков WebRTC или функционала Click-To-Call.
4 Создание агента контакт-центра для расширенной функциональности маршрутизации звонков (необязательно).
5 Использование Webitel REST API для синхронизации истории звонков (необязательно).
6 Работа з дайлером (необязательно).

Важно!

Webitel и SPA должны использовать HTTPS-соединение с действительными SSL-сертификатами, подписанными известными ЦС.

Общие настройки интеграции Webitel:

Для целей интеграции, вам нужно сохранить на стороне SPA следующие 4 настройки:

Конечная точка Webitel REST API. Например: https://cloud.webitel.com/api/
Конечная точка Webitel Web Socket. Например: wss://cloud.webitel.com/ws/
Токен интеграции Webitel.
Домен пользователей Webitel. Внутренний домен Webitel, например: my-company.lo

Создание пользователя и сохранение токена интеграции.

Name - имя пользователя.
Login - логин пользователя. Он может совпадать с внутренним номером пользователя.
Password - случайная строка.
Extension - внутренний телефонный номер пользователя.
Product license key - лицензионный ключ продукта (пользователи без лицензии не могут войти в Webitel).
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 для каждого пользователя вам необходимо сохранять:

Идентификатор пользователя (user ID).
Идентификатор устройства (device ID).
Токен пользователя (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.