API телефония. Документация по использованию API виртуальной АТС.

Версия 2.0

Запросы для управления телефонией через АТС отправляются на адрес https://digitoffice.ru/api2/*APIkey*/*command*

Параметры Описание
APIkey Ваш ключ
command Вызываемая команда

В ответ возвращается JSON-строка со статусом запроса и объяснением в случае ошибки:

{"ok": true}

или

{"ok": false, "message": "Описание ошибки"}

Все параметры регистрозависимы.

Здесь представлен пример использования API телефонии для подтверджения телефонных номеров, вводимых на вашем сайте.

Также есть пример организации автоматических уведомлений для ваших сотрудников и клиентов.

Команда GET /info – Получить информацию о системе

Пример API запроса для управления виртуальной АТС:

curl "https://digitoffice.ru/api2/*APIkey*/info"

Пример ответа виртуальной АТС:

{"ok": true, "credit": 0, "licnum": "100001", "balance": 123.72}

Параметры Описание
credit Размер кредитного лимита
licnum Лицевой счет
balance Текущий баланс

Работа с телефонными номерами

Команда GET /getNumbers – Получить информацию о подключенных номерах

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/getNumbers"

Пример ответа:

{"ok": true, "Numbers": [{"validated": true, "number": "79000000001"}, {"validated": false, "number": "79000000002"}]}

В Numbers содержится список подключенных телефонных номеров в облачную АТС, validated true означает что номер прошел проверку и его можно использовать в API.

Команда GET /addNumber – Добавить телефонный номер в систему

Параметры Описание
number Добавляемый номер

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/addNumber?number=70000000000"

Пример ответа:

{"ok": true}

Команда GET /delNumber – Удалить телефонный номер

Параметры Описание
number Удаляемый номер

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/delNumber?number=70000000000"

Пример ответа:

{"ok": true}

Команда GET /callVerification – Проверочный звонок

Параметры Описание
number Проверяемый номер

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/callVerification?number=70000000000"

Пример ответа:

{"ok": true}

Команда GET /confirmNumber – Подтверждение номера

Параметры Описание
number Подтверждаемый номер
pin Проверочный код

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/confirmNumber?number=70000000000&pin=12345"

Пример ответа:

{"ok": true}

Работа со звуковыми записями

Команда GET /getFiles – Получить список записей

Параметры Описание
prefix Если указан этот параметр, возвращается список файлов, начинающихся на указанное имя

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/getFiles"

Пример ответа:

{"ok": true, "files": ["musicname1.mp3", "musicname2.mp3", "musicname3.mp3"]}

Команда POST /uploadFile – Загрузить запись

Параметры Описание
file Загружаемый файл
name Название для файла, если не указано – будет сохранен под оригинальным именем файла

Пример запроса:

curl --form "file=@record.mp3" --form "name=xxxx" "https://digitoffice.ru/api2/*APIkey*/uploadFile"

Пример ответа:

{"ok": true}

Команда GET /createMessage – Создать запись

Параметры Описание
name Имя записи
message Записать заданную фразу, ограничение - до 1000 русских знаков
phrase_params Дополнительные (необязательные) параметры для проговаривания текста. Описание смотреть в функции initCall.

Пример запроса:

curl -G --data-urlencode "message=Это проверочное сообщение" "https://digitoffice.ru/api2/*APIkey*/createMessage?name=mess.mp3&phrase_params=3,3,1.2"

Пример ответа:

{"ok": true}

Команда GET /delFile – Удалить запись

Параметры Описание
name Имя удаляемого файла

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/delFile?name=filename"

Пример ответа:

{"ok": true}

Работа с вызовами

Команда GET, POST /initCall – Инициировать звонок на номер

Вызывает указанный номер и воспроизводит сообщение, записанное в файл или переданное текстом. Допускается только один параметр – file или phrase. Если указан параметр ivr, то после вызова происходит перенаправление в голосовое меню. Если указан только параметр ivr, то сразу соединяет с голосовым меню.

Параметры Описание
to Вызываемый номер
cid Подставляемый номер из списка проверенных
file Воспроизвести указанный файл
phrase Проговорить заданную фразу, ограничение - до 1000 русских знаков
ivr Название голосового меню
phrase_params Дополнительные (необязательные) параметры для проговаривания текста. Состоит из трех значений, все три значения обязательны.

Дополнительные (необязательные) параметры phrase_params для проговаривания текста состоят из трех значений, все три значения обязательны.

  • номер голоса (цифра от 1 до 6, первые четыре женских голоса, оставшиеся мужские)
  • номер эмоции (1- доброжелательная, 2- раздраженная, 3- нейтральная)
  • скорость проговаривания, значение от 0.1 до 3.0, где 0.1 - самый медленный темп, 1- нормальный темп, и т.д.

Значения нужно отделять запятой, например &phrase_params=3,3,1.2 (женский голос, нейтральная эмоция, сказать фразу чуть быстрее)

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/initCall?to=70000000001&cid=70000000002&ivr=menu1"

Пример ответа:

{"ok": true}

Работа со статистикой

Команда GET /Statistics – Запрос статистики звонков

Запрос статистики по заданным параметрам.

Параметры Описание
search Строка для поиска звонка
start Время начала в формате 'день.месяц.год часы:минуты'
end Время конца в формате 'день.месяц.год часы:минуты'
results Ограничение строк выдачи, по умолчанию 100

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/Statistics?search=79&start=01.01.2016%2017:00"

Пример ответа:

{"ok": true, "records": [ {"direction": "", "call_cost": "", "destination_number": "79000000001", "start_stamp2": "2016-03-28 12:36:26", "billsec": 0, "caller_id_number": "\u0421\u0435\u0440\u0432\u0438\u0441\u043d\u044b\u0439", "per_min": "", "status": "Normal"}, {"direction": "", "call_cost": "", "destination_number": "79000000002", "start_stamp2": "2016-03-28 11:18:47", "billsec": 0, "caller_id_number": "\u0421\u0435\u0440\u0432\u0438\u0441\u043d\u044b\u0439", "per_min": "", "status": "Normal"}, ]}

Параметры Описание
direction Направление звонка
call_cost Стоимость звонка
destination_number Вызываемый номер
start_stamp2 Время начала
billsec Время разговора
calleridnumber Вызывающий номер
per_min Стоимость минуты по данному направлению
status Статус

Статус может иметь следующие значения:

  • Normal - Успешный разговор.
  • Cancel - Вызов отменен звонящей стороной.
  • Busy - Абонент занят или сбросил звонок.
  • Failure - Звонок не прошел. Причины могут быть различными, от недоступности абонента, до абонент не существует.

Настройка голосового меню IVR

Команда GET /listIVR – Список имеющихся меню

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/listIVR"

Пример ответа:

{"ok": true, "list": [ {"max_timeouts": 3, "redirects": [ {"digits": "1", "transferToUser": null, "transferToQueue": null, "transferToGroup": null, "exitMenu": false, "goBack": false, "goToMenu": null, "transferToNumber": "", "toMenu": 25, "id": 13}, {"digits": "4", "transferToUser": null, "transferToQueue": null, "transferToGroup": null, "exitMenu": false, "goBack": false, "goToMenu": null, "transferToNumber": "", "toMenu": 25, "id": 20}, {"digits": "2", "transferToUser": null, "transferToQueue": null, "transferToGroup": null, "exitMenu": false, "goBack": false, "goToMenu": null, "transferToNumber": "", "toMenu": 25, "id": 21} ], "name": "test01", "confirm_key": "", "digit_len": 1, "inter_digit_timeout": 2, "max_failures": 3, "timeout": 10, "greet_short": "829af0e8-30e7-4f75-b841-9654d99aabb3.wav", "confirm_attempts": null, "greet_long": 3, "invalid_sound": "829af0e8-30e7-4f75-b841-9654d99aabb3.wav", "id": 25, "exit_sound": "829af0e8-30e7-4f75-b841-9654d99aabb3.wav" }, {"max_timeouts": 3, "redirects": [], "name": "www", "confirm_key": "", "digit_len": 1, "inter_digit_timeout": 10, "max_failures": 1, "timeout": 5, "greet_short": null, "confirm_attempts": null, "greet_long": 1, "invalid_sound": null, "id": 26, "exit_sound": null} ]}

Команда GET /addIVR – Добавить голосовое меню

Параметры Описание
name Название меню
greet_long Аудио файл приветствия. Проигрывается один раз
greet_short Воспроизводится, когда заканчивается время, отведенное на нажатие клавиши
invalid_sound Воспроизводится, если звонящий выбирает несуществующий пункт меню
exit_sound Воспроизводится при выходе из меню
timeout Таймаут для меню, если звонящий не выберет любой пункт меню, то он выходит из меню (сек)
inter_digit_timeout Максимальное время между нажатиями клавиш (сек)
max_failures Количество ошибочных нажатий клавиш
max_timeouts Сколько раз можно ничего не вводить
digit_len Количество цифр для ввода

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/addIVR" \ -d "name=test01" \ -d "greet_long=hello.mp3" \ -d "timeout=10" \ -d "max_timeouts=9" \ -d "digit_len=3" \ -d "inter_digit_timeout=3" \ -d "max_failures=5"

Пример ответа:

{"ok": true}

Команда GET /delIVR – Удалить меню

Параметры Описание
name Идентификатор меню, которое нужно удалить

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/delIVR?name=menuname"

Пример ответа:

{"ok": true}

Команда GET /updateIVR – Изменить параметры в меню

Передаются изменяемые параметры. Названия параметров такие же, как и в команде addIVR.

Пример запроса:

curl "https://digitoffice.ru/api2/*APIkey*/updateIVR" -d "name=test01" \ -d "timeout=7" \ -d "max_failures=4"

Пример ответа:

{"ok": true}

По всем вопросам, связанным с работой телефонным API нужно обращаться в техническую поддержку. Так же готовы помочь с реализацией ваших проектов по телефонии, добавление в API нового функционала.