Интеграция calltracking.ru

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!=звонок от спаммера - Будут исключены звонки с указанными комментариями

Помимо размерностей, показателей и фильтров дополнительными параметрами запроса к 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 одновременных запросов в секунду.

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

Интеграция API calltracking.ru

API

Получите скидку 25% на любые продукты, 500 минут транскрибации и 5 тегов заявок

Получите скидку 25% на любые продукты,
500 минут транскрибации и 5 тегов заявок