https://github.com/bobrovskih/mango-vpbx

NodeJS SDK for API VPBX by MANGO OFFICE
https://github.com/bobrovskih/mango-vpbx
api mango mangotelecom nodejs office sdk sip voip vpbx
Last synced: about 1 year ago
JSON representation
NodeJS SDK for API VPBX by MANGO OFFICE
Host: GitHub
URL: https://github.com/bobrovskih/mango-vpbx
Owner: Bobrovskih
License: mit
Created: 2017-12-22T18:02:37.000Z (over 8 years ago)
Default Branch: master
Last Pushed: 2023-01-05T11:20:55.000Z (over 3 years ago)
Last Synced: 2024-10-31T17:46:52.409Z (over 1 year ago)
Topics: api, mango, mangotelecom, nodejs, office, sdk, sip, voip, vpbx
Language: JavaScript
Homepage: https://www.npmjs.com/package/mango-vpbx
Size: 505 KB
Stars: 9
Watchers: 2
Forks: 2
Open Issues: 4
Metadata Files:
- Readme: README.MD
- License: LICENSE
Awesome Lists containing this project

README

          
 [![npm version](https://badge.fury.io/js/mango-vpbx.svg)](https://www.npmjs.com/package/mango-vpbx) [![Build status branch:master](https://travis-ci.org/Bobrovskih/mango-vpbx.svg?branch=master)](https://travis-ci.org/Bobrovskih/mango-vpbx)

 [![coverage](https://codecov.io/gh/Bobrovskih/mango-vpbx/branch/master/graph/badge.svg)](https://codecov.io/gh/Bobrovskih/mango-vpbx)

 

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

[![API Виртуальной АТС от MANGO OFFICE](https://www.mango-office.ru/upload/iblock/d11/api-icon.png "API Виртуальной АТС от MANGO OFFICE")](https://www.mango-office.ru/support/virtualnaya_ats/integratsiya_api/obshchie_voprosy_po_api_vats_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');`

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

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

```

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

```typescript

    import VPBX from 'mango-vpbx';

    const vpbx = new VPBX();

```

[Все примеры](examples/)

## класс VPBX

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

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

```javascript

const vpbx = new VPBX(apiKey, apiSalt);

```

| Параметр  | Тип  | Описание |

| --------- | ---- | -------- |

| [apiKey] | string | Уникальный код вашей АТС |

| [apiSalt] | string | Ключ для создания подписи |

## Методы

Список возможных json параметров их значений для вызова API методов доступен в [официальной документации](https://www.mango-office.ru/upload/api/MangoOffice_VPBX_API_v1.9.pdf)

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

| Параметр  | Тип  | Описание |

| --------- | ---- | -------- |

| success  | boolean  |  результат |

| code   | number   |  код ответа ВАТС  |

| message  | string   |  сообщение  |

### метод call

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

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

```

### метод callGroup

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

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

```

### метод hangup

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

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

```

### метод sms

Отправка 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);

```

### метод recordingStart

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

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

```

### метод route

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

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

```

### метод transfer

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

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

```

### метод stats

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

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

```

### метод recording

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

```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

```

### метод users

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

```js

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

```

| Параметр  | Тип  | Описание |

| --------- | ---- | -------- |

| [json] | object | параметры |

| [json.extension] | string | добавочный номер сотрудника |

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

```js

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

```

### метод dctUserInfo

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

```js

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

```

| Параметр  | Тип  | Описание |

| --------- | ---- | -------- |

| json | object | параметры |

| json.number | string | динамический номер |

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

```js

const json = { number: '74952129298' };

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

```

### метод dctUserHistory

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

```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 представляет собой набор запросов (уведомлений), которые направляются к внешней системе.

### метод events

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

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

### метод call

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

```js

Realtime.call; // => Function

```

### метод sms

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

```js

Realtime.sms; // => Function

```

### метод recording

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

```js

Realtime.recording; // => Function

```

### метод dtmf

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

```js

Realtime.dtmf; // => Function

```

### метод summary

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

```js

Realtime.summary; // => Function

```

### метод ping

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

```js

Realtime.ping; // => Function

```

### метод all

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

```js

Realtime.all; // => Function

```

### метод hear

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

```js

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

```

| Параметр  | Тип  | Описание |

| --------- | ---- | -------- |

| filter  | object  |  фильтр для событий  |

| handler  | function   |  функция обратного вызова  |

Аргумент `filter` должен иметь обязательное свойство `event` - имя события 

(возможные значения: 'call', 'recording', 'summary', 'dtmf', 'sms', 'callback', 'stats', 'ping')

Функция `handler` в качестве первого аргумента принимает json-объект, содержащий параметры события (список передаваемых параметров доступен в [официальной документации](https://www.mango-office.ru/upload/api/MangoOffice_VPBX_API_v1.9.pdf))

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

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

```

[Все примеры](examples/)

## Отладка

 Для логирования запросов необходимо задать переменную `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:*`
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/bobrovskih/mango-vpbx

Awesome Lists containing this project

README
