База знаний

API

CallTracking API - инструмент для разработчиков, позволяющий получить доступ к статистике ваших проектов отслеживания звонков и построить выборки по интересующим критериям. Запросы к API имеют похожую логику логику API GoogleAnalytics, что даёт преимущество разработчикам знакомым с последней системой. В качестве формата ответа используется JSON.

1. Ссылки на исходники

Для простоты формирования запросов к API есть библиотека, написанная на языке PHP. Последняя версия библиотеки доступна по ссылке calltracking_api_lib.zip. Если вы используете другие языки, то вызовы нужно формировать аналогично. Примеры даны ниже.

2. Руководство
2.1. Аутентификация

Перед отправкой запросов к API нужно пройти аутентификацию. Для этого на сервер нужно отправить запрос следующего вида:

 

https://calltracking.ru/api/login.php?account_type=calltracking&login=ваш_логин&password=ваш_пароль&service=analytics

В случае успешной аутентификации в ответе прийдёт объект следующего вида:

 

{
    "status":"ok",
    "data":"calltracking-f4d91f112р623e92523faf8a3130476a-n-946096c94052aa22df39fa189a3fa96dffe1b2df",
    "error_code":"0",
    "error_text":""
ct:status }

Поле data - токен, который надо передавать при последующих запросах к API.

В случае не успешной аутентификации ответ будет иметь следующий вид:

 

{
    "status":"error",
    "data":"",
    "error_code":"3",
    "error_text":"Bad login or password"
}

2.2. Построение запросов

Запросы к API состоят из размерностей(dimensions), показателей(metrics) и фильтров(filters), по аналогии с API Google Analytics. Эти параметры передаются GET или POST запросом на https://calltracking.ru/api/get_data.php. Показатели - это индивидуальные параметры активности по звонкам на вашем сайте. В данный момент показатели включают в себя:

 

показатель описание
ct:calls численный показатель звонков
ct:duration длительность звонка в секундах
ct:answer_time время поднятия трубки
ct:call_comment Комментарий звонка из личного кабинета
ct:caller_history_listing история посещения страниц звонящим
ct:caller_history_listing_full история посещения страниц звонящим с указанием изменения реквизитов источника

 

Размерности разбивают показатели на группы. Например источник звонка или дата совершения звонка. Вот полный список доступных размерностей:

 

размерность описание
ct:datetime Дата и время совершения звонка в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС. С использованием этой размерности мы, как правило, получаем индивидуальные звонки. Исключение - одновременные звонки.
ct:date Дата совершения звонка в формате ГГГГ-ММ-ДД.
ct:source Название источника звонка
ct:caller Номер звонящего. С использованием этой размерности мы, как правило, получаем индивидуальные звонки. Исключение - повторные звонки.
ct:virtual_number Виртуальный номер, на который поступил звонок.
ct:recipient Реальный номер принимающий звонок.
ct:recordlink Ссылка на mp3-запись звонка.
ct:calltag Метка звонка
ct:dsource Только для динамического коллтрекинга: определившийся источник
ct:dmedium Только для динамического коллтрекинга: определившийся канал
ct:dcampaign Только для динамического коллтрекинга: определившаяся кампания
ct:dterm Только для динамического коллтрекинга: определившийся запрос
ct:dcontent Только для динамического коллтрекинга: определившееся содержание
ct:cid Только для динамического коллтрекинга: google client id звонящего
ct:status Состояние звонка. Может принимать варианты:
ANSWERED - разговор был совершён
NO ANSWER - трубку не подняли
BUSY - сигнал занято
FAILED - ошибка в работе промежуточного оборудования
ct:category Категория звонка. Может принимать варианты:
static - звонок по статическому источнику
offline - оффлайн звонок. Звонящий был не на сайте во время совершения звонка
online - онлайн звонок
bounce - отказной звонок. Несколько посетителей одновременно видели номер во время совершения звонка
deferred - отложенный звонок. Реквизиты звонящего скопированы из звонка совершённого ранее

 

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

Фильтры позволяют оставить только интересующие записи выборки Список доступных размерностей:

 

фильтруемые размерности доступные операторы пример
ct:duration =, !=, <, >, >=, <= ct:duration>=30 - В выборке останутся только звонки общей длительностью более 30 секунд
ct:answer_time =, !=, <, >, >=, <= ct:answer_time<5 - В выборке останутся только звонки, время ожидания ответа которых - менее 5 секунд
ct:caller =, != ct:caller=4951234567 - Останутся только звонки с номера (495) 123-45-67
ct:status =, != ct:status!=ANSWERED - Останутся все звонки, кроме отмеченных
ct:calltag =, != ct:calltag=1 - Останутся только звонки с цифровой меткой 1
ct:recordlink =, != ct:recordlink=/shareRecords/2016-05-03/1462264350.975416.mp3 - Будет найдена точно указанная запись разговора
ct:dsource,
ct:dmedium,
ct:dcampaign,
ct:dterm,
ct:dcontent
=, != ct:dcampaign=gazonokosilki - Останутся только звонки с кампании gazonokosilki
ct:call_comment =, != ct:call_comment!=звонок от спаммера - Будут исключены звонки с указанными комментариями

 

Список проектов

Список проектов (рис. 1)

Помимо размерностей, показателей и фильтров дополнительными параметрами запроса к API являются:

project - id проекта отслеживания звонков по которому проводится выборка. Можно узнать из списка проектов (рис. 1).

start-date и end-date - даты, ограничивающие отчётный период. Принимаются значения в формате ГГГГ-ММ-ДД.

sort - показатель, по которому надо проводить сортировку. Принимаются те-же значения, что и в размерностях и показателях. Порядок сортировки можно изменить, если первым символом указать - (знак минус).

max-results - максимальное количество записей в ответе. Может принимать целочисленные значения от 1 до 10 000.

start-index - сдвиг от первой записи. Может принимать целочисленные значения.

view-type - тип представления. Может принимать следующие значения: grouped - сгруппированный список по размерностям и list - простой список, без группировки

scope-unique - фильтрация уникальных звонков. Может принимать следующие значения 1 или 0

2.3. Ошибки в запросах

Самыми распространёнными ошибками являются:

Code 3: Bad login or password - при не корректной аутентификации.

Code 4: Data not accessible - при указании некорректного id проекта отслеживания звонков или некорректного токена

Code 6: API request is not correct. Check parametrs - при ошибках в параметрах запроса или при несовместимых размерностей и показателей.

Code 6: You have exeeded daily request quota - при превышении суточного ограничения на количество запросов к API (подробнее).

3. Примеры запросов

Ниже указаны самые популярные запросы к API.

После аутентификации полученный token нужно передавать в каждом запросе как отдельный параметр. Вот пример запроса

3.1. Получение количества звонков за каждый день

 

https://calltracking.ru/api/get_data.php?project=101&auth=token&dimensions=ct%3Adate&metrics=ct%3Acalls&sort=-ct%3Acalls&start-date=2012-04-01&end-date=2012-05-31&max-results=100&start-index=0

Результатом будет структура такого вида:

 

{
    "status":"ok",
    "data":{"2012-05-22":{"ct:calls":"687"},"2012-05-21":{"ct:calls":"630"}, ... // всего 100 записей
    "error_code":"0",
    "error_text":""
}

Этот запрос удобно формировать PHP библиотекой, которая сама будет передавать token и заботится о экранировании параметров. Указанный выше пример с использованием библиотеки будет формироваться так:

 

<?php
...
require_once("calltracking_api.php");
$CT_api = new calltracking_api();
if ( $CT_api->login($login, $password) ) {
 
    $params = array();
    $params['project'] = 101;
    $params['dimensions'] = 'ct:date';
    $params['metrics'] = 'ct:calls';
    $params['sort'] = '-ct:calls';
    $params['start-date'] = '2012-04-01';
    $params['end-date'] = '2012-04-30';
    $params['max-results'] = 10;
    $params['start-index'] = 0;
 
    $CT_data = $CT_api->getData($params);
 
    var_dump($CT_data);
}
?>

Результатом будет декодированная структура того-же вида. Для наглядности все следующие примеры будут указаны с использованием PHP библиотеки.

3.2. Получение статистики статусов звонков по источникам

Указанные параметры для формирования запроса к API позволяют получить количество звонков в каждом источнике по группам ANSWERED/NO ANSWER, которые длятся более 5 секунд

 

<?php
    ...
    $params['project'] = 101;
    $params['dimensions'] = 'ct:source,ct:status';
    $params['metrics'] = 'ct:calls';
    $params['start-date'] = 2012-04-01';
    $params['end-date'] = '2012-04-30';
    $params['max-results'] = 100;
    $params['start-index'] = 0;
    $params['filters'] = 'ct:duration>5';
?>

 

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

CT_data:Array

(

    [status] => ok

    [data] => Array

        (

            [Яндекс SEO] => Array

                (

                    [ANSWERED] => Array

                        (

                            [ct:calls] => 6162

                        )

 

                    [NO ANSWER] => Array

                        (

                            [ct:calls] => 193

                        )

 

                    [BUSY] => Array

                        (

                            [ct:calls] => 60

                        )

 

                )

 

            [Яндекс.Директ] => Array

                (

                    [ANSWERED] => Array

                        (

                            [ct:calls] => 3770

                        )

 

                    [NO ANSWER] => Array

                        (

                            [ct:calls] => 137

                        )

 

                    [BUSY] => Array

                        (

                            [ct:calls] => 61

                        )

                )

                

             ...

        )

 

    [error_code] => 0

    [error_text] =>

)

3.3. Продолжительность и время снятия трубки звонков за один день

 

<?php
    ...
    $params['project'] = 101;
    $params['dimensions'] = 'ct:datetime';
    $params['metrics'] = 'ct:duration,ct:answer_time';
    $params['sort'] = '-ct:datetime';
    $params['start-date'] = '2012-04-30';
    $params['end-date'] = '2012-04-30';
    $params['max-results'] = 10;
    $params['start-index'] = 20;
?>

Указана сортировка по времени, чтобы звонки шли от более поздних к более ранним. В указанном примере API вернёт 10 записей, начиная с 3 страницы.

3.4. Количество звонков на каждую метку тегирования

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

 

<?php
    ...
    $params['project'] = 101;
    $params['project'] = $project_id;
    $params['dimensions'] = 'ct:recipient,ct:calltag';
    $params['metrics'] = 'ct:calls';
    $params['start-date'] = '2012-04-01';
    $params['end-date'] = '2012-04-30';
    $params['max-results'] = 1000;
    $params['start-index'] = 0;
?>

Наверняка в указанном примере большая часть звонков не будет иметь отметки тегирования. В таком случае группа без метки будет называться (not set).

 

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

 

CT_data:Array
(
    [status] => ok
    [data] => Array
        (
            [84956605651] => Array
                (
                    [(not set)] => Array
                        (
                            [ct:calls] => 9237
                        )
 
                    [1] => Array
                        (
                            [ct:calls] => 1013
                        )
 
                    [5*2000] => Array
                        (
                            [ct:calls] => 16
                        )
 
                    ...
                )
 
        )
 
    [error_code] => 0
    [error_text] =>
)

4. Ограничения использования

Запросы к API доступны только регулярным аккаунтам системы CallTracking. Гостевым аккаунтам и клиентам агентств запросы не доступны.

Для предотвращения высоких нагрузок на сервер введено ограничение на количество запросов в сутки. Регулярным клиентам доступно:

1000 запросов в сутки.

10 одновременных запросов в секунду.

Для крупных агентств и активных пользователей ограничение может быть увеличено по письменной просьбе.