Выгрузка журнала звонков
Назначение API
API — это программный интерфейс для внешних программных продуктов.
Рассматриваемый в данном разделе API интерфейс позволяет получить статистику о звонках, которая может быть проанализирована другими системами, и на основе которой клиенты сервиса могут сделать свои выводы и прогнозы, интегрировать данные в CRM, или другие сервисы.
Формат запросов данных о звонках
Допустимые типы запросов: GET
Формат результатов выборки: JSONMapObject
Стандартная выборка звонков за один день
Описание запроса
Пример стандартного запроса с выборкой данных за один день:
https://api.calltouch.ru/calls-service/RestAPI/{ID Вашего сайта}/calls-diary/calls?clientApiId={токен}&dateFrom=29/11/2016&dateTo=29/11/2016
В примере выше перечислены обязательные входные параметры, подробно о которых рассказано в таблице ниже. При этом дата во входных параметрах dateFrom и dateTo должна быть одинаковой, т.к. по умолчанию для оптимизации скорости работы серверов Calltouch выборка статистики по звонкам возможна только за один день.
Описание ответа
Пример стандартного ответа по запросу с выборкой данных за один день:
[{call1},{call2},{call3},...]
Все выходные параметры перечислены в таблице ниже.
Постраничная выборка звонков более чем за один день
Описание запроса
Для выборки статистики по звонкам более чем за один день, необходимо использовать постраничный формат. Для этого в запрос, помимо обязательных входных параметров dateFrom и dateTo, добавьте параметр page, указав его значение равное номеру страницы. На одной странице при этом может быть выгружено не более 1000 звонков.
Пример постраничного запроса для выборки данных более чем за один день:
https://api.calltouch.ru/calls-service/RestAPI/{ID Вашего сайта}/calls-diary/calls?clientApiId={токен}&dateFrom=01/11/2016&dateTo=29/11/2016&page=1&limit=500
Где для постраничной выборке используются параметры:
- page=1 — номер страницы, в данном примере первая.
- limit=500 — дополнительный необязательный параметр, максимальное количество звонков на странице, в данном примере 500, максимально возможное значение равно 1000.
Более подробно о данных входных параметрах рассказано в таблице ниже.
Описание ответа
Ответ постраничного запроса будет различаться от стандартного, пример:
{"page":1,"pageTotal":1,"pageSize":500,"recordsTotal":10,"records":[{call1},{call2},{call3},...,{call10}]}
Где:
- "page":1 — номер страницы, в данном примере первая.
- "pageTotal":1 — всего страниц, в данном примере одна.
- "pageSize":500 — максимальное количество звонков на странице, в данном примере 500, т.к. установлен входной параметр limit.
- "recordsTotal":10 — всего звонков, в данном примере десять.
Все выходные параметры перечислены в таблице ниже.
Указание модели атрибуции "Последний непрямой"
В зависимости от модели атрибуции (см. статью Настройки модели атрибуции), источник звонка может меняться. По умолчанию источники звонков в API выгружаются по модели атрибуции "Последний непрямой". Выбор модели атрибуции осуществляется с помощью входного параметра attribution, его возможные значения:
- 0 — последнее взаимодействие
- 1 — последний непрямой (по умолчанию, если параметр не указан)
Параметр attribution=1 можно и не указывать, он используется по умолчанию.
Изменение настроек модели атрибуции в разделе: Настройки / Отчеты / Модель атрибуции личного кабинета Calltouch влияет только на отображение статистики в веб-интерфейсе, это НЕ влияет на выгрузку данных через API.
Запрос для выгрузки звонков по модели атрибуции "Последний непрямой" за один день:
https://api.calltouch.ru/calls-service/RestAPI/{ID Вашего сайта}/calls-diary/calls?clientApiId={токен}&dateFrom=16/02/2017&dateTo=16/02/2017&attribution=1
Постраничный запрос для выгрузки звонков по модели атрибуции "Последний непрямой" за несколько дней:
https://api.calltouch.ru/calls-service/RestAPI/{ID Вашего сайта}/calls-diary/calls?clientApiId={токен}&dateFrom=1/02/2017&dateTo=16/02/2017&page=1&limit=500&attribution=1
Все выходные параметры перечислены в таблице ниже. Пример с различными источниками одного и того же звонка в зависимости от выбранной модели атрибуции смотрите в конце статьи.
Указание модели атрибуции "Последнее взаимодействие"
Можно изменить модель атрибуции "Последний непрямой", используемую в API по умолчанию, на "Последнее взаимодействие", добавив параметр attribution=0, после чего источники звонков будут отображены уже по последней сессии перед звонком.
Запрос для выгрузки звонков по модели атрибуции "Последнее взаимодействие" за один день:
https://api.calltouch.ru/calls-service/RestAPI/{ID Вашего сайта}/calls-diary/calls?clientApiId={токен}&dateFrom=16/02/2017&dateTo=16/02/2017&attribution=0
Постраничный запрос для выгрузки звонков по модели атрибуции "Последнее взаимодействие" за несколько дней:
https://api.calltouch.ru/calls-service/RestAPI/{ID Вашего сайта}/calls-diary/calls?clientApiId={токен}&dateFrom=1/02/2017&dateTo=16/02/2017&page=1&limit=500&attribution=0
Все выходные параметры перечислены в таблице ниже. Пример с различными источниками одного и того же звонка в зависимости от выбранной модели атрибуции смотрите в конце статьи.
Входные параметры
Имя параметра | Обязателен | Описание |
siteId | Да | Уникальный идентификатор Вашего сайта в Calltouch. Формат: https://api.calltouch.ru/calls-service/RestAPI/XXX/... , где XXX - идентификатор Вашего сайта в Calltouch. |
clientApiId | Да | Уникальный токен доступа в Calltouch для отправки API-запроса в Calltouch. Получить его можно в разделе Интеграции => API личного кабинета Calltouch. Формат: clientApiId=45-значный токен |
dateFrom | Да | Дата начала выборки. Формат: dateFrom=dd/mm/yyyy |
dateTo | Да | Дата конца выборки. Формат: dateTo=dd/mm/yyyy |
timeFrom | Нет | Время начала периода выгрузки в формате hh:mm:ss. |
timeTo | Нет | Время конца периода выгрузки в формате hh:mm:ss. |
page | Нет |
При использовании данного параметра, включается постраничный формат выборки. В данном параметре указывается номер страницы. При этом на одной странице может быть отображено до 1000 звонков. Формат: page=X, где X >= 1 |
limit | Нет | Ограничение на количество записей одной страницы. Используется только вместе с предыдущим параметром page. Формат: limit=X, где 1 <= X <= 1000 |
clientId | Нет | Уникальный идентификатор Google Analytics 4. Параметр присутствует в случае, если настроена интеграция Calltouch с Google Analytics 4. Допустимо вводить несколько значений, разделенные знаком ",". Формат: clientId=XXX,YYY,ZZZ,... |
yaClientId | Нет |
Уникальный идентификатор Яндекс.Метрика. Значение параметра не равно null, если настроена выгрузка звонков в Яндекс.Метрика. Обратите внимание! Даже если выгрузка звонков в Яндекс.Метрика настроена, в некоторых случаях Яндекс.Метрика не присваивает свой ИД пользователю:
Значение yaClientId в этих случаях будет равно null. |
callId | Нет | Список уникальных идентификаторов звонка в системе Calltouch. Допустимо вводить несколько значений, разделенные знаком ",". Формат: callId=XXX,YYY,ZZZ,... |
attribution | Нет |
Модель атрибуции звонков. Возможные значения:
Более подробно о моделях атрибуции Вы можете узнать в соответствующей статье. |
bindTo | Нет |
Флаг выгрузки звонков с привязкой к разным метрикам. Возможные значения:
|
ani.value | Нет | Телефонный номер звонящего. |
ani.filterMode | Нет | Режим фильтрации предыдущего параметра по номеру звонящего, описание режимов см. ниже. |
phoneNumber.value | Нет | Виртуальный рекламный номер, на который был осуществлен звонок. |
phoneNumber.filterMode | Нет | Режим фильтрации предыдущего параметра по номеру из пула, описание режимов см. ниже. |
manager | Нет |
В качестве его значения можно указать ФИО менеджера, для выгрузки только тех звонков, которым был присвоен этот менеджер ( например с помощью API-метода присвоения менеджеров к лидам). |
uniqueOnly | Нет |
Флаг выгрузки уникальных звонков. Формат:
Если не указывать флаг, то выгружаются все звонки. |
targetOnly | Нет |
Флаг выгрузки целевых звонков. Формат:
Если не указывать флаг, то выгружаются все звонки. |
uniqTargetOnly | Нет |
Флаг выгрузки уникально-целевых звонков. Формат:
Если не указывать флаг, то выгружаются все звонки. |
callbackOnly | Нет |
Флаг выгрузки обратных звонков. Формат:
Если не указывать флаг, то выгружаются все звонки. |
source.value | Нет | Значение источника. |
source.filterMode | Нет | Режим фильтрации предыдущего параметра по источнику, описание режимов см. ниже. |
medium.value | Нет | Значение типа трафика. |
medium.filterMode | Нет | Режим фильтрации предыдущего параметра по типу трафику, описание режимов см. ниже. |
utmSource.value | Нет | Значение utm-метки utm_source. |
utmSource.filterMode | Нет | Режим фильтрации предыдущего параметра по utm-метки utm_source, описание режимов см. ниже. |
utmMedium.value | Нет | Значение utm-метки utm_medium. |
utmMedium.filterMode | Нет | Режим фильтрации предыдущего параметра по utm-метки utm_medium, описание режимов см. ниже. |
utmTerm.value | Нет | Значение utm-метки utm_term. |
utmTerm.filterMode | Нет | Режим фильтрации предыдущего параметра по utm-метки utm_term, описание режимов см. ниже. |
utmContent.value | Нет | Значение utm-метки utm_content. |
utmContent.filterMode | Нет | Режим фильтрации предыдущего параметра по utm-метки utm_content, описание режимов см. ниже. |
utmCampaign.value | Нет | Значение utm-метки utm_campaign. |
utmCampaign.filterMode | Нет | Режим фильтрации предыдущего параметра по utm-метки utm_campaign, описание режимов см. ниже. |
keyword.value | Нет | Значение ключевого слова. |
keyword.filterMode | Нет | Режим фильтрации предыдущего параметра по ключевому слову, описание режимов см. ниже. |
withMapVisits | Нет | Флаг выгрузки истории посещений посетителя, совершившего звонок. Формат: withMapVisits=true - включить в ответ историю посещений, withMapVisits=false или отсутствие параметра - не включать. |
withOrders | Нет | Флаг выгрузки данных по сделкам, связанным со звонками. Формат: withOrders=true - выгрузить данные по связанным сделкам, withOrders=false - не выгружать данные по связанным сделкам, отсутствие параметра – не выгружать. |
orderNumber | Нет | Внешний ID сделки из CRM системы, связанной со звонком. |
withCallTags | Нет |
Флаг отображения тегов звонков. Формат: withCallTags=true - отображать теги, withCallTags=false или отсутствие параметра — не отображать теги. Обратите внимание! Теги передаются по API на момент запроса. Если Вы используете автотегирование Predict или Antifrod, то теги к звонкам присваиваются не сразу, поэтому API запрос на получение тегов Predict или Antifrod рекомендуется производить спустя 1 неделю после звонка. |
additionalTag.name | Нет | Имя дополнительного параметра отслеживания платного трафика. |
additionalTag.value | Нет | Значение дополнительного параметра отслеживания платного трафика. |
additionalTag.filterMode | Нет | Режим фильтрации предыдущего параметра по дополнительному параметру отслеживания платного трафика, описание режимов см. ниже. |
withComments | Нет |
Флаг отображения комментариев к звонкам, оставленных в плеере журнала звонков. Формат:
Комментарии отображаются в выходном параметре comments. |
withYandexDirect | Нет |
Флаг выгрузки данных по рекламным кампаниям Яндекс.Директ. Если входной параметр withYandexDirect = true, то в выгрузке присутствует выходной параметр yandexDirect, если withYandexDirect = false или не указан, то выходной параметр yandexDirect отсутствует. |
withGoogleAdwords | Нет | Флаг выгрузки данных по рекламным кампаниям Google Ads. Если входной параметр withGoogleAdwords = true, то в выгрузке присутствует выходной параметр googleAdWords, если withGoogleAdwords = false или не указан, то выходной параметр googleAdWords отсутствует. |
withAttrs | Нет | Флаг выгрузки сторонних параметров, переданных заранее в статистику Calltouch. Возможные значения: 1. Флаг withAttrs=false или не указан, по умолчанию. Сторонние параметры не выгружаются, значение выходного параметра attrs=null. 2. Флаг withAttrs=true. Сторонние параметры выгружаются в выходной параметр attrs. Если их нет, то значение выходного параметра attrs=null. |
withText | Нет |
Флаг выгрузки разговора звонка в текстовой форме. Формат:
Текст разговора отображается в выходном параметре phrases. |
withCallbackInfo | Нет |
Флаг выгрузки данных ФИО, E-mail, номер телефона, пользовательские поля, полученных из виджетов. Формат:
Данные будут доступны только для обратных звонков в выходном параметре сallbackInfo. Если виджет на заявках или заявки в нерабочее время не прозваниваются, то данные из виджетов доступны в параметре withWidgetInfo выгрузки заявок из ЛК. |
withCustomFields |
Нет |
Флаг выгрузки данных по пользовательским полям. Формат:
Если параметр не указан — по умолчанию false Данные будут доступны в выходном параметре customFields. |
callreferenceId | Нет | Уникальный ID звонка (или несколько через запятую) с Вашей АТС, переданный в параметре callid API-запроса на импорт звонков. |
withDcm | Нет |
Флаг выгрузки данных по интеграции с DoubleClick Campaign Manager. Возможные значения:
По каждому звонку может быть несколько отправок в DCM, в соответствии с настройками интеграции. Поэтому в ответе будет массив данных, каждая отправка будет в отдельном элементе массива. В ответ на запрос к API попадает последняя попытка отправки на момент обращения к нашему API. Формат ответа: 1. Если withDcm не задано или false, то: Где:
|
Регистр параметров строго важен, используйте именно тот, который указан в таблице выше.
К примеру, параметр dateTo будет работать, а параметр dateto уже нет.
Режимы фильтрации
Выборку некоторых параметров выше, имя которых параметр.filterMode, можно дополнительно отфильтровать:
- startwith — начинается с;
- contains — содержит;
- exact — полное соответствие (по умолчанию если фильтр не задан).
Выходные параметры
Имя параметра | Описание |
page |
Используется в постраничном формате выборки данных. Содержит номер страницы. |
pageTotal |
Используется в постраничном формате выборки данных. Содержит общее количество страниц. |
pageSize |
Используется в постраничном формате выборки данных. Содержит значения размера страницы. Если не установлен входной параметр limit, значение по умолчанию равно 1000. |
recordsTotal |
Используется в постраничном формате выборки данных. Содержит общее количество звонков на всех страницах. |
records |
Используется в постраничном формате выборки данных. Содержит запрашиваемые звонки и их выходные параметры, перечисленные ниже в текущей таблице. |
callId | Уникальный идентификатор звонка в Calltouch. |
callphase |
Фаза звонка на момент API запроса:
|
attribution | Модель атрибуции звонков. Возможные значения:
|
callerNumber | Номер звонившего. |
redirectNumber |
Номер переадресации. В случае, если номер переадресации не один (настроена группа обзвона на несколько номеров или номер переадресации зарубежный), то подставится значение "undefined". |
date | Дата звонка. |
manager |
ФИО менеджера, который был присвоен этому звонку с |
waitingConnect | Время ожидания ответа. |
duration | Длительность разговора. |
phoneNumber | Номер, на который звонили. |
subPoolName |
Название сабпула, с которым связан рекламный номер. Если звонок не имеет связи с сабпулом, то в качестве значения будет передано null. |
successful | Статус звонка. Может принимать следующие значения:
|
statusDetails |
Детализация статуса звонка. |
uniqueCall | Уникальный звонок. Может принимать следующие значения:
|
targetCall | Целевой звонок. Может принимать следующие значения:
|
uniqTargetCall | Уникально-целевой звонок. Может принимать следующие значения:
|
callbackCall | Обратный звонок. Может принимать следующие значения:
|
city | Город, в котором находится клиент, совершивший звонок. Определение города происходит по IP-адресу клиента. |
source | Источник. |
medium | Тип трафика. |
keyword | Ключевое слово. |
url | Адрес, по которому попали на сайт. |
callUrl | Адрес страницы, находясь на которой, посетитель совершил звонок. |
ref | Адрес, с которого перешли на сайт. |
hostname |
Отслеживаемый домен или поддомен ресурса, на который был осуществлен переход (например: yoursite.ru). |
utmSource | Значение utm-метки utm_source. |
utmMedium | Значение utm-метки utm_medium. |
utmCampaign | Значение utm-метки utm_campaign. |
utmContent | Значение utm-метки utm_content. |
utmTerm | Значение utm-метки utm_term. |
sessionId | Уникальный идентификатор сессии Calltouch. |
ctCallerId |
Уникальный идентификатор клиента в Calltouch. когда нужно идентифицировать клиента без использования его персональных данных (номер телефона). |
clientId |
Уникальный идентификатор Google Analytics 4. Параметр присутствует в случае, если настроена интеграция Calltouch с Google Analytics 4. |
yaClientId |
Уникальный идентификатор Яндекс.Метрика. Значение параметра не равно null, если настроена выгрузка звонков в Яндекс.Метрика. Обратите внимание! Даже если выгрузка звонков в Яндекс.Метрика настроена, в некоторых случаях Яндекс.Метрика не присваивает свой ИД пользователю:
Значение yaClientId в этих случаях будет равно null. |
sipCallId | Уникальный идентификатор сеанса связи с АТС Calltouch. Его значение отправляется на ваше оборудование в случае использования переадресации по SIP trunk. Может быть полезен при интеграции с вашей АТС. |
userAgent | Информация об устройстве, с которого зашли на сайт. |
ip | IP-адрес посетителя. |
siteId | ID сайта |
mapVisits |
История посещений. Параметр присутствует в случае, если указан входной параметр истории посещений withMapVisits=true. Результат будет содержать все посещения посетителя до и после совершения звонка со следующими данными:
|
orders | Массив всех сделок, связанных со звонком. Для каждой сделки содержит следующие данные:
Создание и редактирование сделок по звонкам осуществляется при этом через отдельный интерфейс API, ознакомиться с инструкцией по которому можно в соответствующей статье. |
additionalTags | Дополнительные параметры отслеживания платного трафика. Содержат следующие данные:
|
callTags[i].names |
Теги звонков, присутствуют в случае, если указан входной параметр withCallTags=true. Параметр содержит следующие данные:
Обратите внимание! Теги передаются по API на момент запроса. Если Вы используете автотегирование Predict или Antifrod, то теги к звонкам присваиваются не сразу, поэтому API запрос на получение тегов Predict или Antifrod рекомендуется производить спустя 1 неделю после звонка. category — устаревший параметр, оставлен в API для обратной совместимости и в ЛК нигде не используется. Теги нужно парсить из callTags[i].names. Если там встречается запятая — это разделить тегов и их там несколько. |
comments |
Комментарии к звонкам, оставленные в плеере журнала звонков. Выгружаются, если присутствует входной параметр withComments=true. Возможные значения:
"comments": [ Где:
Обратите внимание, в конце комментария может присутствовать символ \n. Он означает перенос строки, не забудьте учесть это при парсинге параметров. |
yandexDirect |
Если источник звонка или заявки рекламная кампания Яндекс.Директ, между Calltouch и Яндекс.Директ включена интеграция, то в данном параметре выводится следующая информация:
"yandexDirect": { Пример ответа, когда у звонка или заявки нет этих данных (не настроена интеграция, либо данные еще не собрались): |
googleAdWords | Если источник звонка или заявки рекламная кампания Google Ads, между Calltouch и Google Ads включена интеграция, то в данном параметре выводится следующая информация:
"googleAdWords": { |
attrs | Сторонние параметры, переданные заранее в статистику Calltouch. Выгружаются, если во входных параметрах был передан флаг withAttrs=true. Возможные значения:
attrs: {"param1":"value1","param2"value2"} |
phrases |
Если у звонка имеется текстовая запись разговора, то в данном параметре выгружается массив фраз из звонка (соблюдая последовательность) в формате:
Пример, когда у звонка имеется текстовая запись разговора: "phrases": [ |
phonesInText |
Массив номеров телефонов, полученных из текста разговора (номера были произнесены в ходе разговора). Значение параметра в ответе формируется только при включении соответствующего сеттинга (требуется обратиться к вашему менеджеру). Если сеттинг не включен, или в звонке значение отсутствует (Сервис Calltouch Predict выключен или не успел обработать запись, или номеров в разговоре произнесено не было), то в значении будет null. |
сallbackInfo |
Данные (ФИО, email, номер телефона) из форм обратного звонка, оставленных в соц. сетях VK, Facebook и MyTarget. Выгружаются только для обратных звонков, если был передан входной параметр withCallbackInfo=true. Формат: [ |
customFields |
Данные по пользовательским полям в звонках. Будут в ответе если был передан входной параметр withCustomFields=true. Формат: [ |
callReferenceId | Уникальный ID звонка с Вашей АТС, переданный в параметре callid API-запроса на импорт звонков. |
dcm |
Данные по отправке звонка с DoubleClick Campaign Manager. Формат ответа: 1. Если входной параметр withDcm (см. выше) не задан или false, то: "dcm": null "dcm": [] "dcm": [ Где:
|
ctClientId |
Идентификатор посетителя Calltouch. Он представляет из себя значение нашей куки _ct. Если в звонке значение отсутствует (у лида нет сессии, например, звонок на статический номер), то в значении будет null. |
ctGlobalId
|
Глобальный идентификатор посетителя Calltouch, общий для сайтов, на которых установлен скрипт Calltouch. Он представляет из себя значение сквозной куки _ct_client_global_id. Значение параметра в ответе формируется только при включении соответствующего сеттинга (требуется обратиться к вашему менеджеру). Если сеттинг не включен, или в звонке значение отсутствует (у лида нет сессии, например, звонок на статический номер), то в значении будет null. |
- Данные из Яндекс.Директа и Google Ads подгружаются в Calltouch на следующий день после фиксирования звонка или заявки. Если данные обновляются на стороне Яндекс.Директа или Google AdWords (они могут обновиться 4 раза в месяц), то они будут изменены и в API-выгрузке.
- JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.
- Выгрузка данных осуществляется в соответствии с ограничениями по сегментам у пользователя-владельца токена. Если пользователь имеет ограниченный доступ к ряду сегментов, то в ответе будут присутствовать только те звонки, которые входят в сегменты, доступные пользователю.
Примеры
Пример стандартного запроса с выборкой данных за один день
Запрос
https://api.calltouch.ru/calls-service/RestAPI/11425/calls-diary/calls?clientApiId=2045544541ct93c3c1d6ac73c6c4257fb6a99671dc76&dateFrom=22/11/2016&dateTo=22/11/2016&withCallTags=true&withMapVisits=true
[{"date":"22/11/2016 12:30:57","city":"moscow","utmContent":"","source":"calltouch_test","medium":"test","duration":7,"ref":"","additionalTags":[],"waitingConnect":14,"attribution":1,"keyword":"","successful":true,"order":null,"callId":27175663,"callTags":[{"category":"Тест","names":["Тест"]}],"utmSource":"calltouch_test","callerNumber":"79209191245","ip":"83.220.41.124","utmTerm":"","mapVisits":[{"utmSource":"calltouch_test","sessionDate":"22/11/2016 12:29:34","city":"moscow","ip":"83.220.41.124","utmTerm":"","utmContent":"","userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36","source":"calltouch_test","medium":"test","utmCampaign":"","url":"https://filimonov4.ulovisto.ru/roistat/?utm_source=calltouch_test&utm_medium=test&attrs={\"roistat_visit\":28}","ref":"","additionalTags":[],"utmMedium":"test","keyword":""}],"userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36","sessionId":1596863828,"utmCampaign":"","url":"https://filimonov4.ulovisto.ru/roistat/?utm_source=calltouch_test&utm_medium=test&attrs={\"roistat_visit\":28}","phoneNumber":"74952411502","utmMedium":"test"}]
Пример постраничного запроса для выборки данных более чем за один день
Запрос
https://api.calltouch.ru/calls-service/RestAPI/28968/calls-diary/calls?clientApiId=mD4rd.Nc5JINXrWEDLIi7/jvY/3CR64etYH40DggYFpCo&dateFrom=28/03/2019&dateTo=28/03/2019&withCallTags=true&withMapVisits=true&page=1&limit=2
{
"page": 1,
"pageTotal": 3,
"pageSize": 2,
"recordsTotal": 5,
"records": [
{
"date": "28/03/2019 12:24:28",
"callUrl": null,
"city": "moscow",
"uniqueCall": false,
"redirectNumber": "74953080100",
"callReferenceId": "49185946-513b-11e9-b39a-67ef1c26e87d",
"utmContent": "8",
"yaClientId": null,
"source": "2",
"medium": "4",
"callphase": "calldisconnected",
"duration": 4,
"ref": null,
"additionalTags": [],
"hostname": null,
"waitingConnect": 18,
"ctCallerId": "3a8cd9e5b0b0833809acf953691ad36f",
"callbackCall": false,
"keyword": "10",
"successful": true,
"order": {
"completedAmount": 0,
"completedDate": "28/03/2019",
"createdDate": "28/03/2019",
"orderDate": "28/03/2019 12:24:28",
"orderId": 107833,
"orderNumber": "",
"plannedAmount": 0
},
"callId": 306543,
"callTags": [
{
"category": "",
"type": "AUTO-PN",
"names": [
"Тег по номеру клиента",
"Тег по номеру подмены"
]
},
{
"category": "Мужчина",
"type": "AUTO_GR",
"names": [
"Мужчина"
]
},
{
"category": "Тест от calltouch",
"type": "AUTO-PN",
"names": [
"Тест от calltouch"
]
}
],
"utmSource": "2",
"sipCallId": "2ad49661-cbde-1237-6a8b-005056befeeb",
"callerNumber": "74953080100",
"ip": null,
"utmTerm": "10",
"mapVisits": null,
"userAgent": null,
"sessionId": null,
"utmCampaign": "9",
"url": null,
"attrs": null,
"phoneNumber": "74991166453",
"uniqTargetCall": false,
"targetCall": false,
"attribution": 1,
"utmMedium": "4",
"orders": [
{
"completedAmount": 0,
"completedDate": "28/03/2019",
"createdDate": "28/03/2019",
"orderDate": "28/03/2019 12:24:28",
"orderId": 107833,
"orderNumber": "",
"plannedAmount": 0
},
{
"completedAmount": 0,
"completedDate": "28/03/2019",
"createdDate": "28/03/2019",
"orderDate": "28/03/2019 12:24:28",
"orderId": 107835,
"orderNumber": "",
"plannedAmount": 0
}
]
},
{
"date": "28/03/2019 13:28:38",
"callUrl": null,
"city": "moscow",
"uniqueCall": false,
"redirectNumber": "79051453074",
"callReferenceId": "4029f32c-5144-11e9-a2ae-67ef1c26e87d",
"utmContent": "8",
"yaClientId": null,
"source": "2",
"medium": "4",
"callphase": "calldisconnected",
"duration": 19,
"ref": null,
"additionalTags": [],
"hostname": null,
"waitingConnect": 10,
"ctCallerId": "3a8cd9e5b0b0833809acf953691ad36f",
"callbackCall": false,
"keyword": "10",
"successful": true,
"order": {
"completedAmount": 0,
"completedDate": "28/03/2019",
"createdDate": "28/03/2019",
"orderDate": "28/03/2019 13:28:38",
"orderId": 107915,
"orderNumber": "",
"plannedAmount": 0
},
"callId": 307570,
"callTags": [
{
"category": "",
"type": "AUTO-PN",
"names": [
"Тег по номеру клиента",
"Тег по номеру подмены"
]
},
{
"category": "Мужчина",
"type": "AUTO_GR",
"names": [
"Мужчина"
]
},
{
"category": "Тест от calltouch",
"type": "AUTO-PN",
"names": [
"Тест от calltouch"
]
}
],
"utmSource": "2",
"sipCallId": "17a2475c-cbe7-1237-6a8b-005056befeeb",
"callerNumber": "74953080100",
"ip": null,
"utmTerm": "10",
"mapVisits": null,
"userAgent": null,
"sessionId": null,
"utmCampaign": "9",
"url": null,
"attrs": null,
"phoneNumber": "74991166453",
"uniqTargetCall": false,
"targetCall": false,
"attribution": 1,
"utmMedium": "4",
"orders": [
{
"completedAmount": 0,
"completedDate": "28/03/2019",
"createdDate": "28/03/2019",
"orderDate": "28/03/2019 13:28:38",
"orderId": 107915,
"orderNumber": "",
"plannedAmount": 0
},
{
"completedAmount": 0,
"completedDate": "28/03/2019",
"createdDate": "28/03/2019",
"orderDate": "28/03/2019 13:28:38",
"orderId": 107917,
"orderNumber": "",
"plannedAmount": 0
}
]
}
]
}
Пример запроса с указанием модели атрибуции
В зависимости от модели атрибуции (см. статью Настройки модели атрибуции), источник звонка может меняться. В данном примере посетитель вначале зашел на сайт с платного трафика google cpc, добавил сайт в закладки и спустя продолжительное время вернулся на сайт уже с прямого перехода (direct) (none) из закладок. По умолчанию источник этого звонка в API будет выгружен по модели атрибуции "Последний непрямой", в данном примере google cpc. Но можно изменить модель атрибуции, используемые в API, на "Последнее взаимодействие", добавив параметр attribution=0, после чего источник определится уже по последней сессии, в данном примере (direct) (none).
- Атрибуция "Последний непрямой", используемая по умолчанию, входной параметр attribution не задан либо равен 1:
Запрос
https://api.calltouch.ru/calls-service/RestAPI/12612/calls-diary/calls?clientApiId=635827914ct091afc00b014daa66744996b9621e09e&dateFrom=14/02/2017&dateTo=14/02/2017&callId=2061644
[{"callId":20616445,"date":"14/02/2017 17:17:59","utmSource":"google","callerNumber":"79209367891","city":"vladimir","ip":"95.66.182.68/32","utmTerm":"<не заполнено>","utmContent":"<не заполнено>","userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36","sessionId":1256826731,"source":"google","medium":"cpc","utmCampaign":"<не заполнено>","url":"https://4dev.online/calltouchtest/?utm_source=google&utm_medium=cpc&specific_id=1","duration":13,"ref":"","additionalTags":[],"phoneNumber":"74952414029","waitingConnect":13,"attribution":1,"utmMedium":"cpc","keyword":"<не заполнено>","successful":true,"order":null}]
- Атрибуция "Последнее взаимодействие", входной параметр attribution равен 0:
Запрос
https://api.calltouch.ru/calls-service/RestAPI/12612/calls-diary/calls?clientApiId=635827914ct091afc00b014daa66744996b9621e09e&dateFrom=14/02/2017&dateTo=14/02/2017&callId=20616445&attribution=0
Ответ
[{"callId":20616445,"date":"14/02/2017 17:17:59","utmSource":"<не указано>","callerNumber":"79209367891","city":"vladimir","ip":"95.66.182.68/32","utmTerm":"<не указано>","utmContent":"<не указано>","userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36","sessionId":1256834386,"source":"(direct)","medium":"(none)","utmCampaign":"<не указано>","url":"https://4dev.online/calltouchtest/?specific_id=1","duration":13,"ref":"","additionalTags":[],"phoneNumber":"74952414029","waitingConnect":13,"attribution":0,"utmMedium":"(none)","keyword":"(not set)","successful":true,"order":null}]
Ошибки API
Код ошибки | Описание и предлагаемое решение |
HTTP Status 500 / Forbidden | Illegal access - неверные авторизационные данные. Необходимо проверить актуальность clientApiId или siteId. |
HTTP Status 400 / Bad Request |
The request sent by the client was syntactically incorrect — синтаксическая ошибка в запросе, подробности ошибки выводятся в выходном параметре message. Необходимо проверить корректность входных параметров. Так же может возникать, если API-запрос осуществляется к отключенному сайту. |
HTTP Status 404 | The requested resource is not available — запрошенный ресурс недоступен, обращение к несуществующей директории. Необходимо обратиться в техническую поддержку Calltouch, отправив заявку на нашу почту info@calltouch.net. |
Система баллов API Calltouch
Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов
За каждый успешно выполненный запрос списываются баллы.
Подробнее читайте в статье: Система баллов API Calltouch
Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).
- A/B тестирование (раздел «Подключение»)
- Email-трекинг (раздел «Подключение»)
- Отслеживание офлайн конверсии (раздел «Подключение»)
- Подключение к отслеживанию дополнительных доменов (раздел «Подключение»)
- Подмена номеров на AMP-страницах Google (раздел «Подключение»)