mango-vpbx

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

Установка

npm install mango-vpbx

Требования

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

Уникальный код продукта ВАТС (API KEY)

Код продукта можно задать через переменную process.env.API_KEY
Или передать первый аргумент в конструктор new VPBX('your-api-key-here', 'your-api-salt');

Уникальный ключ (API SALT)

Уникальный ключ можно задать через переменную process.env.API_SALT
Или передать второй аргумент в конструктор new VPBX('your-api-key-here', 'your-api-salt');

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

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();

Пример подключения в typescript

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

Все примеры

класс VPBX

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

Создание нового экземпляра

const vpbx = new VPBX(apiKey, apiSalt);

Параметр	Тип	Описание
[apiKey]	`string`	Уникальный код вашей АТС
[apiSalt]	`string`	Ключ для создания подписи

Методы

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

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

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

метод call

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

vpbx.call(json); // => Promise<any>

Параметр	Тип	Описание
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 секунд

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

const json = {
    from: {
        extension: '5000'
    },
    to_number: '74952129298',
};
const { success } = await vpbx.call(json);

метод callGroup

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

vpbx.callGroup(json); // => Promise<any>

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

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

const json = {
    from: '222',
    to_number: '74991102914',
    line_number: '74952129298'
};
const { success } = await vpbx.callGroup(json);

метод hangup

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

vpbx.hangup(json); // => Promise<any>

Параметр	Тип	Описание
json	`object`	параметры
[json.command_id]	`string`	идентификатор команды
json.call_id	`string`	идентификатор вызова, который необходимо завершить

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

const json = {
    call_id: 'NyAoNDk1KSAyMTItOTItOTgJ'
};
const { success } = await vpbx.hangup(json);

метод sms

Отправка SMS

vpbx.sms(json); // => Promise<any>

Параметр	Тип	Описание
json	`object`	параметры
[json.command_id]	`string`	идентификатор команды
json.text	`string`	текст сообщения
json.from_extension	`string`	внутренний номер сотрудника
json.to_number	`string`	номер вызываемого телефона
[json.sms_sender]	`string`	имя отправителя

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

const json = {
    from_extension: '5000',
    to_number: '74952129298',
    text: 'It works'
};
const { success } = await vpbx.sms(json);

метод recordingStart

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

vpbx.recordingStart(json); // => Promise<any>

Параметр	Тип	Описание
json	`object`	параметры
[json.command_id]	`string`	идентификатор команды
json.call_id	`string`	идентификатор вызова
json.call_party_number	`string`	номер абонента участвующего в вызове, которого нужно начать записывать.

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

const json = {
    call_id: 'NyAoNDk1KSAyMTItOTItOTgJ',
    call_party_number: '5000',
};
const { success } = await vpbx.recordingStart(json);

метод route

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

vpbx.route(json); // => Promise<any>

Параметр	Тип	Описание
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`	отображаемое имя

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

const json = {
    call_id: 'NyAoNDk1KSAyMTItOTItOTgJ',
    to_number: '101'
};
const { success } = await vpbx.route(json);

метод transfer

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

vpbx.transfer(json); // => Promise<any>

Параметр	Тип	Описание
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")

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

const json = {
    call_id: 'NyAoNDk1KSAyMTItOTItOTgJ',
    method: 'blind',
    to_number: '101',
    initiator: '5000'
};
const { success } = await vpbx.transfer(json);

метод stats

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

vpbx.stats(json); // => Promise<any>

Параметр	Тип	Описание
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`	фильтр - успешные

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

const json = {
    date_from: '1481630491',
    date_to: '1481734491'
};
const { success, stats } = await vpbx.stats(json);

метод recording

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

vpbx.recording(json); // => Promise<any>

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

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

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

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

Скачивание записи разговора

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

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

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

метод users

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

vpbx.users(json); // => Promise<any>

Параметр	Тип	Описание
[json]	`object`	параметры
[json.extension]	`string`	добавочный номер сотрудника

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

const { success, users } = await vpbx.users();

метод dctUserInfo

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

vpbx.dctUserInfo(json); // => Promise<any>

Параметр	Тип	Описание
json	`object`	параметры
json.number	`string`	динамический номер

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

const json = { number: '74952129298' };
const { success, dctUserInfo } = await vpbx.dctUserInfo(json);

метод dctUserHistory

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

vpbx.dctUserHistory(json); // => Promise<any>

Параметр	Тип	Описание
json	`object`	параметры
json.number	`string`	динамический номер

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

const json = { number: '74952129298' };
const { success, dctUserHistory } = await vpbx.dctUserHistory(json);

API RealTime

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

метод events

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

vpbx.events(url); // => Realtime

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

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

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

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

метод call

Обработчик "Уведомления о вызове"

Realtime.call; // => Function

метод sms

Обработчик "Уведомления о результате смс"

Realtime.sms; // => Function

метод recording

Обработчик "Уведомления о записи разговора"

Realtime.recording; // => Function

метод dtmf

Обработчик "Уведомления о нажатиях DTMF клавиш"

Realtime.dtmf; // => Function

метод summary

Обработчик "Уведомления о завершении вызова"

Realtime.summary; // => Function

метод ping

Обработчик "Проверить подключение" из Личного кабинета

Realtime.ping; // => Function

метод all

Обработчик всех событий (только для метода hear)

Realtime.all; // => Function

метод hear

Слушает события по заданному фильтру

Realtime.hear(filter, handler); // => void

Параметр	Тип	Описание
filter	object	фильтр для событий
handler	function	функция обратного вызова

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

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

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

 
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);

Обработчик "уведомления о завершении вызова" будет вызван только для исходящего звонка:

events.hear({ event: 'summary', call_direction: '2' }, e => console.log('завершился исходящий звонок', e.entry_id));

Фильтр может состоять из нескольких параметров:

events.hear({ event: 'recording', recording_state: 'Completed', completion_code: '1000' }, e => console.log('новая запись разговора!', e.recording_id));

В параметрах допускаются регулярные выражения:

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:*

mango-vpbx

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

Установка

Требования

Уникальный код продукта ВАТС (API KEY)

Уникальный ключ (API SALT)

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

Пример подключения в typescript

класс VPBX

Методы

метод call

метод callGroup

метод hangup

метод sms

метод recordingStart

метод route

метод transfer

метод stats

метод recording

метод users

метод dctUserInfo

метод dctUserHistory

API RealTime

метод events

Класс Realtime

метод call

метод sms

метод recording

метод dtmf

метод summary

метод ping

метод all

метод hear

Отладка

Dependencies (6)

Dev Dependencies (8)

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads