Pull to refresh
0
Zadarma
Бесплатная облачная АТС, виртуальные номера, CRM

API интерфейс для бесплатной АТС и телефонии

Reading time6 min
Views34K
imageНесколько недель назад проект Zadarma опубликовал собственный API. Он позволяет интегрировать основные функции IP-телефонии и бесплатной облачной АТС.
Каждый может за считанные минуты создать бесплатную облачную АТС и подключить к ней интерфейс API, а через него уже интегрировать АТС со своими приложениями.
В статье публикуем список и описание методов, ссылки на классы и примеры, которые уже есть для работы (опубликованы PHP-классы). Нам крайне интересны ваши отзывы: для дальнейшего развития интерфейса API, интеграции с CRM и другими системами.


Основные функции, доступные в API:


  • отображение и изменение настроек SIP-аккаунтов (в том числе установка/смена переадресации номеров, возможность привязки к SIM-карте);
  • отображение баланса, выборка статистики с разной детализацией (как SIP, так и бесплатной АТС);
  • совершение исходящих звонков (функция CallBack на внешние и внутренние номера);
  • отправка SMS-сообщений (за пределы РФ);
  • уведомление вашего сервера о каждом входящем звонке в АТС, а также маршрутизация этих звонков вашим приложением.

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

Доступные примеры и классы:


На сегодня доступен полный класс PHP для работы с API, его вы можете скачать на Github. Там-же есть примеры работы со всеми его функциями.
Кроме официального появляются альтернативные классы работы под PHP и даже для командной строки Windows.

Авторизация и начало работы


Для начала работы с API у вас уже должен быть зарегистрирован аккаунт в системе Zadarma. Если нужны бесплатная АТС/номера/SIM-карты, то их также лучше предварительно включить.
Далее нужно получить ключи для авторизации в личном кабинете.
Каждый запрос, который нуждается в авторизации, сопровождается дополнительным заголовком, вида:
"Authorization: ключ_пользователя: подпись"
Подпись составляется по следующему алгоритму:
  • массив из передаваемых параметров (GET, POST, PUT, DELETE) сортируется по названию ключа по алфавиту;
  • из полученного массива формируется строка запроса (например, функция http_build_query в PHP), пример “from=DATEFROM&to=DATETO…”;
  • и далее — соединяется по формуле:
  • строка = имя_метода + строка_запроса + md5( строка_запроса ),
  • где “имя_метода” — строка запроса, начиная от домена (с указанием версии АПИ), до начала перечисления параметров, например — /v1/sip/"
  • полученная строка кешируется по алгоритму sha1 с секретным ключом пользователя:
  • хеш = hash( строка, секретный_ключ )
  • и далее хеш кодируется в base64
  • подпись = base64_encode( хеш )

Пример на PHP:
ksort($params);
$paramsStr = http_build_query($params);
$sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret));

$header = 'Authorization: ' . $userKey . ':' . $sign; 


Формат и ограничения


Форматы ответа: json (по-умолчанию) и xml.
Чтобы получить ответ от АПИ в формате xml, в строку запроса добавляется параметр «format=xml».
В каждом ответе содержится информация о лимитах и текущем запросе, например:
X-Zadarma-Method: /v1/
X-RateLimit-Reset: 1434371160
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99 
где,
  • X-Zadarma-Method — текущий вызываемый метод;
  • X-RateLimit-Remaining — количество оставшихся запросов, с учетом лимита на метод и на пользователя;
  • X-RateLimit-Limit — цифра общего лимита обращений в минуту;
  • X-RateLimit-Reset — время сброса лимита.

В случае блокировки, метод отдает ответ с 429 заголовком «You exceeded the rate limit».
Ответ состоит из обязательного ключа «status» (success или error). Далее, в зависимости от метода, отдаются свои ключи с запрашиваемой информацией.
В случае ошибки, отдается дополнительный ключ «message» с описанием ошибки.

Пример исходящего звонка через API


Исходящие звонки производятся посредством CallBack (описание работы Callback здесь).
Схема работы:
  1. От вас поступает API запрос на сервер Zadarma
  2. Вы получаете входящий звонок и прослушиваете сообщение «Дождитесь звонка»
  3. Сервер посылает второй вызов на телефон нужного вам абонента
  4. Когда абонент ответил на звонок — можно общаться.

CallBackZadarma
Обратите внимание: как на месте «вашего телефона», так и на месте «телефона, на который звоните» может быть ваш SIP-логин либо внутренний номер АТС. Это позволяет совершать и исходящие звонки с офисных IP-телефонов/шлюзов/программ SIP а также звонки внутри сети.
Название метода: /v1/request/callback/
Параметры:
  • from – ваш номер телефона или SIP, который вызывается callback;
  • to – номер телефона или SIP, которому звонят;
  • sip (опционально) – номер SIP-пользователя, если он хочет использовать определенный CallerID, закрепленный за этим SIP-ом;
  • predicted (опционально) – если указан этот флаг, то запрос является предикативным (система изначально звонит на номер “to” и только если ему дозванивается, соединяет с вашим SIP либо телефонным номером);

Пример ответа:
JSON
{
    "status":"success",
    "from": 442037691880,
    "to": 442037691881,
    "time": 1435573082
}
XML
<?xml version="1.0"?>
<answer>
    <status>success</status>
    <from>442037691880</from>
    <to>442037691881</to>
    <time>1435573082</time>
</answer>

Пример PHP с классом Zadarma:
<?php
include_once 'include.php';
$params = array(
    'from' => '442037691880',
    'to' => '442037691881',
//    'sip' => 'YOURSIP'
);
$zd = new \Zadarma_API\Client(KEY, SECRET);
$answer = $zd->call('/v1/request/callback/', $params);
$answerObject = json_decode($answer);
if ($answerObject->status == 'success') {
    print_r($answerObject);
} else {
    echo $answerObject->message;
}


Удобство для коллцентров


Специально для коллцентров есть возможность предикативного набора — система изначально звонит на номер “to” и только если ему дозванивается, соединяет с вашим SIP либо телефонным номером.
Например: у вас есть большой список номеров куда звонить и несколько сотрудников коллцентра, с предикативным набором вам не нужно чтобы сотрудники поочередно набирали номера и ждали результат (теряя рабочее время).
Для удобного обзвона номеров из коллцентра:
  • передаете список номеров через вызовы функции callback в API
  • в параметре from указываете номер вашей бесплатной АТС, к которой и подключены сотрудники коллцентра, также указываете флаг predicted
  • готово! Система сама обзвонит ваших клиентов, и только если клиент возьмети трубку к вашим сотрудникам поступит входящий звонок и начнется разговор. Заметная экономия времени сотрудников.
Обратите внимание: Система совершит совершит такой обзвон только если в нем более четверти действительных номеров.

Уведомление о входящем звонке


Система Zadarma может отправлять информацию о каждом входящем звонке в виртуальной АТС и направлять звонок на нужный внутренний номер в зависимости от ответа. Для этого необходимо создать открытую для всеобщего доступа ссылку, которая будет принимать POST-запросы с информацией из системы Zadarma.
Для того, чтобы система приняла ссылку, необходимо добавить проверочный код вначале скрипта.
Пример на PHP:
<?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?>
Параметры, которые отправляются на callback-ссылку:
  • caller_id — номер звонящего;
  • called_did – номер, на который позвонили;
  • callstart – время начала звонка
Для каждого запроса можно «на лету» изменять сценарий работы по текущему звонку, отправив в ответ на информацию:
{     "redirect": ID,     "caller_name": NAME }
где,
  • redirect – id сценария редиректа или внутренний номер АТС, или «blacklist» — в этом случае звонок будет отклонен с сигналом занято;
  • caller_name – можно дать имя входящему номеру.

Пример кода на PHP:
<?php
if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']);
if ($_POST) {
    $callerId = $_POST['caller_id']; // number of calling party;
    $calledDid = $_POST['called_did']; // number of called party;
    $callstart = $_POST['callstart']; // start time of call
    /*
    // For each request you can easily change work scenario for current call by sending in response on information:
    echo json_encode(array(
        'redirect' => 1,
        'caller_name' => 'TestName'
    ));
    exit();
    */
}

Полный список методов API:


/v1/info/balance/ — текущий баланс пользователя;
/v1/info/price/ — стоимость звонка с учетом текущего тарифа пользователя;
/v1/request/callback/ — запрос на callback (описан выше);
/v1/sip/ — список SIP-номеров пользователя;
/v1/sip/callerid/ — изменение CallerID (из приобретенных либо подтвержденных номеров);
/v1/sip/redirection/ — отображение текущих переадресаций по SIP-номерам пользователя, включение/выключение переадресации, изменение параметров переадресации;
/v1/sms/send/ — отправка SMS;
/v1/statistics/ — получение общей статистики;
/v1/statistics/pbx/ — статистика по бесплатной АТС.

В будущем планируется увеличение количества методов. Если считаете, что есть методы, которые необходимо добавить в API — пишите в комментариях.
Tags:
Hubs:
Total votes 29: ↑27 and ↓2+25
Comments21

Articles

Information

Website
zadarma.com
Registered
Founded
Employees
51–100 employees
Location
Россия
Representative
IgorDimitrov