Библиотека для 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:[email protected]\",\"line_number\":\"74952129298\",\"acd_group\":\"22\"},\"dct\":{\"type\":0}}"} +0ms

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