Методы API
API работает посредством CRUD интерфейса.
В системе используется система версий методов. Методы старых версий продолжаются поддерживаться в прежнем режиме, в новых методах возможны изменения, которые будут документироваться.
В текущей реализации 3 метода:
- История звонков (History)
- Переменные проекта (Words)
- Исходящий звонок (Dial)
- Мониторинг внутренний линий (Monitoring)
Пример реализации обращения к API на PHP и класс для взаимодействия с API вы можете скачать здесь https://voicetal.ru/voicetal_api_php_class.rar
Для работы с API нужны номер проекта и ключ API. Увидеть эти параметры можно на странице проекта во вкладке Настройка.
Инициализация класса для работы с API Voicetal
<?php require_once ('VoicetalApi.php'); $project_id = ID_проекта; $project_key = 'API_ключ_проекта'; $vt = new \Voicetal\VoicetalApi($project_id, $project_key); ?>
История звонков (History)
Доступные методы: read.
Метод позволяет получить историю звонков по проекту с детализацией. Подходит для интеграции с CRM и прочими системами.
Метод может принимать следующие параметры:
- answers – в случае если значение 1, то выбираем только те данные, где было совершенно хоть какое то действие
- date_start, date_end – параметры выборки даты, в формате d.m.Y (01.01.2016)
- phone – выборка по конкретному номеру телефона
- limit – ограничение на вывод, по умолчанию 20, максимум 100
- page – страница результатов
- unique_id - история звонка по его ID (при вызове через метод Исходящий звонок (Dial) возвращается unique_id).
Пример запроса
limit — текущий лимит на вывод
page — текущая страница
total — общее количество записей
leads — объект с результатами поиска, содержит в себе значения value
value
phone – номер телефона пользователя
time — время в формате Unixtime
date — дата звонка
hour — час в который произошел звонок
price — стоимость звонка
time_end — время окончания звонка
time_duration — продолжительность звонка
id — уникальный идентификатор звонка
goal — считается ли данный звонок успешным
actions – действия которые были выполнены с пользователем, содержит значения value
value
type — тип записи, перечислены ниже
time — время в формате unixtime
answers – используется при типе записи decode
value — значение
Используются следующие типы записей в поле type
record – запись ответа пользователя
decode — расшифровка ответа пользователя
digits — нажатие цифры
play – проигрывание записи
callPhone - переадресация на номер
callQuery - переадресация на очередь звонков
recognizeCall – стенограмма звонка
Пример запроса
<?php require_once ('VoicetalApi.php'); $project_id = ID_проекта; $project_key = 'API_ключ_проекта'; $vt = new \Voicetal\VoicetalApi($project_id, $project_key); $result = $vt->History->read(array('limit' => 100, 'page' => 2)); ?>
Переменные проекта (Words)
Доступные методы: read, create, update, delete.
Переменные проекта используются для сохранения временных данных, которые могут быть использованы в схеме звонка ([$var_name]). Например, наличие определенного товара, информация о свободном времени для записи на услугу, информация о конкретном заказе, режим работы и график работы менджеров и прочее.
Метод Read
Считать значения переменной по названию.
Пример запроса
<?php require_once ('VoicetalApi.php'); $project_id = ID_проекта; $project_key = 'API_ключ_проекта'; $vt = new \Voicetal\VoicetalApi($project_id, $project_key); //Считать значение всех переменных $result = $vt->Words->read(); //Считать значение конкретной переменной $result = $vt->Words->hello->read(); ?>
Метод Create
Создание переменной.
Пример запроса
<?php require_once ('VoicetalApi.php'); $project_id = ID_проекта; $project_key = 'API_ключ_проекта'; $vt = new \Voicetal\VoicetalApi($project_id, $project_key); $result = $vt->Words->create(array('name' => 'hello', 'value' => 'hello world!')); ?>
Метод Update
Изменение переменной.
Пример запроса
<?php require_once ('VoicetalApi.php'); $project_id = ID_проекта; $project_key = 'API_ключ_проекта'; $vt = new \Voicetal\VoicetalApi($project_id, $project_key); $vt->Words->Hello->update(array('value' => 'wasted...')); ?>
Метод Delete
Удаление переменной.
Пример запроса
<?php require_once ('VoicetalApi.php'); $project_id = ID_проекта; $project_key = 'API_ключ_проекта'; $vt = new \Voicetal\VoicetalApi($project_id, $project_key); $vt->Words->hello->delete(); ?>
Исходящий звонок (Dial)
Доступные методы: create.
Вариант 1 - исходящий звонок указанному абоненту с воспроизведением схемы звонка проекта
Звонок сначала идет на номер phone и если связь установлена (ANSWER), то запускается схема проекта.
Позволяет совершить исходящий звонок на указанный номер. Обязательный параметры - phone, номер, на который звоним. Так же можно передать переменные в поле keys, которые могут быть использованы в схеме звонка ([=var_name]).
Пример запроса
<?php require_once ('VoicetalApi.php'); $project_id = ID_проекта; $project_key = 'API_ключ_проекта'; $vt = new \Voicetal\VoicetalApi($project_id, $project_key); $result = $vt->Dial->create(array('phone' => '89261234567', 'keys' => [ 'order_id' => '623 723', 'new_status' => '82', 'client_name' => 'site.ru', 'new_date' => '20 июля', 'driver_tel' => '89261234567' ])); ?>
Варианта 2 - Callback-звонок
В данном случае звонок сначала идет на внутренний номер телефона internal_phone. Как только внутренний номер отвечает на звонок, идет звонок на номер phone. internal_phone - логин внутреннего номера.
Данную функцию можно использовать, например, как:
- - Callback-сервис - клиент на сайте вводит свой номер телефона, нажимает кнопку и звонок сразу идет менеджеру на внутренний номер. Как только он берет трубку, звонок идет клиенту.
- - Интеграция с CMS\CRM - чтобы менеджеры не вводили вручную телефонные номера, а могли по нажатию кнопки связаться с клиентом.
Пример запроса
<?php require_once ('VoicetalApi.php'); $project_id = ID_проекта; $project_key = 'API_ключ_проекта'; $vt = new \Voicetal\VoicetalApi($project_id, $project_key); $result = $vt->Dial->create(array('phone' => '89261234567', 'keys' => [ 'mode' => 'callback', 'internal_phone' => '00100101' ])); ?>
Мониторинг внутренних линий (Monitoring)
Доступные методы: read.
Мониторинг внутренних линий - возвращает список номеров проекта со статусом линии. 1 = онлайн, 0 - оффлайн.
Пример запроса
<?php require_once ('VoicetalApi.php'); $project_id = ID_проекта; $project_key = 'API_ключ_проекта'; $vt = new \Voicetal\VoicetalApi($project_id, $project_key); $result = $vt->Monitoring->read (); ?>