mango-vpbx

 

Библиотека для API Виртуальной АТС от MANGO OFFICE


$3

npm install mango-vpbx

$3

NodeJS версии 8 или более

$3

Код продукта можно задать через переменную process.env.API_KEY

Или передать первый аргумент в конструктор
new VPBX('your-api-key-here', 'your-api-salt');

$3

Уникальный ключ можно задать через переменную process.env.API_SALT

Или передать второй аргумент в конструктор
new VPBX('your-api-key-here', 'your-api-salt');

$3

``javascript
const VPBX = require('mango-vpbx');
const vpbx = new VPBX();

async function main() {
// звонок с внутреннего номера 5000
// на номер 74952129298
const json = {
from: {
extension: '5000'
},
to_number: '74952129298'
};
const { success } = await vpbx.call(json);
}
main();
`


$3


`typescript
import VPBX from 'mango-vpbx';
const vpbx = new VPBX();
`

Все примеры

класс VPBX

Класс для API Виртуальной АТС от MANGO OFFICE




Создание нового экземпляра
`javascript
const vpbx = new VPBX(apiKey, apiSalt);
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| [apiKey] | string | Уникальный код вашей АТС |
| [apiSalt] | string | Ключ для создания подписи |

Методы

Список возможных json параметров их значений для вызова API методов доступен в официальной документации

Вызов методов возвращает промис, результат которого объект, содержащий свойства:

| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| success | boolean | результат |
| code | number | код ответа ВАТС |
| message | string | сообщение |

$3

Инициирование вызова от имени сотрудника

`js
vpbx.call(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| [json.command_id] | string | идентификатор запроса |
| json.from | object | инициатор вызова |
| json.from.extension | string | добавочный номер сотрудника |
| [json.from.number] | string | номер телефона |
| json.to_number | string | вызываемый номер телефона |
| [json.line_number] | string | номер линии (АОН) |
| [json.sip_headers] | object | заголовки SIP |
| [json.sip_headers.answer_after] | string | автоответ через n секунд |

Пример использования
`js
const json = {
from: {
extension: '5000'
},
to_number: '74952129298',
};
const { success } = await vpbx.call(json);
`

$3

Инициирование вызова от имени группы

`js
vpbx.callGroup(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| [json.command_id] | string | идентификатор запроса |
| json.from | string | добавочный номер группы |
| json.to | string | вызываемый номер телефона |
| [json.line_number] | string | номер линии (АОН) |

Пример использования
`js
const json = {
from: '222',
to_number: '74991102914',
line_number: '74952129298'
};
const { success } = await vpbx.callGroup(json);
`

$3

Завершение вызова

`js
vpbx.hangup(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| [json.command_id] | string | идентификатор команды |
| json.call_id | string | идентификатор вызова, который необходимо завершить |

Пример использования
`js
const json = {
call_id: 'NyAoNDk1KSAyMTItOTItOTgJ'
};
const { success } = await vpbx.hangup(json);
`

$3

Отправка SMS

`js
vpbx.sms(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| [json.command_id] | string | идентификатор команды |
| json.text | string | текст сообщения |
| json.from_extension | string | внутренний номер сотрудника |
| json.to_number | string | номер вызываемого телефона |
| [json.sms_sender] | string | имя отправителя |

Пример использования
`js
const json = {
from_extension: '5000',
to_number: '74952129298',
text: 'It works'
};
const { success } = await vpbx.sms(json);
`

$3

Включение записи разговора

`js
vpbx.recordingStart(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| [json.command_id] | string | идентификатор команды |
| json.call_id | string | идентификатор вызова |
| json.call_party_number | string | номер абонента участвующего в вызове, которого нужно начать записывать. |

Пример использования
`js
const json = {
call_id: 'NyAoNDk1KSAyMTItOTItOTgJ',
call_party_number: '5000',
};
const { success } = await vpbx.recordingStart(json);
`

$3

Маршрутизация вызова

`js
vpbx.route(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| [json.command_id] | string | идентификатор команды |
| json.call_id | string | идентификатор вызова |
| json.to_number | string | новый номер назначения вызова |
| [json.sip_headers] | object | заголовки SIP |
| [json.sip_headers.display_name] | string | отображаемое имя |

Пример использования
`js
const json = {
call_id: 'NyAoNDk1KSAyMTItOTItOTgJ',
to_number: '101'
};
const { success } = await vpbx.route(json);
`




$3

Перевод вызова

`js
vpbx.transfer(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| [json.command_id] | string | идентификатор команды |
| json.call_id | string | идентификатор вызова |
| json.method | string | тип перевода: blind - слепой, hold - консультативный |
| json.to_number | string | номер (цель) перевода |
| json.initiator | string | участник разговора, от имени которого выполняется перевод (например, "from.extension", "from.number", "to.extension", "to.number") |

Пример использования
`js
const json = {
call_id: 'NyAoNDk1KSAyMTItOTItOTgJ',
method: 'blind',
to_number: '101',
initiator: '5000'
};
const { success } = await vpbx.transfer(json);
`

$3

Запрос статистики вызовов

`js
vpbx.stats(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| json.date_from | string | timestamp начала |
| json.date_to | string | timestamp конца |
| [json.fields] | string | список полей включаемые в выгрузку (через запятую). Возможные значения: "records, start, finish, answer, from_extension, from_number, to_extension, to_number, disconnect_reason, line_number, location, entry_id" |
| [json.from] | object | данные, относящиеся к вызывающему абоненту |
| [json.from.extension] | string | добавочный номер |
| [json.from.number] | string | номер телефона |
| [json.to] | object | данные, относящиеся к вызываемому абоненту |
| [json.to.extension] | string | добавочный номер |
| [json.to.number] | string | номер телефона |
| [json.call_party] | object | данные, относящиеся к вызываемому или вызывающему абоненту. Использование поля допустимо только без заполнения полей to и from |
| [json.call_party.extension] | string | добавочный номер |
| [json.call_party.number] | string | номер телефона |
| [json.request_id] | string | идентификатор запроса |
| [json.incoming] | boolean | фильтр - входящие |
| [json.outgoing] | boolean | фильтр - исходящие |
| [json.fail] | boolean | фильтр - неуспешные |
| [json.success] | boolean | фильтр - успешные |

Пример использования
`js
const json = {
date_from: '1481630491',
date_to: '1481734491'
};
const { success, stats } = await vpbx.stats(json);
`

$3

Получение записи разговора

`js
vpbx.recording(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| json.recording_id | string | идентификатор записи разговора |
| [json.folder] | string | абсолютный путь до папки, для сохранения записи разговора |
| [json.expires] | string, date, number | время жизни ссылки на запись разговора ('MAX' = 1000 лет)|

Для скачивания записи разговора на диск необходимо задать свойство json.folder

Для получения ссылки на запись разговора необходимо задать свойство json.expires


Примеры использования

Скачивание записи разговора
`js
const json = {
recording_id: 'MToxMjI3NTM6MzUwNzMxMDk4NTow',
folder: 'C:/mango-vpbx/downloads/'
};
const { success, recording } = await vpbx.recording(json);
console.log(recording); // => C:/mango-vpbx/downloads/date_time_name.mp3
`

Получение ссылки на запись разговора
`js
const json = {
recording_id: 'MToxMjI3NTM6MzUwNzMxMDk4NTow',
expires: 'MAX',
};
const { success, recording } = await vpbx.recording(json);
console.log(recording); // => https://app.mango-office.ru/vpbx/queries/recording/link/MToxMjI3NTM6MzUwNzMxMDk4NTow/play/4unbf6zukwey1sdbn131nbvc6usianm4/33082514105/01578098d7854d7978773ed13ada3992358e2f09521e2be8726791e53392bd4d
`

$3

Запрос списка сотрудников ВАТС

`js
vpbx.users(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| [json] | object | параметры |
| [json.extension] | string | добавочный номер сотрудника |

Пример использования
`js
const { success, users } = await vpbx.users();
`

$3

Запрос информации о посетителе сайта по динамическому номеру

`js
vpbx.dctUserInfo(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| json.number | string | динамический номер |

Пример использования
`js
const json = { number: '74952129298' };
const { success, dctUserInfo } = await vpbx.dctUserInfo(json);
`

$3

Запрос истории навигации посетителя сайта по динамическому номеру

`js
vpbx.dctUserHistory(json); // => Promise
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| json | object | параметры |
| json.number | string | динамический номер |

Пример использования
`js
const json = { number: '74952129298' };
const { success, dctUserHistory } = await vpbx.dctUserHistory(json);
`

API RealTime

API Realtime представляет собой набор запросов (уведомлений), которые направляются к внешней системе.

$3

Cоздает обработчики для прослушивания событий от ВАТС
`js
vpbx.events(url); // => Realtime
`

| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| url | string | адрес внешней системы |

Пример использования
`js
const app = require('express')();
const bodyParser = require('body-parser');

const VPBX = require('mango-vpbx');

const vpbx = new VPBX();

const events = vpbx.events('http://example.com/mango-vpbx');

app.use(bodyParser.urlencoded());

app.use(events.call);
app.use(events.summary);
app.use(events.recording);
app.use(events.dtmf);
app.use(events.sms);
app.use(events.ping);


events.on('call', e => console.log('on events/call', e));
events.on('summary', e => console.log('on events/summary', e));
events.on('recording', e => console.log('on events/recording', e));
events.on('dtmf', e => console.log('on events/dtmf', e));
events.on('sms', e => console.log('on events/sms', e));
events.on('ping', e => console.log('check connection', e));

events.on('data', e => console.log('on any events', e));

app.use((req, res) => res.status(404).send({ error: 'not found' }));
app.listen(80);

`

Класс Realtime

Класс для создания обработчиков и получения уведомлений от ВАТС

$3

Обработчик "Уведомления о вызове"
`js
Realtime.call; // => Function
`

$3

Обработчик "Уведомления о результате смс"
`js
Realtime.sms; // => Function
`

$3

Обработчик "Уведомления о записи разговора"
`js
Realtime.recording; // => Function
`

$3

Обработчик "Уведомления о нажатиях DTMF клавиш"
`js
Realtime.dtmf; // => Function
`

$3

Обработчик "Уведомления о завершении вызова"
`js
Realtime.summary; // => Function
`

$3

Обработчик "Проверить подключение" из Личного кабинета
`js
Realtime.ping; // => Function
`

$3

Обработчик всех событий (только для метода hear)
`js
Realtime.all; // => Function
`

$3

Слушает события по заданному фильтру
`js
Realtime.hear(filter, handler); // => void
`
| Параметр | Тип | Описание |
| --------- | ---- | -------- |
| filter | object | фильтр для событий |
| handler | function | функция обратного вызова |

Аргумент filter должен иметь обязательное свойство event - имя события
(возможные значения: 'call', 'recording', 'summary', 'dtmf', 'sms', 'callback', 'stats', 'ping')

Функция handler в качестве первого аргумента принимает json-объект, содержащий параметры события (список передаваемых параметров доступен в официальной документации)

Пример использования
`js

const app = require('express')();
const bodyParser = require('body-parser');

const VPBX = require('mango-vpbx');

const vpbx = new VPBX();

const events = vpbx.events('http://example.com/mango-vpbx');

app.use(bodyParser.urlencoded({ extended: false }));

app.use(events.all);

events.hear({ event: 'ping' }, e => console.log('ping works!'));
events.hear({ event: 'call' }, e => console.log('call event', e.location, e.call_state));

app.use((req, res) => res.status(404).send({ error: 'not found' }));
app.listen(80);

`


Обработчик "уведомления о завершении вызова" будет вызван только для исходящего звонка:
`js
events.hear({ event: 'summary', call_direction: '2' }, e => console.log('завершился исходящий звонок', e.entry_id));
`

Фильтр может состоять из нескольких параметров:
`js
events.hear({ event: 'recording', recording_state: 'Completed', completion_code: '1000' }, e => console.log('новая запись разговора!', e.recording_id));
`

В параметрах допускаются регулярные выражения:
`js
events.hear({ event: 'summary', call_direction: /[12]/ }, e => console.log('события завершения входящего/исходящего вызовов', e));
`

Все примеры

Отладка


Для логирования запросов необходимо задать переменную process.env.DEBUG=mango-vpbx:worker

Пример лога:
`
mango-vpbx:worker <- POST https://app.mango-office.ru/vpbx/commands/callback +213ms
mango-vpbx:worker {"vpbx_api_key":"2fn293fg43gfh02h4ub3jd23o312u4bc","sign":"394h39ufhi20jg5gj54j9ug2i0j20j3ig0edjbopeef3ojefrf0e3ie2fjojejf0","json":"{\"from\":{\"extension\":\"5000\",\"number\":\"74991102914\"},\"to_number\":\"74952129298\",\"command_id\":\"cmd-1516131681519\"}"} +1ms
mango-vpbx:worker -> 200 OK +189ms
`

Для логирования ивентов необходимо задать переменную process.env.DEBUG=mango-vpbx:events

Пример лога:

`
mango-vpbx:events -> POST /events/call {"vpbx_api_key":"2fn293fg43gfh02h4ub3jd23o312u4bc","sign":"394h39ufhi20jg5gj54j9ug2i0j20j3ig0edjbopeef3ojefrf0e3ie2fjojejf0","json":"{\"entry_id\":\"MzUyODbvczg4OTo0MDE=\",\"call_id\":\"MzUyODbvczg4OTo0MDEMzUyODbvczg4O\",\"timestamp\":1522347638,\"seq\":1,\"call_state\":\"Appeared\",\"location\":\"abonent\",\"from\":{\"number\":\"74991102914\",\"taken_from_call_id\":\"MzUyODbvczg4OMzUyODbvczg4OMzUyODbvcg\"},\"to\":{\"extension\":\"101\",\"number\":\"sip:example@domain.mangosip.ru\",\"line_number\":\"74952129298\",\"acd_group\":\"22\"},\"dct\":{\"type\":0}}"} +0ms
`


Для логирования запросов и ивентов необходимо задать переменную process.env.DEBUG=mango-vpbx:*`