Документация API CallTracking Calls

CallTracking API позволяет получать полную информацию по звонкам как из сервиса CallTracking, так и из сервиса CallKeeper. Запрос осуществляется методом GET.

Методы

Для использования методов следует передать имя выбранного метода в параметр method. К API CallTracking с целью получения звонков следует обращаться с помощью одного из трех методов: get, getByRole, getWithRole.

?format/version/apikey/entity/method/pages/from/to&length=10

• get



Для получения принадлежащих пользователю звонков указывается метод get. Пример получения звонков, принадлежащих пользователю без учета ролей, в формате JSON с 1 января по 20 марта 2021, страница с индексом 0:

https://ckct.ru/api/index.php?json/v3/51lVB9PiAoOC6j72/call/get/0/2021-01-01/2021-03-20



Пример получения звонков, принадлежащих пользователю без учета ролей, в формате JSON с 10 февраля по 20 марта 2021, страница с индексом 1:

https://ckct.ru/api/index.php?json/v3/51lVB9PiAoOC6j72/call/get/1/2021-02-10/2021-03-20


• getByRole



Для получения звонков только по роли указывается метод getByRole (при использовании данного параметра, в ключе apikey следует передать ключ, выданный по роли, а не ключ пользователя). Пример получения звонков, выданных пользователю по роли, в формате JSON с 1 января по 20 марта 2021, страница с индексом 0:

https://ckct.ru/api/index.php?json/v3/dc97970ec0d3aa6b/call/getByRole/0/2021-01-01/2021-03-20



Пример получения звонков, выданных пользователю по роли, в формате JSON с 1 мая 2020 по 20 марта 2021, страница с индексом 2:

https://ckct.ru/api/index.php?json/v3/dc97970ec0d3aa6b/call/getByRole/2/2020-05-01/2021-03-20


• getWithRole



Для получения звонков пользователя вместе со звонками по роли следует указать метод getWithRole. Пример получения всех звонков, как выданных пользователю по роли, так и принадлежащих непосредственно пользователю, в формате JSON с 1 января по 20 марта 2021, страница с индексом 0:

https://ckct.ru/api/index.php?json/v3/51lVB9PiAoOC6j72/call/getWithRole/0/2021-01-01/2021-03-20



Пример получения всех звонков, как выданных пользователю по роли, так и принадлежащих непосредственно пользователю, в формате JSON с 1 января по 20 марта 2021, страница с индексом 1:

https://ckct.ru/api/index.php?json/v3/51lVB9PiAoOC6j72/call/getWithRole/1/2020-01-01/2021-03-20

Параметры запроса

• format - формат данных в котором вы хотите получить информацию по звонкам. На данный момент доступен только формат json.
• version - версия API. Может иметь значения v1, v2 и v3. Актуальная версия в настоящее время - это v3, в запросах следует указывать именно ее.
• apikey - секретный ключ для доступа к API. Его можно получить у своего менеджера. Ключ представляет собой буквенно-числовую последовательность длинной 16 символов.
• entity - сущности, к которым запрашивается доступ. Для получения звонков пользователя указывается call.
• method - запрашиваемый метод. Для получения принадлежащих пользователю звонков указывается get. Для получения звонков только по роли указывается getByRole (при использовании данного параметра, в ключе apikey следует передать ключ, выданный по роли, а не ключ пользователя). Для получения звонков пользователя вместе со звонками по роли следует указать getWithRole.
• pages - если у пользователя много звонков, то выводить в ответе сразу все было бы не эффективно, по этому вывод сделан постранично. На одной странице содержится 1000 звонков. В данном параметре вы можете указать номер конкретной страницы, которую хотите получить, это десятичное число. Нумерация страниц начинается с 0.
• from - параметр устанавливает начальную дату выборки. Его можно передавать в двух форматах. В виде timestamp (например 1588854585), либо в формате "yyyy-mm-dd" (например 2020-05-07).
• to - параметр устанавливает дату конца выборки. Имеет тот же формат что и предыдущий параметр.
• length - параметр позволяет указать количество звонков в ответе. Минимум - 1, максимум - 10000, значение по-уполчанию - 1000

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

Формат ответа представляет из себя массив звонков в формате JSON

[
  {
    "page": 1,
    "universalId": "23423423434434234",
    "serviceType": "calltracking",
    "clientNumber": "7999999999",
    "managerNumber": "7888888888",
    "callerIdToManager": "79999999999",
    "callerIdToClient": "79999999999",
    "statusFirst": 200,
    "statusSecond": 200,
    "status": "success",
    "callTime": "2020-04-05 13:23:32",
    "localDate": "2020-04-05 15:23:32",
    "timezoneOffset": "+0020",
    "duration": 152,
    "tariffTime": 3,
    "site": "mysite.ru",
    "recordUrl": "https://callkeeper.ru/record",
    "unique": true,
    "target": true,
    "uniqueTarget":  false,
    "visitSite": "callkeeperr.ru",
    "referrer": "search.ru",
    "utm_source": "search",
    "utm_medium": "cpc",
    "utm_campaign": "advert",
    "utm_content": "goods",
    "utm_term": "some info",
    "yaClid": "534543523543",
    "gaClid": "345345353.234234234",
    "roistatClid": "323423423",
    "calltouchClid": "234234234",
    "comagicClid": "34223234",
    "city": "Москва",
    "region": "Москва",
    "country": "Россия",
    "ipAddress": "127.0.0.1",
    "pagesCount": 5,
    "entryPoint": "https://callkeeper.ru/blog",
    "entryPointQuery": "https://callkeeper.ru/call-tracking/",
    "callPage": "https://callkeeper.ru/calls",
    "counts": 12,
    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)",
    "device": "iphone 7",
    "cbWidgetHash": "xxx99xx99xxxxx999xxxxxx9999xxx99",
    "cbToolId": 1000,
    "cbCallId": 10000000,
    "cbUid": 1000,
    "cbToolName": "Виджет обратного звонка",
    "cbSmatrisSession": 62345,
    "cbOfficeNumber": "0",
    "cbOfficeName": "Moscow office",
    "cbOrderDate":  "2020-05-04 12:13:22",
    "cbAttempt": 3,
    "cbAttemptsQueue": [
      10000000,
      11111111
    ],
    "cbConnectType": "smartcall",
    "cbSmartCallCount": 5,
    "cbIvrCount": 12,
    "cbEventSource":  "api",
    "ctCallId": 100000,
    "ctCampaignId": 1000,
    "ctCampaignName": "sale",
    "ctIsListened": "1",
    "tags": [
      "some tag",
      "any tag"
    ],
  }
]
                    

Описание полей

Возвращаемые данным методом значения описаны в следующем порядке:

имя параметра - описание параметра (тип данных)

Если параметр может принимать одно из нескольких значений, то они будут перечислены через запятую.

Ни один из параметров не принимает значение NULL. В случае если параметр пустой, то вместо NULL у строковых значений будет пустая строка, у числовых значений - 0, у массивов - пустой массив.

В ответе есть параметры, специфичные для сервиса Callback, они обозначаются префиксом "cb" перед названием параметра.

Также есть параметры, специфичные для сервиса CallTracking, они обозначены префиксом "ct". Параметры без этих префиксов являются общими для обоих сервисов.

• page - номер текущей страницы (INT)
• universalId – универсальный id звонка в callback и calltracking (STRING)
• serviceType – текстовое название сервиса ("callback","calltracking","import")
• clientNumber – номер телефона клиента (STRING)
• managerNumber – реальный (не подстановочный) номер дилерского центра (STRING)
• callerIdToManager – номер который подставится в сторону менеджера (STRING)
• callerIdToClient – номер который подставится в сторону клиента (STRING)
• statusFirst – статус звонка оператору (для callback) или на подстановочный номер (для calltracking) (INT)
• statusSecond - статус звонка клиенту (для callback) или на номер переадресации (для calltracking) (INT)
• status - статус звонка, успешный или не успешный ("success", "fail")
• callTime – дата и время звонка (DATE)
• localDate - дата и время в часовом поясе клиента (DATE)
• timezoneOffset - смещение часового пояса (STRING)
• duration – время разговора в секундах (INT)
• tariffTime - таррифицируемое время разговора в минутах (INT)
• site – сайт из настроек виджета или из кампании (STRING)
• recordUrl – ссылка на запись разговора (STRING)
• unique – уникальный ли звонок (BOOL)
• target – целевой ли звонок (BOOL)
• uniqueTarget – уникально-целевой ли звонок (BOOL)
• siteVisit – сайт на который был визит с последующим звонком (STRING)
• referrer – сайт с которого был переход (STRING)
• utm_source – рекламная метка utm_source (STRING)
• utm_medium – рекламная метка utm_medium (STRING)
• utm_campaign – рекламная метка utm_campaign (STRING)
• utm_content – рекламная метка utm_content (STRING)
• utm_term - рекламная метка utm_term (STRING)
• yaClid – идентификатор клиента в сервисе Яндекс.Метрика (STRING)
• gaClid – идентификатор клиента в сервисе Google analytics (STRING)
• roistatClid – идентификатор клиента в сервисе Roistat (STRING)
• comagicClid – идентификатор клиента в сервисе Comagic (STRING)
• calltouchClid – идентификатор клиента в сервисе Calltouch (STRING)
• city – город нахождения посетителя (STRING)
• region – регион нахождения посетителя (STRING)
• country – cтрана нахождения посетителя (STRING)
• ipAddress - ip адрес посетителя (STRING)
• pagesCount – количество страниц на которые зашел пользователь за визит (INT)
• entryPoint – страница входа на сайт (STRING)
• entryPointQuery – страница входа вместе с гет параметрами (STRING)
• callPage – страница с которой был совершен или заказан звонок (STRING)
• counts – всего количество визитов этого пользователя на сайт (INT)
• userAgent – user agent строка идентифицирующая браузер посетителя (STRING)
• device – тип устройства (STRING)
• cbWidgetHash – уникальный хэш виджета (STRING)
• cbToolId – id виджета (INT)
• cbCallId – id звонка (INT)
• cbUid - id аккаунта (INT)
• cbToolName – название инструмента с которого был заказан звонок (INT)
• cbOfficeNumber – порядковый номер офиса (INT)
• cbOfficeName – название офиса (STRING)
• cbOrderDate – дата заказа звонка (DATE)
• cbAttempt – номер попытки дозвона (INT)
• cbAttemptsQueue – id звонков предыдущих попыток дозвона (ARRAY[INT])
• cbConnectType – тип соединения ("auto","smartcall","dtmf")
• cbSmartCallCount – количество попыток распознавания smartcall или dtmf (INT)
• cbSmatrisSession – уникальный номер сессии Smartis (INT)
• cbIvrCount – количество повторений ivr (INT)
• cbEventSource – инструмент, с которого был заказан звонок ("widget","mobile","api","lg","iform","form","ckapp","hand","fb","vk","ok")
• ctCallId – id звонка в коллтреккинге (INT)
• ctCampaignId – id кампании в коллтреккинге (INT)
• ctCampaignName – название кампании (STRING)
• ctIsListened – прослушана ли запись ("","0","1")
• tags – массив тэгов, присвоенных звонку (ARRAY[STRING])

Дополнительно

Все возможные статусы по звонкам доступны по ссылке.

Формат ошибок

В случае неуспешного запроса, вернется ответ следующего формата:

{
  "inbound": {
    "error": "No rows found"
  },
  "info": {
    "entities": {
      "call": ["get"],
      "callrole": ["get"],
      "phone": ["get"],
      "user": ["get"],
      "campaign": ["get"],
      "tag": ["get"]
    },
    "types": ["json", "plain", "csv", "xml"],
    "versions": ["v1"]
  },
  "payload": []
}

В данном ответе поле "info" носит информационный характер, и во всех неуспешных запросах оно будет одинаковое. Поле "payload" также во всех неудачных запросах будет пустым, что означает, что данных в ответе нет.

Значимым для обработки неуспешного ответа является лишь поле "inbound". В случае невалидного запроса оно будет содержать ключ "error", в котором будет находится текстовое описание ошибки.

Описание возможных ошибок при запросах к API

1. Не найдено звонков за выбранный период, или звонков у данного пользователя не существует

   "error": "No rows found"

2. Параметр format в запросе отсутствует либо неверный

   "error":"Type to return is not available"

3. Параметр version в запросе отсутствует либо неверный

   "error":"Type to return is not available"

4. Параметр apikey в запросе отсутствует либо неверный

   "error":"User is not recognized"

5. Параметр entity в запросе отсутствует либо неверный

   "error":"Entity does not exist"

6. Параметр method в запросе отсутствует либо неверный

   "error":"Method does not exist"

7. Параметр pages в запросе отсутствует, либо неверный, либо он превышает количество страниц в ответе

   "error":"Incorrect page is set"

8. Параметр from в запросе отсутствует, либо неверный, либо он превышает количество страниц в ответе

   "error":"Start date has wrong type. Possible format is 'Y-m-d' or timestamp"