Интеграция по API Calltracking.ru 2.0.
Calltracking API — инструмент для разработчиков, позволяющий получить доступ к статистике обращений ваших проектов и построить выборки нужных данных. Запросы к API имеют похожую логику API Google Analytics, что упрощает задачу разработчикам, знакомым с этой системой.
Авторизация, методы авторизации
Перед отправкой запросов к API нужно подтвердить право видеть запрашиваемую статистику — пройти аутентификацию.
Самый простой способ — указать свой логин и пароль. Для этого на сервер нужно отправить запрос следующего вида:
https://calltracking.ru/api_upgrade/login.php?login=ваш_логин&password=ваш_пароль
В случае успешной аутентификации в ответе придёт объект следующего вида:
{
"status":"ok",
"data":"calltracking-f4d91f112р623e92523faf8a3130476a-n-946096c94052aa22df39fa189a3fa96dffe1b2df",
"error_code":"0",
"error_text":""
}
Поле data — токен, который надо передавать при последующих запросах к API. В случае неуспешной аутентификации ответ будет иметь следующий вид:
{
"status":"error",
"data":"",
"error_code":"3",
"error_text":"Bad login or password"
}
Время жизни токена — 1 месяц. Токен можно получать перед каждым запросом к API, но он меняться не будет, потому его можно сохранить и пользоваться пока он не устареет.
По запросу время жизни токена можно увеличить максимум до 5 лет. Но он все равно утратит свою актуальность, если будут происходить крупные изменения, связанные с доступами — например, когда отключают какой-либо аккаунт или проект, который связан с полученным токеном.
Формирование запроса и примеры
Получив токен, можно приступать к формированию запроса. Обязательными параметрами для запроса будут:
- id проекта
- даты (интервал)
- размерности
- метрики
- количество записей
- токен, полученный при авторизации
Вот примеры запросов:
Метрики
После авторизации можно приступать к формированию самого запроса к API. Первым обязательным параметром запроса являются метрики обращений. Метрика — это определенная характеристика одной группы обращений. Результатом ответа API будут значения всех выбранных метрик по выбранным группам обращений. Ниже перечень всех доступных метрик:
| Показатель | Описание |
| ct:entity_name | Тип обращения (звонок/email/чат/обратный звонок) |
| ct:datetime | Численный показатель звонков |
| ct:entity_count | Численный показатель звонков |
| ct:entity_count_unique | Численный показатель звонков |
| ct:entity_count_repeated | Численный показатель звонков |
| ct:tagname | Численный показатель звонков |
| ct:calls | Численный показатель звонков |
| ct:caller_history_listing | История посещения страниц звонящим |
| ct:caller_history_listing_full | История посещения страниц звонящим с указанием изменения реквизитов источника |
| ct:dsource_entity | UTM-метка источника звонка |
| ct:dmedium_entity | UTM-метка канала звонка |
| ct:dcampaign_entity | UTM-метка кампании звонка |
| ct:dterm_entity | UTM-метка ключевого слова звонка |
| ct:dcontent_entity | UTM-метка содержания звонка |
| ct:status | Статус звонка (отвечен/не отвечен/занято/сбой соединения) |
| ct:category | Категория звонка (онлайн/оффлайн/отказной/отложенный/статический) |
| ct:recordlink | Ссылка на запись разговора |
| ct:source | Источник звонка |
| ct:dst | Подменный номер, на который поступил звонок |
| ct:src | Номер звонящего |
| ct:rdst | Реальный номер, на который переадресован звонок |
| ct:city_code | Код реального номера, на который переадресован звонок |
| ct:count_unique_calls | Количество уникальных звонков |
| ct:tag | Отмеченные теги тонального тегирования |
| ct:tagtext | Отмеченные названия тегов тонального тегирования |
| ct:is_unique | Признак уникальности звонка |
| ct:call_id | id звонка |
| ct:uniqueid | Название файла записи звонка |
| ct:import_call_id | id звонка той системы, откуда он был импортирован |
| ct:call_region | Регион, откуда поступил звонок |
| ct:client_landing | Посадочная страница клиента |
| ct:landing | Посадочная страница звонка |
| ct:cid | Google client id |
| ct:hangupcode | Код завершения вызова |
| ct:user_agent | useragent посетителя |
| ct:visitors | Количество посетителей (из аналитики) |
| ct:hours | Часы поступления звонков |
| ct:cost | Стоимость объявлений (контекстная реклама), которые привели к звонкам |
| ct:calls_percent | Доля звонков текущей группы от общего числа звонков |
| ct:call_unique_percent | Доля уникальных звонков текущей группы от общего числа звонков |
| ct:metric_value | id посетителя, совершившего звонок, в Яндекс.Метрике |
| ct:client_name | Имя клиента |
| ct:client_phone | Телефон клиента |
| ct:client_email | Email клиента |
| ct:transcribation_text | Полный текст разговора |
| cs:tagger_comment_val | Комментарий тегератора |
| cs:target_calls | Количество целевых звонков |
| cs:not_target_calls | Количество нецелевых звонков |
| cs:effective_call | Показатель эффективности для данной выборки |
| cs:example_metrik | Абсолютно любые теги из системы речевой аналитики |
Размерности
В сочетании с метриками в API используются размерности. Размерность — это характеристика / группа, по которой вы хотите анализировать данные. Можно использовать несколько размерностей одновременно, разделяя их запятыми.
При использовании нескольких размерностей обретает важность параметр view-type
view-type=grouped покажет данные по размерностям вложенным списком
view-type=list покажет данные по размерностям плоским списком
Ниже — перечень всех доступных размерностей:
| Размерность | Описание |
| 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:uniqueid | id звонка, полученного от АТС Calltracking.ru |
| ct:call_id | id звонка в системе Calltracking.ru |
| ct:import_call_id | id звонка, импортированного из внешней системы |
| ct:day_week | День недели |
| ct:bundleName | Название связки |
| ct:calltagtext | Текстовая расшифровка тега |
| ct:dynamic_campaign_name | Название кампании в контекстной системе |
| ct:dclients | id сессий посетителей, которые совершили звонок |
| ct:city_code | Код региона звонящего |
| ct:call_region | Регион звонящего |
| ct:hours | Час суток совершения звонка |
| ct:month | Месяц совершения звонка |
| ct:landing | Посадочная страница |
| ct:domain | Доменное имя сайта, откуда пришел звонок |
| ct:project | id проекта |
| cs:tagger_comments | Комментарий тегератора |
| cs:managers_callscoring | Менеджер принимавший звонки |
| cs:all_status | Все заведенные статусы (чекбоксы) системы речевой аналитики |
| cs:all_properties | Все заведенные свойства (радиокнопки) системы речевой аналитики |
| cs:example_dimension | Абсолютно любые теги из системы речевой аналитики |
Фильтры
| Фильтруемые размерности | Доступные операторы | Пример |
| 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!=звонок от спаммера Будут исключены звонки с указанными комментариями |
| ct:dynamic_campaign_name | =, != | ct:dynamic_campaign_name=ВЧ запросы Останется только кампания высокочастотных запросов |
| ct:uniqueid | =, != | ct:uniqueid=1681752054.8532683 Будет найден только один звонок |
| ct:import_call_id | =, != | ct:import_call_id!=1234567 Из выдачи будет исключен один импортированный звонок |
| ct:tagname | =, != | ct:tagname=целевой Останутся только звонки, протегированные как целевые |
| ct:source_id | =, != | ct:source_id=423847 В выдаче останется только выбранный источник |
| ct:disposition | =, != | ct:disposition=ANSWERED Останутся только отвеченные звонки |
| ct:category | =, != | ct:category!=bounce В выдаче останутся все звонки, кроме отказных |
| ct:call_region | =, != | ct:call_region=Республика Татарстан Останется только выбранный регион |
| ct:is_hands_tagged | =, != | ct:is_hands_tagged=y Выбраны только прослушанные тегератором звонки |
Scope
Разновидностью фильтра является Scope.
На данный момент во всех версиях API существует только один вариант Scope — scope-unique=1
Ограничения по страницам и датам
Помимо размерностей, показателей и фильтров, дополнительными параметрами запроса к API являются: start-date и end-date — даты, ограничивающие отчетный период. Принимаются значения в формате ГГГГ-ММ-ДД, указывающие конкретные даты, или псевдонимы из следующего списка:
yesterday — вчерашний день (пример: 2023-05-25)
today — сегодняшний день (пример: 2023-05-26)
week_ago — семь дней назад (пример: 2023-05-19)
week_start — семь дней назад (пример: 2023-05-19)
month_ago — месяц назад (пример: 2023-04-26)
month_start — начало текущего месяца (пример: 2023-05-01)
year_ago — год назад (пример: 2022-05-26)
year_start — начало текущего года (пример: 2023-01-01)
max-results — количество записей на одной странице
start-index — смещение относительно начала (сколько строк пропустить)
Типы обращений
Для данной версии API доступен выбор типов обращений, которые возвращают запрос. Название параметра — source-data
Перечисление типов обращений — через запятую.
Пример всех доступных видов:
source-data=calls,chats,conversions,callback,emails