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

    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 — пишите в комментариях.
    Zadarma
    Бесплатная облачная АТС, виртуальные номера

    Комментарии 21

      +5
      Не совсем понятно со звонками из АТС. Можно через API сделать звонок с внутреннего номера АТС?
        +4
        Да, конечно можно. Звонить также через функцию Callback, для этого указывайте внутренний номер АТС в поле from. Например:
        from – 102
        to – 7495777….
        sip — 101
        В примере еще и CallerID будет с соседнего номера 101 взят (можно и свой использовать со 102). Приношу извинения, что эта возможность не была описана в на сайте, сейчас добавим в информацию про CallBack.
        +5
        Ограничения я так понимаю 100 запросов в минуту. Это для любых запросов?
          +4
          Для всех кроме статистики. Статистику можно запрашивать 10 раз в минуту (и не более чем за 30 дней в одном запросе).
          +2
          Будет ли реализация получения записи звонка, если звонить через CallBack?
          Т.е. хотелось бы после звонка получать ссылку с возможностью скачать запись звонка, для контроля менеджеров например, или привязки записи в crm.
            0
            Получение записи звонка при звонке через CallBack есть, но только не через ссылку а по email.
            Это одна из функций бесплатной АТС: На внутреннем номере менеджера включаете запись звонка и записи всех его разговоров поступают в заданный почтовый ящик. CallBack запросы отправляете на этот внутренний номер. Так подойдет?

            (Возможно удобней именно по ссылке, что-то подобное будет реализовано позже в рамках очередного расширения функционала, сейчас все записи отправляются по почте).
              0
              Почта это плохо, это сложно автоматизировать, получить ссылку, выкачать файл и прикрепить в CRM намного проще.
              Еще бы хотелось вместе со звонком передавать вам какой то параметр, который будет возвращаться вместе с ссылкой на запись разговора, чтобы можно было идентифицировать конкретный звонок, даже если сосед звонил в то же самое время.
                0
                Хранение записей и передача их по ссылке есть в планах, и обязательно это сделаем.
                Почта это пока временный вариант.

                Насчет идентификации звонка. С каждым звонком есть номер кто звонил номер куда звонил и время, я думаю этого будет достаточно для его идентификации?
                А при входящих звонках можно еще и имя каждому звонку дать.
                  0
                  Есть тривиальная задача привязать запись звонка к CRM, так я передаю например id контакта/компании/лида и могу четко идентифицировать куда мне эту запись прикрепить. А так я имею только запись разговора кто и кому звонил и время вызова.
                  Один номер может быть у разных компаний и начинается неразбериха, куда и зачем звонили.
                  Думаю один дополнительный параметр не сложно получить и передать, а жизнь это порядком облегчит.
                    0
                    Лучше тогда не один, а все параметры начинающиеся с определенного префикса. Так часто делают в платежных системах и клиент сам может решить, сколько параметров ему нужно и что они будут означать.
                      0
                      Добрый день,

                      На сегодня задача привязки статистики в записям звонков частично решена.
                      С сегодняшнего дня поле «call_id»: передает уникальный айди звонка, аналогичный айди есть в названиях всех файлов с записями звонков.
                      То есть вы можете по этому айди выгружать записи не только за сегодня, а за любой прошлый период.

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

                        0
                        Отлично, ждем загрузку из облака и делаем интеграцию :)
              +1
              Неплохо было бы сделать API для партнеров, разумеется не тех, кто работает по ссылке, а через дилерский аккаунт — регистрация/удаление пользователей и т.п.
              А то использовать в своем приложении звонки через Вас для множества независимых пользователей очень неудобно.
              Регистрация и дальнейшие настройки — все вручную, через подтверждение по почте и т.д.
              Автоматизировать бы все это.
                0
                Это обсуждается, чтобы учесть все технические организационные и юридические нюансы.
                –1
                Информация о входящих звонках

                1. куда прописать ссылка для оповещения?
                2. почему нет уникального id звонка? по нем в дальнейшем можно было бы получить запись разговора и т.д.
                3. Почему оповещение только при поступлении звонка? Еще надо когда взял трубку, завершил или перевел.
                4. Такое же надо для исходящих звонков. CRM тоже надо это знать

                пока это в реальности использовать невозможно
                  0
                  Вы точно прочли статью выше и попробовали это использовать? :)

                  1. ссылка настраивается там-же где и получаются ключи для начала работы с API. Не получится начать работать с API не заметив настройки ссылки.
                  2. Есть поле caller_name, можете там задать что вам нравится. В системе уникальными является сочетание 2-х номеров и времени. По ним можете получать любую статистику и загружать записи (записи звонков сейчас передаются в почту).
                  3. При начале звонка придет оповещение. Информация как/когда/чем завершился звонок легко может быть получена из статистики.
                  4. CRM сама создает исходящие звонки через функцию callback. Ей нужно напомнить о том что она сама сделала?

                  За последние недели в реальности многие уже это используют и довольны функционалом. Потому рекомендуем попробовать.

                  По поводу записи разговоров и передачи записи по ссылке: это выше обсуждали, вопросов нет, все передали разработчикам.
                    +1
                    точно прочел, но конечно же не использовал

                    1. это можно было упомянуть в статье, не все сразу кидаются что-то пробовать
                    2. уникальный id намного удобней и не надо думать о формате даты, формате телефонов и кучи всего кто может возникнуть
                    3. если нет события о поднятии трубки, то какому пользователю показывать карточку звонка в СРМ? А если надо сразу после завершения звонка запустить бизнес процесс? статистика это хорошо, это она не в реальном режиме.

                    а еще просят при переводе звонка, открыть карточку в нового пользователя. Как это сделать?

                    4. А если звонок сделать не с срм через callback?

                    Я написал не просто так покритиковать, а опираясь на опыт интеграции нашей CRM не с одной телефонией (октелл, астериск, бинотел, ...).

                    Указанные замечания очень важны.

                    Просто так пробовать дорогое удовольствие. Надо для начала понять надо ли это, что с этого можно сделать и предложить клиентам. Но то что есть API это уже большой плюс, осталось довести до ума :-)

                      0
                      Сегодня реализован пункт 2 в вашем вопросе.
                      Пункт call_id в статистике АТС передает уникальный айди звонка, этот айди уже есть в названии всех записей звонков.
                  0
                  Использовал этот API для написания интеграции к нашей CRM casepress.org/product/integratsiya-casepress-i-ip-ats-zadarma
                  Тестируем уже неделю — полет нормальный. Очень удобно и экономично.
                    0
                    Дополнения к интерфейсу API Zadarma.

                    Добавлены методы:
                    /v1/pbx/internal/ — отображение внутренних номеров АТС.
                    /v1/pbx/internal/recording/ — включение записи разговоров на внутреннем номере АТС.

                    Также модифицирован метод /v1/statistics/pbx/ — статистика по АТС
                    После модификации поле "call_id" содержит уникальный ID звонка, который указан в названии файла с записью разговора.

                      Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                      Самое читаемое