API Voicetal: методы API Voicetal

Методы 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 ();
?>