Выгрузка журнала звонков

Читать 37

Назначение 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, если настроена выгрузка звонков в Яндекс.Метрика.

Обратите внимание! Даже если выгрузка звонков в Яндекс.Метрика настроена, в некоторых случаях Яндекс.Метрика не присваивает свой ИД пользователю:

  • Счетчик Яндекс.Метрика не установлен на сайт.
  • Счетчик установлен неправильно.
  • Работу счетчика Яндекс.Метрика на сайте блокируют другие скрипты. Проверить это можно в консоли браузера.
  • Счетчик заблокирован расширением Adblock Plus.
  • Домен mc.yandex.ru заблокирован в файле hosts вашей ОС.

Значение yaClientId в этих случаях будет равно null.

callId Нет Список уникальных идентификаторов звонка в системе Calltouch. Допустимо вводить несколько значений, разделенные знаком ",". Формат: callId=XXX,YYY,ZZZ,...
attribution Нет

Модель атрибуции звонков. Возможные значения:

  • 0 — последнее взаимодействие;
  • 1 — последний непрямой (по умолчанию, если параметр не указан).

Более подробно о моделях атрибуции Вы можете узнать в соответствующей статье.

bindTo Нет

Флаг выгрузки звонков с привязкой к разным метрикам. Возможные значения:

  • call — по дате звонков (по умолчанию);
  • session — по дате сессий.
ani.value Нет Телефонный номер звонящего.
ani.filterMode Нет Режим фильтрации предыдущего параметра по номеру звонящего, описание режимов см. ниже.
phoneNumber.value Нет Виртуальный рекламный номер, на который был осуществлен звонок.
phoneNumber.filterMode Нет Режим фильтрации предыдущего параметра по номеру из пула, описание режимов см. ниже.
manager Нет

В качестве его значения можно указать ФИО менеджера, для выгрузки только тех звонков, которым был присвоен этот менеджер ( например с помощью API-метода присвоения менеджеров к лидам).

uniqueOnly Нет

Флаг выгрузки уникальных звонков. Формат:

  • uniqueOnly=true — выгружаются только уникальные;
  • uniqueOnly=false — выгружаются только повторные.

Если не указывать флаг, то выгружаются все звонки.

targetOnly Нет

Флаг выгрузки целевых звонков. Формат:

  • targetOnly=true — выгружаются только целевые;
  • targetOnly=false — выгружаются только нецелевые.

Если не указывать флаг, то выгружаются все звонки.

uniqTargetOnly Нет

Флаг выгрузки уникально-целевых звонков. Формат:

  • uniqTargetOnly=true — выгружаются только уникально-целевые;
  • uniqTargetOnly=false — выгружаются только не уникально-целевые.

Если не указывать флаг, то выгружаются все звонки.

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 Нет

Флаг отображения комментариев к звонкам, оставленных в плеере журнала звонков. Формат:

  • withComments=true — отображать комментарии;
  • withComments=false или отсутствие параметра — не отображать комментарии.

Комментарии отображаются в выходном параметре 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 Нет

Флаг выгрузки разговора звонка в текстовой форме. Формат:

  • withText=true — отображать текст разговора;
  • withText=false или отсутствие параметра — не отображать текст разговора.

Текст разговора отображается в выходном параметре phrases.

withCallbackInfo Нет

Флаг выгрузки данных ФИО, E-mail, номер телефона, пользовательские поля, полученных из виджетов.
Для виджетов лид-форм Facebook, VK также выгружаются id лида и id объявления.

Формат:

  • withCallbackInfo=true — выгружать данные;
  • withCallbackInfo=false или отсутствие параметра — не выгружать данные.

Данные будут доступны только для обратных звонков в выходном параметре сallbackInfo.

Если виджет на заявках или заявки в нерабочее время не прозваниваются, то данные из виджетов доступны в параметре withWidgetInfo выгрузки заявок из ЛК.

withCustomFields
Нет

Флаг выгрузки данных по пользовательским полям.

Формат:

  • withCustomFields=true — выгружать данные по пользовательским полям;
  • withCustomFields=false — не выгружать данные.

Если параметр не указан — по умолчанию false

Данные будут доступны в выходном параметре customFields.

callreferenceId Нет  Уникальный ID звонка (или несколько через запятую) с Вашей АТС, переданный в параметре callid API-запроса на импорт звонков.
withDcm Нет

Флаг выгрузки данных по интеграции с DoubleClick Campaign Manager. Возможные значения:

  • true — выгрузить данные по отправке звонка в DCM;
  • false — не выгружать данные.

По каждому звонку может быть несколько отправок в DCM, в соответствии с настройками интеграции. Поэтому в ответе будет массив данных, каждая отправка будет в отдельном элементе массива. В ответ на запрос к API попадает последняя попытка отправки на момент обращения к нашему API.

Формат ответа:

1. Если withDcm не задано или false, то:
"dcm": null
2. Если withDcm=true, но не было отправок в DCM, то:
"dcm": []
3. Если withDcm=true, отправки были, то:
"dcm": [
{
"profileIdDCM": 1411789,
"floodlightConfigurationId": "10355394",
"floodlightActivityId": "10501143",
"requestStatus": "ERROR",
"requestErrors": "HTTP_AUTH_ERROR"
}
]

Где:

  • profileIdDCM — идентификатор профиля DCM;
  • floodlightConfigurationId — конфигурация из DCM;
  • floodlightActivityId — идентификатор флудлайта;
  • requestStatus — статус отправки звонка в DCM. Возможные значения:
    • success — успешная отправка;
    • error — отправка, завершенная ошибкой.
  • requestErrors — описание ошибки отправки звонка в DCM, если она возникает. Если нет, то значение будет null.

Регистр параметров строго важен, используйте именно тот, который указан в таблице выше.
К примеру, параметр dateTo будет работать, а параметр dateto уже нет.

Режимы фильтрации

Выборку некоторых параметров выше, имя которых параметр.filterMode, можно дополнительно отфильтровать:

  • startwith — начинается с;
  • contains — содержит;
  • exact — полное соответствие (по умолчанию если фильтр не задан).

Выходные параметры

Имя параметра Описание
page

Используется в постраничном формате выборки данных.

Содержит номер страницы.

pageTotal

Используется в постраничном формате выборки данных.

Содержит общее количество страниц.

pageSize

Используется в постраничном формате выборки данных.

Содержит значения размера страницы. Если не установлен

входной параметр limit, значение по умолчанию равно 1000.

recordsTotal

Используется в постраничном формате выборки данных.

Содержит общее количество звонков на всех страницах.

records

Используется в постраничном формате выборки данных.

Содержит запрашиваемые звонки и их выходные параметры,

перечисленные ниже в текущей таблице.

callId Уникальный идентификатор звонка в Calltouch.
callphase

Фаза звонка на момент API запроса:

  • callconnected - звонок сейчас идет в реальном времени
  • calldisconnected - звонок завершен
attribution Модель атрибуции звонков. Возможные значения:
  • 0 — последнее взаимодействие;
  • 1 — последний непрямой (по умолчанию).
Более подробно о моделях атрибуции Вы можете узнать в соответствующей статье.
callerNumber Номер звонившего.
redirectNumber

Номер переадресации. В случае, если номер переадресации

не один (настроена группа обзвона на несколько номеров

или номер переадресации зарубежный), то подставится значение "undefined".

date Дата звонка.
manager

ФИО менеджера, который был присвоен этому звонку с

помощью API-метода присвоения менеджеров к лидам.

waitingConnect Время ожидания ответа.
duration Длительность разговора.
phoneNumber Номер, на который звонили.
subPoolName
Название сабпула, с которым связан рекламный номер.
Если звонок не имеет связи с сабпулом, то в качестве значения будет передано null.
successful Статус звонка. Может принимать следующие значения:
  • true (звонок удачный);
  • false (звонок неудачный).
statusDetails
Детализация статуса звонка.
uniqueCall Уникальный звонок. Может принимать следующие значения:
  • true (уникальный звонок);
  • false (повторный звонок).
targetCall Целевой звонок. Может принимать следующие значения:
  • true (целевой звонок);
  • false (нецелевой звонок).
uniqTargetCall Уникально-целевой звонок. Может принимать следующие значения:
  • true (уникально-целевой звонок);
  • false (не уникально-целевой звонок).
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, если настроена выгрузка звонков в Яндекс.Метрика.

Обратите внимание! Даже если выгрузка звонков в Яндекс.Метрика настроена, в некоторых случаях Яндекс.Метрика не присваивает свой ИД пользователю:

  • Счетчик Яндекс.Метрика не установлен на сайт.
  • Счетчик установлен неправильно.
  • Работу счетчика Яндекс.Метрика на сайте блокируют другие скрипты. Проверить это можно в консоли браузера.
  • Счетчик заблокирован расширением Adblock Plus.
  • Домен mc.yandex.ru заблокирован в файле hosts вашей ОС.

Значение yaClientId в этих случаях будет равно null.

sipCallId Уникальный идентификатор сеанса связи с АТС Calltouch. Его значение отправляется на ваше оборудование в случае использования переадресации по SIP trunk. Может быть полезен при интеграции с вашей АТС.
userAgent Информация об устройстве, с которого зашли на сайт.
ip IP-адрес посетителя.
siteId ID сайта
mapVisits

История посещений. Параметр присутствует в случае, если указан входной параметр истории посещений withMapVisits=true. Результат будет содержать все посещения посетителя до и после совершения звонка со следующими данными:

  • sessionDate (дата начала сессии посетителя на сайте);
  • sessionID;
  • ip;
  • userAgent;
  • sessionId;
  • city;
  • source;
  • medium;
  • keyword;
  • url;
  • ref;
  • utmMedium;
  • utmSource;
  • utmTerm;
  • utmContent;
  • utmCampaign;
  • guaClientId (уникальный идентификатор Universal Analytics, он же clientId);
  • ctClientId;
  • ctGlobalId.
orders Массив всех сделок, связанных со звонком. Для каждой сделки содержит следующие данные:
  • createdDate (дата создания контракта);
  • completedDate (дата подписания контракта);
  • orderDate (дата заказа);
  • orderNumber (номер заказа);
  • plannedAmount (планируемая сумма контракта);
  • completedAmount (реальная сумма контракта);
  • orderId (ID сделки в Calltouch).

Создание и редактирование сделок по звонкам осуществляется при этом через отдельный интерфейс API, ознакомиться с инструкцией по которому можно в соответствующей статье.

additionalTags Дополнительные параметры отслеживания платного трафика. Содержат следующие данные:
  • name (имя дополнительного параметра отслеживания платного трафика);
  • value (значение дополнительного параметра отслеживания платного трафика).
callTags[i].names

Теги звонков, присутствуют в случае, если указан входной параметр withCallTags=true. Параметр содержит следующие данные:

  • category (категория тега, по умолчанию равна имени тега);
  • names (имя тега).

Обратите внимание! Теги передаются по API на момент запроса. Если Вы используете автотегирование Predict или Antifrod, то теги к звонкам присваиваются не сразу, поэтому API запрос на получение тегов Predict или Antifrod рекомендуется производить спустя 1 неделю после звонка.

category — устаревший параметр, оставлен в API для обратной совместимости и в ЛК нигде не используется.

Теги нужно парсить из callTags[i].names. Если там встречается запятая — это разделить тегов и их там несколько.

comments

Комментарии к звонкам, оставленные в плеере журнала звонков. Выгружаются, если присутствует входной параметр withComments=true. Возможные значения:

  • Если у звонка не будет комментариев, значение параметра будет в виде пустого массива:
    "comments": []
  • Если у звонка будут комментарии, значение параметра будет массив комментариев:
"comments": [
{
"commentId": 611916,
"callId": 31435734,
"comment": "Комментарий 1\n",
"partyId": 882,
"partyName": "login_1"
},
{
"commentId": 611917,
"callId": 31435734,
"comment": "Комментарий 2\n",
"partyId": 7309,
"partyName": "login_2"
},
...
]

Где:
  • commentId — ид комментария (число);
  • callId — ид звонка, по которому оставлен комментарий (число);
  • comment — комментарий (строка);
  • partyId — ид пользователя, оставившего комментарий (число);
  • partyName — логин пользователя, оставившего комментарий (строка).

Обратите внимание, в конце комментария может присутствовать символ \n. Он означает перенос строки, не забудьте учесть это при парсинге параметров.

yandexDirect

Если источник звонка или заявки рекламная кампания Яндекс.Директ, между Calltouch и Яндекс.Директ включена интеграция, то в данном параметре выводится следующая информация:

  • campaignId — ID кампании;
  • adGroupId — ID группы;
  • adId — ID объявления;
  • criteriaId — ID фразы.
    Пример ответа, когда у звонка или заявки есть эти данные:
"yandexDirect": {
 "campaignId": 32515134,
 "adGroupId": 325245212134,
 "adId": 2546356252,
 "criteriaId": 254251323
}

Пример ответа, когда у звонка или заявки нет этих данных (не настроена интеграция, либо данные еще не собрались):

googleAdWords Если источник звонка или заявки рекламная кампания Google Ads, между Calltouch и Google Ads включена интеграция, то в данном параметре выводится следующая информация:
  • campaignId — ID кампании
  • adGroupId — ID группы
  • creativeId — ID объявления
  • criteriaId — ID фразы
    Пример ответа, когда у звонка или заявки есть эти данные:
"googleAdWords":
{
"campaignId": 35635656,
"adGroupId": 134524245,
"creativeId": 23134141,
"criteriaId": 4324553542
}
attrs Сторонние параметры, переданные заранее в статистику Calltouch. Выгружаются, если во входных параметрах был передан флаг withAttrs=true. Возможные значения: attrs: {"param1":"value1","param2"value2"}
phrases

Если у звонка имеется текстовая запись разговора, то в данном параметре выгружается массив фраз из звонка (соблюдая последовательность) в формате:

  • channel — канал (1 - оператор, 0 - клиент)
  • time — временная метка начала фразы в формате ММ:СС
  • message — текст фразы

Пример, когда у звонка имеется текстовая запись разговора:

"phrases": [
   {
        "channel": 1,
        "time": "00:01",
        "message": "здравствуйте вы позвонили в компанию кола если вы всё ещё не используете наш сервис нажмите один если"
   },
   {
        "channel": 1,
        "time": "00:36",   
        "message": "добрый день какое кол ельвира слушаю вас"
  },
   {
      "channel": 0,
       "time": "00:36",
       "message": "добрый день дарья алексеевна я могу услышать"
   },
   {
      "channel": 1,
      "time": "00:42",
      "message": "а не по работе ден начинается десяти часов она еще не на месте"
   },
   {
      "channel": 0,
     "time": "00:48",
     "message": "хорошо благодарю спасибо"
   }, 
  {
      "channel": 1,
      "time": "00:50",
     "message": "всего доброго до свидания"
  }
]
phonesInText

Массив номеров телефонов, полученных из текста разговора (номера были произнесены в ходе разговора). Значение параметра в ответе формируется только при включении соответствующего сеттинга (требуется обратиться к вашему менеджеру). Если сеттинг не включен, или в звонке значение отсутствует (Сервис Calltouch Predict выключен или не успел обработать запись, или номеров в разговоре произнесено не было), то в значении будет null.

сallbackInfo

Данные (ФИО, email, номер телефона) из форм обратного звонка, оставленных в соц. сетях VK, Facebook и MyTarget. Выгружаются только для обратных звонков, если был передан входной параметр withCallbackInfo=true.

Формат:

[
    {
        ...
       "сallbackInfo" : {
         "fields": [
             {"name":"Имя", "value": "Дуся" },
             {"name": "Электронный адрес", "value": "mail@examle.ru" },
          ]
        }
      ...
   }
]
customFields

Данные по пользовательским полям в звонках. Будут в ответе если был передан входной параметр withCustomFields=true.

Формат:

[
    {
        ...
       "customFields": [
            {"field": "name", "value": "Вася"},
      {"field": "birthday", "value": "1990-01-01"}
        ]
      ...
   }
]

callReferenceId Уникальный ID звонка с Вашей АТС, переданный в параметре callid API-запроса на импорт звонков.
dcm

Данные по отправке звонка с DoubleClick Campaign Manager.

Формат ответа:

1. Если входной параметр withDcm (см. выше) не задан или false, то:

"dcm": null  
2. Если withDcm=true, но не было отправок в DCM, то:
"dcm": []  
3. Если withDcm=true, отправки были, то:
"dcm": [
{
"profileIdDCM": 1411789,
"floodlightConfigurationId": "10355394",
"floodlightActivityId": "10501143",
"requestStatus": "ERROR",
"requestErrors": "HTTP_AUTH_ERROR"
}
]

Где:

  • profileIdDCM — идентификатор профиля DCM
  • floodlightConfigurationId — конфигурация из DCM
  • floodlightActivityId — идентификатор флудлайта
  • requestStatus — статус отправки звонка в DCM. Возможные значения:
    • success — успешная отправка
    • error — отправка, завершенная ошибкой
  • requestErrors — описание ошибки отправки звонка в DCM, если она возникает. Если нет, то значение будет null.
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).

Не нашли решение проблемы?
Заполните форму, и мы вам поможем.