Этот документ описывает основы интеграции Webitel с любым одностраничным веб-приложением (SPA).
Основные пункты интеграции:
Важно!
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.