API Динамического коллтрекинга

API Динамического коллтрекинга

Преимущества использования API

1.     Данное API используется нашими партнерами-рекламными агентствами для получения информации из коллтрекинга и загрузки информации о звонках в свои системы. Поэтому, если Вы являетесь клиентом рекламного агентства Вы можете запросить у них информацию по количеству звонков в вашу компанию в разрезе каналов продвижения и рекламных кампаний.

2.       Через данное API мы передаем информацию о звонках с utm-метками и другой информацией в популярные биддеры. Т.о. в них становится возможным оптимизация ставок для повышения конверсии в звонки. Если ваша система еще не подключена, Вы можете с помощью данной инструкции ее подключить.

 Назначение API

 Данное API предназначено для забора данных по звонкам на подменные номера системами автоматизации рекламы, системами аналитики рекламных агентств.

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

Рекомендуем обращаться к API раз в день для забора данных о конверсиях за день, но можно использовать и другую стратегию работы с API.

 

Как подключить API

Перейдите в Личный кабинет MANGO OFFICE, откройте настройки виджета Динамического коллтрекинга.

В разделе «API отчетов» нажмите на кнопку «Создать токен».

api_get_token.png

 

 

Вы увидите Ваш токен на экране, далее можно нажать кнопку «Скопировать токен».

Используйте этот токен для обращения к API в соответствии с инструкцией ниже.

copy_token.png


Также для использования API Вам необходимо знать идентификатор вашего виджета динамического коллтрекинга.

Вы можете увидеть его в коде Вашего виджета, который Вы вставляете на сайт.

<a id="mango-calltracking" href="tel:79999999999">79999999999</a>

<script>

    (function(w, d, u, i, o, s, p) {

        if (d.getElementById(i)) { return; } w['MangoObject'] = o;

        w[o] = w[o] || function() { (w[o].q = w[o].q || []).push(arguments) }; w[o].u = u; w[o].t = 1 * new Date();

        s = d.createElement('script'); s.async = 1; s.id = i; s.src = u;

        p = d.getElementsByTagName('script')[0]; p.parentNode.insertBefore(s, p);

    }(window, document, '//ics-pres-node1.ru.mgo.su/widgets/mango.js', 'mango-js', 'mgo'));

    mgo({calltracking: {id: 913, elements: [{selector: '#mango-calltracking'}]}});

</script>

 

Описание API и его методы

 


Получить количество звонков

Метод возвращает список звонков на все подменные номера (включая номера статических каналов) отсортированный по убыванию для виджета в заданном интервале времени.


Url запроса: https://widgets-api.mango-office.ru/v1/calltracking/[widgetId]/calls.[ext] , где widgetId - номер виджета, ext - расширение, определяющее тип экспорта. Допустимые типы выгрузки: csv, json. По умолчанию: json.

 

Для авторизации запроса необходимо передать token, полученный в личном кабинете. Возможны два способа указать token, либо в параметрах:

access_token=<token>

либо, в http заголовках:

Authorization: Bearer <token>


Пример запроса GET:  https://widgets-api.mango-office.ru/v1/calltracking/224/calls?dateStart=2017-06-01T00:00Z&dateEnd=2017-06-30T00:00Z&access_token=ceb0b254e8d168a9712c290b1b6517102f775f14


Параметры:

Название

Обязательность

Тип данных

Описание

Значение по умолчанию

dateStart

required

date (DD-MM-YYYYThh:mmZ)

дата и время начала интервала отчёта в формате ISO 8601

dateEnd

required

date (DD-MM-YYYYThh:mmZ)

дата и время окончания интервала отчёта в формате ISO 8601

callType

optional

number

Тип звонка: 0 - динамические и статические, 1 - динамические, 2 - статические, 3 - дефолтные

0

isNew

optional

number

Флаг нового звонка: 0 - все звонки, 1 - только новые

0

isQuality

optional

number

Флаг качественного звонка: 0 - все звонки, 1 - только качественные

0

utmSource

optional

string

Источник

utmMedium

optional

string

Канал

utmCampaign

optional

string

Кампания

utmContent

optional

string

Содержание

utmTerm

optional

string

Ключевое слово


Максимальный интервал времени для запроса звонков - 31 день.

Набор полей в ответе:

Название

Тип данных

Описание

callId

number

id звонка

dateStart

date

Время поступления звонка в формате ISO 8601: DD-MM-YYYYThh:mmZ

dateEnd

date

Время окончания звонка в формате ISO 8601: DD-MM-YYYYThh:mmZ

callType

number

Тип звонка: 1 - динамический, 2 - статический, 3 - дефолтный

callStatus

number

Статус завершения звонка как в ВАТС API, 11XX- звонок был принят, иначе - отклонён

number

number

Динамический номер, на который был принят звонок

callerNumber

number

Номер звонившего

duration

number

Продолжительность звонка в секундах. Считается только продолжительность разговора с оператором.

Без учета времени ожидания в ivr и ожидания распределения звонка внутри группы операторов.

waitDuration

number

Время ожидания до соединения с оператором в секундах

isNew

number

Флаг уникального звонка

isQuality

number

Флаг качественного звонка

isDuplicate

number

Флаг того, что с этого номера звонили последние 3 месяца

uid

string

Уникальный идентификатор клиента MANGO OFFICE

gaCid

string

Идентификатор клиента Google Analytics

yaCid

string

Идентификатор клиента Яндекс Метрики

utmSource

string

Источник

utmMedium

string

Канал

utmCampaign

string

Кампания

utmContent

string

Содержание (объявления)

utmTerm

string

Ключевое слово

countryCode

string

Код ISO страны

regionCode

string

Код ISO региона

city

string

Название города

device

string

Тип устройства: desktop, tablet или mobile

ip

string

IP адрес пользователя

url

string

Адрес страницы сайта, с которой был совершён звонок

firstUrl

string

Адрес страницы входа пользователя на сайт

 

Пример ответа:

[

  {

    "callId": 5001483600,

    "dateStart": "2017-05-30 10:53:03.000Z",

    "dateEnd": "2017-05-30 10:53:22.000Z",

    "callType": 1,

    "callStatus": 1120,

    "number": 74955646568,

    "callerNumber": 74955404444,

    "duration": 10,

    "waitDuration": 9,

    "isNew": true,

    "isQuality": true,

    "isDuplicate": false,

    "uid": "gVVPVLjV1kTOqd0r4xtx",

    "gaCid": null,

    "yaCid": null,

    "utmSource": "apple",

    "utmMedium": "apple",

    "utmCampaign": "apple",

    "utmContent": "apple",

    "utmTerm": "apple",

    "countryCode": "",

    "regionCode": "",

    "city": "",

    "ip": "192.168.1.24",

    "url": "http://m-test.ma/dkt/forrep.html?utm_source=apple&utm_medium=apple&utm_campaign=apple&utm_term=apple...",

    "firstUrl": "http://m-test.ma/dkt/forrep.html?utm_source=apple&utm_medium=apple&utm_campaign=apple&utm_term=apple..."

  },

  {

    "callId": 5001483602,

    "dateStart": "2017-05-30 10:55:26.000Z",

    "dateEnd": "2017-05-30 10:55:47.000Z",

    "callType": 1,

    "callStatus": 1110,

    "number": 74955646568,

    "callerNumber": 74955404444,

    "duration": 13,

    "waitDuration": 8,

    "isNew": false,

    "isQuality": false,

    "isDuplicate": true,

    "uid": "gVVPVLjV1kTOqd0r4xtx",

    "gaCid": null,

    "yaCid": null,

    "utmSource": "yandex",

    "utmMedium": "cpc",

    "utmCampaign": "(none)",

    "utmContent": "(none)",

    "utmTerm": "(none)",

    "countryCode": "RU",

    "regionCode": "MOW",

    "city": "Москва",

    "ip": "23.16.10.24",

    "url": "http://m-test.ma/dkt/testrep.html?utm_source=poland",

    "firstUrl": "http://m-test.ma/dkt/forrep.html?utm_source=apple&utm_medium=apple&utm_campaign=apple&utm_term=apple..."

  }

]


Примечание по параметрам API:


1. Параметр duration - определяет продолжительность разговора с оператором. Без учета времени ожидания в ivr и ожидания распределения звонка внутри группы операторов.


2. Параметр isNew - звонок считается новым, если выполнено два условия:

1) C данного номера (номер А или номер клиента) не было звонков в компанию в течении последних трех месяцев

2) Звонок распределился на группу продаж, которая указана в настройках коллтрекинга


3. Параметр isQuality. Звонок считается качественным, если время разговора с оператором было больше, чем время заданное в настройках коллтрекинга. По умолчанию - 30 секунд.


4. utmSource - данный параметр формируется аналогично отчету Источник/канал в Google Analytics. Для звонков с прямых переходов значение параметра возвращается (direct). Для звонков из органического поиска возвращается название поисковой системы (например, google или yandex). Для звонков с реферального трафика возвращается url сайта (источника), с которого был переход. Для платной рекламы в общем случае возвращается значение из метки utm_source.


5. utmMedium - данный параметр формируется аналогично отчету Источник/канал в Google Analytics. Для звонков с прямых переходов значение параметра возвращается (none). Для звонков из органического поиска возвращается значение organic. Для звонков с реферального трафика возвращается значение refferal. Для платной рекламы в общем случае возвращается значение из метки utm_medium.


6. utmTerm - данный параметр возвращает значение ключевого слова, если его удалось определить. Для платной рекламы в общем случае возвращается значение из метки utm_term.


7. Calltype. 1- Звонки на подменный динамический номер коллтрекинга, 2- Звонки на статические номера коллтрекинга, которые указаны в настройках статических каналов, 3- Звонки на дефолтный номер (основной, главный номер) компании. Этот номер задается в настройках коллтрекинга и нужен для того, чтобы у посетителей отображался номер, в случае если закончился бюджет на коллтрекинг или произошел технический сбой.