Skip to content

Bobrovskih/mango-vpbx

BranchesTags

Repository files navigation

npm version Build status branch:master coverage

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

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

About

NodeJS SDK for API VPBX by MANGO OFFICE

www.npmjs.com/package/mango-vpbx

Topics

nodejs api sdk sip office voip mango vpbx mangotelecom

Resources

Readme

License

MIT license
Activity

Stars

9 stars

Watchers

2 watching

Forks

2 forks
Report repository

Releases

7 tags

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages