Содержание

Отображение заявок в статистике
API-метод для создания заявок
API-метод для выгрузки заявок
- Запрос
  - Режимы фильтрации
  - Примеры GET-запросов на выгрузку заявок
- Ответ
Подключение к отслеживанию заявок с форм сайта

Отображение заявок в статистике

Чтобы эффективно анализировать статистику, необходимо отслеживать как можно больше обращений клиентов. А клиенты могут обращаться в Вашу компанию не только посредством звонков, но и оставляя заявки на Вашем сайте. Заявки в Calltouch так же являются составляющей лида. Напомним, что лид в Calltouch это звонок + обратный звонок + заявка. Созданные заявки будут доступны в качестве метрик любого отчета Calltouch, как на графиках:

Так и в таблицах в виде отдельных столбцов:

А так же в отдельном отчете Журнал заявок:

API-метод для создания заявок

Запрос

Поддерживаемые методы отправки: GET и POST.

API-запрос:

https://api-nodeX.calltouch.ru/calls-service/RestAPI/requests/{site_id}/register/

Где:

X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
{site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":

______________2019-06-13___12.45.45.png

API-токен для создания заявок не требуется.

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

Параметр	Описание
subject	Произвольное название формы на Вашем сайте, с которой отправляется заявка в Calltouch. В последствие переданное название формы отображается в одноименном столбце журнала заявок:
requestNumber	Уникальный идентификатор заявки на Вашем сайте. В качестве идентификатора может быть передано строковое значение до 256 символов. Переданный идентификатор отображается в столбце "Номер заявки" журнала заявок над названием формы: Параметр является необязательным, если его не передавать, то вместо него в журнале заявок будет отображаться уникальный идентификатор заявки в Calltouch.
requestDate	Дата и время отправки заявки в формате: dd.mm.yyyy%20hh:mm:ss. Дата и время заявки отображается в одноименном столбце "Журнала заявок": Параметр является необязательным, если его не передавать, то заявке будет автоматически присвоена текущая дата и время отправки API-запроса на создание заявки.
sessionId	Идентификатор сессии Calltouch. С помощью него Calltouch присвоит переданной заявке источник перехода на сайт посетителя, отправившего ее. Идентификатор сессии Calltouch присутствует в коде сайта, с которого отправляется заявка, если в этом коде установлен скрипт отслеживания Calltouch. Получить идентификатор сессии можно обратившись к глобальной JS-переменной window.call_value, пример из консоли Google Chrome: Обратите внимание, что в примере выше обращение идет не к переменной window.call_value, а к переменной window.call_value_1. Нестандартные названия переменной (_N в конце имени) возможны, когда Ваш один и тот же сайт отслеживается, например, одновременно в несколько личных кабинетах Calltouch. Если в Вашем случае будет использовать как раз такой нестандартный скрипт Calltouch, обратитесь к Вашему аккаунт-менеджеру Calltouch или на почту info@calltouch.net, чтобы узнать так называемый Specific ID - именно он отображается в качестве _N в конце имени переменной window.call_value. В некоторых случаях переменная window.call_value может принимать значение "undefined", а именно: Сервисом Calltouch на Вашем сайте по условиям подключения сервиса могут отслеживаться не все источники переходов посетителей Настроено ограничение отслеживания по геотаргетингу IP-адрес посетителя находится в списке заблокированных Если в API-запросе на создание заявки передать в параметре sessionId значение undefined, то API-запрос завершиться с ошибкой и заявка не будет создана. В подобных случаях, когда не удается определить источник перехода посетителя на сайт, не передавайте вовсе параметр sessionId при отправке API-запроса на создание заявки. Определившийся источник заявки (с помощью переданного значения сессии) будет отображен в журнале заявок: Параметр sessionId является необязательным, но если его не передавать, источник заявки не удасться определить как показано на скриншоте выше.
fio	Произвольное имя пользователя, отправившего заявку. Переданное значение отображается в журнале заявок: Параметр является необязательным, но если Вы не передаете имя клиента, то обязательно должны передать хотя бы номер телефона или почту клиента, для его последующей идентификации в журнале заявок.
phoneNumber	Номер телефона. Можно передавать в любом формате, главное чтобы было 11 цифр. Переданный номер автоматически будет приведен к формату 7XXXXXXXXXX и будет отображаться в журнале заявок: Параметр является необязательным, но если Вы не передаете номер телефона, то обязательно должны передать хотя бы почту или имя клиента, для его последующей идентификации в журнале заявок. Последние 4 цифры номера при необходимости могут быть скрыты сотрудникам Calltouch, см. раздел "Защита данных" в настройках статистики.
email	Почта клиента. Переданная почта отображается в журнале заявок: Параметр является необязательным, но если Вы не передаете почту клиента, то обязательно должны передать хотя бы номер телефона или имя клиента, для его последующей идентификации в журнале заявок. Часть почты после знака @ при необходимости могут быть скрыты сотрудникам Calltouch, см. раздел "Защита данных" в настройках статистики.
comment	Комментарий к заявке. Необязательный параметр. Произвольный текст, в качестве которого может быть передано любое необходимое значение. Переданный комментарий отображается в журнале заявок ЛК, оставленный от имени "API":

Если не указано ни одного входного параметра - заявка не будет создана и будет выведена ошибка "Не возможно создать заявку - не указано ни одного входного параметра". HTTP-код ответа ошибки: 200.

Пример GET-запроса на создание заявки

GET-запрос:

https://api-node3.calltouch.ru/calls-service/RestAPI/requests/18990/register/?subject=Моя форма&requestNumber=zi0D8c0c&requestDate=26.03.2018%2010:00:00&sessionId=1845461367&fio=Вася&email=vasya@mail.ru&phoneNumber=79205550055

Создаст в ЛК Calltouch сайта с идентификатором 18990 следующую заявку:

Формат тела запроса при использовании метода POST

При использовании метода отправки POST, параметры из таблицы выше должны быть перечислены в формате "application/x-www-form-urlencoded":

параметр1=значение1&параметр2=значение2&...

При использовании метода POST, одним API-запросом можно создать только одну заявку.

Ответ

После успешной отправки API-запроса на создание заявки, возвращается следующий JSON-ответ:

{
    "date": 1522047600000,
    "requestType": "CLIENT_ORDER",
    "dateStr": "26/03/2018 10:00:00",
    "session": {
        "keywords": "",
        "city": "vladimir",
        "ip": "95.66.182.68",
        "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:59.0) Gecko/20100101 Firefox/59.0",
        "source": "yandex",
        "medium": "cpc",
        "ref": "",
        "url": "http://filipok.io/calltouch/?utm_source=yandex&utm_medium=cpc&attrs={\"attrh\":1,\"ver\":171110,\"r7k12_si\":1156810694}",
        "utmSource": "yandex",
        "utmMedium": "cpc",
        "utmTerm": "",
        "utmContent": "",
        "utmCampaign": "",
        "guaClientId": null,
        "yaClientId": null,
        "sessionId": 1845461367,
        "additionalTags": [],
        "attribution": 1,
        "attrs": null
    },
    "subject": "Моя форма",
    "uniqTargetRequest": false,
    "uniqueRequest": false,
    "yandexDirect": null,
    "googleAdWords": null,
    "requestNumber": "zi0D8c0c",
    "requestId": 5222102,
    "client": {
        "fio": "Вася",
        "clientId": 37633316,
        "phones": [
            {
                "phoneNumber": "79205550055",
                "phoneType": "OTHER"
            }
        ],
        "contacts": [
            {
                "contactType": "EMAIL",
                "contactValue": "vasya@mail.ru"
            }
        ]
    },
    "orders": [],
    "targetRequest": false,
    "status": "NOT_SET",
    "order": null
}

JSON-объекты:

Объект	Описание
date	Дата и время создания заявки в формате Unix Timestamp в миллисекундах.
requestNumber	Уникальный идентификатор заявки на Вашем сайте, который Вы отправили в запросе. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор заявки в Calltouch (он же будет и в объекте requestId далее).
dateStr	Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss.
session	Объект будет содержать вложенные объекты с описанием посещения, за которым закрепилась заявка. Описание вложенных объектов: keywords - ключевой запрос city - город посетителя (определяется по его IP-адресу) ip - IP-адрес browser - Браузер source - Источник перехода medium - Канал перехода ref - адрес страницы, с которой был совершен реферальный переход на Ваш отслеживаемый сайт (присутствует только если переход посетителя был реферальным) url - адрес входа на сайт (может отличаться от страницы, с которой в итоге был совершен звонок) utmSource - значение utm-метки utm_source utmMedium - значение utm-метки utm_medium utmTerm - значение utm-метки utm_term utmContent - значение utm-метки utm_content utmCampaign - значение utm-метки utm_campaign guaClientId - идентификатор Google Client ID (присутствует, если настроена интеграция с Google Analytics) yaClientId - идентификатор Yandex Client ID (присутствует, если настроена интеграция с Яндекс.Метрика) sessionId - идентификатор сессии Calltouch, который Вы отправили в запросе ранее attribution - текущая модель атрибуции, согласно которой определился источник заявки (модель атрибуции может быть изменена в системных настройках ЛК, после этого источники будут "на лету" переопределены у всех звонков и заявок ранее) attrs - Сторонние параметры, переданные заранее в статистику Calltouch. Если Вы не отправляли идентификатор сессии Calltouch в запросе, объект будет равен значению null.
requestId	Уникальный идентификатор заявки в Calltouch.
subject	Название формы на Вашем сайте, которое Вы отправили в запросе.
uniqTargetRequest	Уникально-целевая заявка. Может принимать следующие значения: true (уникально-целевая заявка) false (не уникально-целевая заявка)
uniqueRequest	Уникальная заявка. Может принимать следующие значения: true (уникальная заявка) false (повторная заявка)
client	Объект будет содержать вложенные объекты с описанием клиента, данные по которому Вы отправили в запросе. Описание вложенных объектов: fio - имя клиента clientId - идентификатор клиента внутри Calltouch phones - содержит массив, внутри которого в объекте phoneNumber содержится номер телефона клиента contacts - содержит массив, внутри которого в объекте contactValue содержится почта клиента
orders	Здесь будет массив всех сделок, связанных с заявкой. На момент создания заявки пустой.
targetRequest	Целевая заявка. Может принимать следующие значения: true (целевая заявка) false (не целевая заявка)

JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.

API-метод для выгрузки заявок

Посмотреть создавшиеся заявки можно не только в интерфейсе Calltouch, но и получить их выгрузку в формате JSON через API.

Запрос

Поддерживаемый метод отправки: GET.

API-запрос:

https://api-nodeX.calltouch.ru/calls-service/RestAPI/requests

Где X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.

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

Параметр	Описание
clientApiId	Обязательный параметр. В отличие от API-запроса на создание сделки, в API-запросе на их выгрузку требуется указывать токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе "Настройки => API" ЛК Calltouch:
dateFrom	Обязательный параметр. Начальная дата создания заявок, с которой они будут выгружены. Формат mm/dd/yyyy.
dateTo	Обязательный параметр. Конечная дата создания заявок, до которой они будут выгружены. Формат mm/dd/yyyy.
timeFrom	Время начала периода выгрузки в формате hh:mm:ss. Необязательный параметр.
timeTo	Время конца периода выгрузки в формате hh:mm:ss. Необязательный параметр.
subject	Необязательный параметр. В качестве его значения можно указать название формы, для выгрузки только тех заявок, которые были сделаны с этой формы. Поиск среди заявок происходит по названию формы, которое "начинается с" указанного значения в параметре subject.
keywords	Необязательный параметр. В качестве его значения можно указать ключевой запрос, по которому пользователь совершил переход на отслеживаемый сайт и оставил заявку - в этом случае Поиск среди заявок происходит по ключевому запросу, который "содержит" указанное значение в параметре keywords.
city	Необязательный параметр. В качестве его значения можно указать название города, для выгрузки только тех заявок, которые были сделаны пользователем из этого города. Поиск среди заявок происходит по названию города, которое "полностью совпадает" с указанным значением в параметре city. Название городов указываются в формате базы данных Sypex Geo.
source	Необязательный параметр. В качестве его значения можно указать название источника, для выгрузки только тех заявок, которые были сделаны пользователем при переходе на сайт с этого источника. Поиск среди заявок происходит по названию источника, которое "полностью совпадает" с указанным значением в параметре source.
medium	Необязательный параметр. В качестве его значения можно указать название канала, для выгрузки только тех заявок, которые были сделаны пользователем при переходе на сайт с этого канала. Поиск среди заявок происходит по названию канала, которое "полностью совпадает" с указанным значением в параметре medium.
bindTo	Необязательный параметр. Флаг выгрузки заявок с привязкой к разным метрикам. Возможные значения: request - по дате создания заявок (по умолчанию) session - по дате сессий
ani.value	Необязательный параметр. В качестве его значения можно указать телефонный номер, для выгрузки только тех заявок, в которых был указан этот телефонный номер.
ani.filterMode	Режим фильтрации предыдущего параметра по номеру телефона, оставленного в заявке. Описание режимов смотри ниже.
email.value	Необязательный параметр. В качестве его значения можно указать электронную почту, для выгрузки только тех заявок, в которых была указана эта электронная почта.
email.filterMode	Режим фильтрации предыдущего параметра по электронной почте, оставленной в заявке. Описание режимов смотри ниже.
withMapVisits	Флаг истории посещений посетителя, оставившего заявку. Формат: withMapVisits=true - включить в ответ историю посещений, withMapVisits=false или отсутствие параметра - не включать.
withRequestTags	Флаг выгрузки тегов, которые были присвоены заявкам. Формат: withRequestTags=true - включить в ответ теги заявок, withRequestTags=false или отсутствие параметра - не включать.
withYandexDirect	Необязательный параметр. Флаг выгрузки данных по рекламным кампаниям Яндекс.Директ. Если входной параметр withYandexDirect = true, то в выгрузке присутствует выходной параметр yandexDirect, если withYandexDirect = false или не указан, то выходной параметр yandexDirect отсутствует.
withGoogleAdwords	Необязательный параметр. Флаг выгрузки данных по рекламным кампаниям Google AdWords. Если входной параметр withGoogleAdwords = true, то в выгрузке присутствует выходной параметр googleAdWords, если withGoogleAdwords = false или не указан, то выходной параметр googleAdWords отсутствует.
withAttrs	Флаг выгрузки сторонних параметров, переданных заранее в статистику Calltouch. Возможные значения: 1. Флаг withAttrs=false или не указан, по умолчанию. Сторонние параметры не выгружаются, значение выходного параметра attrs=null. 2. Флаг withAttrs=true. Сторонние параметры выгружаются в выходной параметр attrs. Если их нет, то значение выходного параметра attrs=null.
manager	Необязательный параметр. В качестве его значения можно указать ФИО менеджера, для выгрузки только тех заявок, которым был присвоен этот менеджер с помощью API-метода присвоения менеджеров к лидам.

Для выгрузки данных только по одной определенной заявки, используйте API-запрос:

https://api-nodeX.calltouch.ru/calls-service/RestAPI/requests/{requestNumber}

Где:

X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
{requestNumber} - внешний ID заявки. Указывается без фигурных скобок. Его можно получить в JSON-ответе на API-запрос создания заявки.

В качестве параметров, в нем необходимо указать только токен clientApiId (см. таблицу выше).

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

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

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

Примеры GET-запросов на выгрузку заявок

Выгрузка нескольких заявок

Запрос далее выгрузит заявки, созданные за период с 28 марта по 4 апреля 2019 года:

https://api-node9.calltouch.ru/calls-service/RestAPI/requests/?clientApiId=mD4rd.Nc5JINXrWEDLIi7/jvY/3CR64etYH40DggYFpCo&dateFrom=03/28/2019&dateTo=04/04/2019&withMapVisits=true

Выгрузка одной заявки

Запрос далее выгрузит заявку с идентификатором 79825254:

https://api-node3.calltouch.ru/calls-service/RestAPI/requests/79825254?clientApiId=GllU3tbwhrTkA1Chryud4xIT48WE8FPeNyrGQQswIb3nr

Ответ

После успешной отправки API-запроса на выгрузку заявок, возвращается следующий JSON-ответ:

[

    {
        "date": 1554382259240,
        "comments": [
            {
                "commentId": 7319,
                "requestId": 145507,
                "comment": "Колин комментарий",
                "partyId": 19688,
                "partyName": "API"
            }
        ],
        "requestType": "CLIENT_ORDER",
        "dateStr": "04/04/2019 15:50:59",
"manager": "Вася",
        "session": {
            "keywords": "(not set)",
            "city": "moscow",
            "ip": "95.163.114.76/32",
            "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
            "source": "(direct)",
            "medium": "(none)",
            "ref": "",
            "url": "https://alftest.ru/calltouch/supertest/",
            "utmSource": "<не указано>",
            "utmMedium": "<не указано>",
            "utmTerm": "<не указано>",
            "utmContent": "<не указано>",
            "utmCampaign": "<не указано>",
            "guaClientId": null,
            "yaClientId": null,
            "sessionId": 16441053,
            "additionalTags": [],
            "attribution": 1,
            "attrs": null
        },
        "subject": "Заявка на звонок",
        "uniqTargetRequest": true,
        "mapVisits": [
            {
                "utmSource": "<не указано>",
                "sessionDate": "03/04/2019 16:02:51",
                "city": "moscow",
                "ip": "95.163.114.76/32",
                "utmTerm": "<не указано>",
                "utmContent": "<не указано>",
                "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
                "sessionId": 15952760,
                "source": "(direct)",
                "medium": "(none)",
                "utmCampaign": "<не указано>",
                "url": "https://alftest.ru/calltouch/supertest/",
                "ref": "",
                "additionalTags": [],
                "utmMedium": "<не указано>",
                "guaClientId": null,
                "keyword": "(not set)"
            },
            {
                "utmSource": "<не указано>",
                "sessionDate": "04/04/2019 15:50:34",
                "city": "moscow",
                "ip": "95.163.114.76/32",
                "utmTerm": "<не указано>",
                "utmContent": "<не указано>",
                "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
                "sessionId": 16441053,
                "source": "(direct)",
                "medium": "(none)",
                "utmCampaign": "<не указано>",
                "url": "https://alftest.ru/calltouch/supertest/",
                "ref": "",
                "additionalTags": [],
                "utmMedium": "<не указано>",
                "guaClientId": null,
                "keyword": "(not set)"
            }
        ],
        "uniqueRequest": true,
        "requestNumber": "145507",
        "requestId": 145507,
        "client": {
            "fio": "Коля",
            "clientId": 640236,
            "phones": [
                {
                    "phoneNumber": "79991234567",
                    "phoneType": "OTHER"
                }
            ],
            "contacts": [
                {
                    "contactType": "EMAIL",
                    "contactValue": "kolya@yandex.ru"
                }
            ]
        },
        "orders": [
            {
                "orderId": 119901,
                "callId": null,
                "dateCreated": 1554382620000,
                "status": "PENDING",
                "realSum": "2800.0000",
                "offered": null,
                "sent": "04.04.2019",
                "sum": "2800.0000",
                "isMarked": null,
                "commentsCount": 0,
                "currentAmount": 2800,
                "orderNumber": "119901",
                "orderSum": "2800.0000",
                "orderStatus": "PENDING",
                "orderComments": "",
                "session": {
                    "keywords": "(not set)",
                    "city": "moscow",
                    "ip": "95.163.114.76/32",
                    "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
                    "source": "(direct)",
                    "medium": "(none)",
                    "ref": "",
                    "url": "https://alftest.ru/calltouch/supertest/",
                    "utmSource": "<не указано>",
                    "utmMedium": "<не указано>",
                    "utmTerm": "<не указано>",
                    "utmContent": "<не указано>",
                    "utmCampaign": "<не указано>",
                    "guaClientId": null,
                    "yaClientId": null,
                    "sessionId": 16441053,
                    "additionalTags": [],
                    "attribution": 1,
                    "attrs": null
                }
            }
        ],
        "targetRequest": true,
        "status": "NOT_SET",
        "order": {
            "orderId": 119901,
            "callId": null,
            "dateCreated": 1554382620000,
            "status": "PENDING",
            "realSum": "2800.0000",
            "offered": null,
            "sent": "04.04.2019",
            "sum": "2800.0000",
            "isMarked": null,
            "commentsCount": 0,
            "currentAmount": 2800,
            "orderNumber": "119901",
            "orderSum": "2800.0000",
            "orderStatus": "PENDING",
            "orderComments": "",
            "session": {
                "keywords": "(not set)",
                "city": "moscow",
                "ip": "95.163.114.76/32",
                "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
                "source": "(direct)",
                "medium": "(none)",
                "ref": "",
                "url": "https://alftest.ru/calltouch/supertest/",
                "utmSource": "<не указано>",
                "utmMedium": "<не указано>",
                "utmTerm": "<не указано>",
                "utmContent": "<не указано>",
                "utmCampaign": "<не указано>",
                "guaClientId": null,
                "yaClientId": null,
                "sessionId": 16441053,
                "additionalTags": [],
                "attribution": 1,
                "attrs": null
            }
        }
    },

    ...

    {
        ...
    }

]

JSON-объекты:

Объект	Описание
date	Дата и время создания заявки в формате Unix Timestamp в миллисекундах.
comments	Комментарии к заявкам. Возможные значения: Если у заявки не будет комментариев, значение параметра будет в виде пустого массива: "comments": [] Если у заявки будут комментарии, значение параметра будет массив комментариев: Где вложенные объекты элемента массива: commentId - ID комментария (число) requestId - ID заявки, по которой оставлен комментарий (число) comment - комментарий (строка) partyId - ID пользователя, оставившего комментарий (число) partyName - логин пользователя, оставившего комментарий (строка) Обратите внимание, в конце комментария comment может присутствовать символ \n. Он означает перенос строки, не забудьте учесть это при парсинге параметров.
requestNumber	Уникальный идентификатор заявки на Вашем сайте, который Вы отправили в запросе. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор заявки в Calltouch (он же будет и в объекте Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss. далее).
dateStr	Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss.
manager	ФИО менеджера, который был присвоен заявке с помощью API-метода присвоения менеджеров к лидам. Если у заявки нет менеджера, передается значение null.
session	Объект будет содержать вложенные объекты с описанием посещения, за которым закрепилась заявка. Описание вложенных объектов: keywords - ключевой запрос city - город посетителя (определяется по его IP-адресу) ip - IP-адрес browser - Браузер source - Источник перехода medium - Канал перехода ref - адрес страницы, с которой был совершен реферальный переход на Ваш отслеживаемый сайт (присутствует только если переход посетителя был реферальным) url - адрес входа на сайт (может отличаться от страницы, с которой в итоге был совершен звонок) utmSource - значение utm-метки utm_source utmMedium - значение utm-метки utm_medium utmTerm - значение utm-метки utm_term utmContent - значение utm-метки utm_content utmCampaign - значение utm-метки utm_campaign guaClientId - идентификатор Google Client ID (присутствует, если настроена интеграция с Google Analytics) yaClientId - идентификатор Yandex Client ID (присутствует, если настроена интеграция с Яндекс.Метрика) sessionId - идентификатор сессии Calltouch, который Вы отправили в запросе ранее attribution - текущая модель атрибуции, согласно которой определился источник заявки (модель атрибуции может быть изменена в системных настройках ЛК, после этого источники будут "на лету" переопределены у всех звонков и заявок ранее) attrs - Сторонние параметры, переданные заранее в статистику Calltouch. Если Вы не отправляли идентификатор сессии Calltouch в запросе, объект будет равен значению null.
requestId	Уникальный идентификатор заявки в Calltouch.
subject	Название формы на Вашем сайте, которое Вы отправили в запросе.
uniqTargetRequest	Уникально-целевая заявка. Может принимать следующие значения: true (уникально-целевая заявка) false (не уникально-целевая заявка)
uniqueRequest	Уникальная заявка. Может принимать следующие значения: true (уникальная заявка) false (повторная заявка)
client	Объект будет содержать вложенные объекты с описанием клиента, данные по которому Вы отправили в запросе. Описание вложенных объектов: fio - имя клиента clientId - идентификатор клиента внутри Calltouch phones - содержит массив, внутри которого в объекте phoneNumber содержится номер телефона клиента contacts - содержит массив, внутри которого в объекте contactValue содержится почта клиента
targetRequest	Целевая заявка. Может принимать следующие значения: true (целевая заявка) false (не целевая заявка)
orders	Массив всех сделок, связанных с заявкой. Для каждой сделки будет содержать вложенные объекты с описанием сделки, связанной с заявкой, если таковые были созданы (см. статью Управление сделками через API). Описание вложенных объектов: orderId - идентификатор сделки внутри Calltouch dateCreated - дата и время создания сделки status - cтатус сделки sum - бюджет сделки orderNumber - уникальный идентификатор сделки в Вашей CRM (если при создании сделки Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор сделки в Calltouch - он же будет и в объекте orderId выше) Если Вы не отправляли идентификатор сессии Calltouch в запросе, массив будет пустой.
mapVisits	История посещений. Параметр присутствует в случае, если указан входной параметр истории посещений withMapVisits=true. Результат будет содержать все посещения пользователя оставившего заявку на сайте, utmSource sessionDate sessionID city ip utmTerm utmContent userAgent sessionId source medium utmCampaign url ref additionalTags utmMedium guaClientId keyword
yandexDirect	Если источник звонка или заявки рекламная кампания Яндекс.Директ, между Calltouch и Яндекс.Директ включена интеграция, то в данном параметре выводится следующая информация: campaignId - ID кампании adGroupId - ID группы adId - ID объявления criteriaId - ID фразы Пример ответа, когда у звонка или заявки есть эти данные: "yandexDirect": { "campaignId": 32515134, "adGroupId": 325245212134, "adId": 2546356252, "criteriaId": 254251323 } Пример ответа, когда у звонка или заявки нет этих данных (не настроена интеграция, либо данные еще не собрались): "yandexDirect": null
googleAdWords	Если источник звонка или заявки рекламная кампания Google AdWords, между Calltouch и Google AdWords включена интеграция, то в данном параметре выводится следующая информация: campaignId - ID кампании adGroupId - ID группы creativeId - ID объявления criteriaId - ID фразы Пример ответа, когда у звонка или заявки есть эти данные: "googleAdWords": { "campaignId": 35635656, "adGroupId": 134524245, "creativeId": 23134141, "criteriaId": 4324553542 } Пример ответа, когда у звонка или заявки нет этих данных (не настроена интеграция, либо данные еще не собрались): "googleAdWords": null
attrs	Сторонние параметры, переданные заранее в статистику Calltouch. Выгружаются, если во входных параметрах был передан флаг withAttrs=true. Возможные значения: attrs: {"param1":"value1","param2":"value2"}

Данные из Яндекс.Директ и Google AdWords подгружаются в Calltouch на следующий день после фиксирования звонка или заявки. Если данные обновляются на стороне Яндекс.Директ или Google AdWords (они могут обновиться 4 раза в месяц), то они будут изменены и в API-выгрузке.

Подключение к отслеживанию заявок с форм сайта

Суть подключения состоит в том, чтобы по событию отправки формы на Вашем сайте, выполнялся скрипт, который будет отправлять в Calltouch API-запрос на создание заявки. Реализовать подключение можно либо на клиентской стороне, либо на серверной. Оба способа описаны далее.

Реализация на клиентской стороне

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

В данном случае оптимальным вариантом будет добавление дополнительного скрипта Calltouch в текущий обработчик формы. Обратите внимание, что скрипт отправки заявки в Calltouch необходимо выполнять только при успешном прохождении валидации формы. Ниже представлен пример скрипта для отправки API-запроса на создание заявки средствами JavaScript, используя функцию AJAX библиотеки jQuery:

var ct_node_id = 'X';
var ct_site_id = '{site_id}';
var ct_data = {             
fio: 'Иванов Иван Иванович',
phoneNumber: '79000000000',
email: 'test@test.ru',
subject: 'Заявка с сайта',
sessionId: window.call_value 
};
jQuery.ajax({  
  url: 'https://api-node'+ct_node_id+'.calltouch.ru/calls-service/RestAPI/requests/'+ct_site_id+'/register/',      
  dataType: 'json',         
  type: 'POST',          
  data: ct_data
});

Где:

X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
{site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":

______________2019-06-13___12.45.45.png

ct_data - массив передаваемых входных параметров API-запроса на создание заявки.

Во входных параметрах fio, phoneNumber, email и subject скрипта выше указаны тестовые данные формы. При написании реального скрипта на сайте для отправки заявок в Calltouch, необходимо настроить передачу данных, введенных клиентом на отправляемой форме, в качестве значений соответствующих входных параметров API-запроса на создание заявки.

По умолчанию AJAX-запрос выполняется асинхронно. Если при отправке формы на сайте происходит редирект или обновление страницы, мы рекомендуем использовать синхронный AJAX-запрос, чтобы избежать случаев, когда редирект при отправке формы выполнится быстрее, чем API-запрос на создание заявки в Calltouch. Для этого в AJAX-функцию необходимо добавить параметр async: false.

В случае, если форма на сайте имеет простой функционал и минимальный набор полей, можно организовать скрипт отправки заявок из формы в Calltouch с помощью отдельного внешнего обработчика. Приведем пример скрипта, реализованном с использованием функций библиотеки jQuery, в котором по событию submit некоторой формы будет производится сбор введенных в форме данных и отправка заявки в Calltouch:

<script type="text/javascript">
/* Вешаем обработчик по событию submit формы с идентификатором myform */
jQuery(document).on('submit', 'form#myform', function() { 
/* Записываем в переменную form объект с формой, на которой сработало событие submit */
var form = jQuery(this);
/* Ищем на форме input для ввода номера телефона и получаем его значение, в примере поиск производится по наличию у input атрибута name со значением phone */
var phone = form.find('input[name="phone"]').val();
/* Аналогично собираем другие введенные в поля формы данные, например, ФИО и email */
var fio = form.find('input[name="name"]').val();
var mail = form.find('input[name="email"]').val(); 
/* Указываем название формы */
var sub = 'Заявка на звонок';
/* Указываем ID сайта внутри Calltouch и адрес API-сервера */
var ct_node_id = 'X';
var ct_site_id = '{site_id}';
/* Формируем массив входных параметров запроса */
var ct_data = {         
fio: fio,
phoneNumber: phone,
email: mail,
subject: sub,
sessionId: window.call_value 
};
/* При необходимости делаем проверку на корректность собранных с формы данных */
/* Например, обязательным для заполнения на форме является поле с телефоном, проверяем его наличие и не пустое ли оно */
if (typeof(phone)!='undefined' && phone!=''){
/* Выполняем AJAX-запрос */
jQuery.ajax({  
  url: 'https://api-node'+ct_node_id+'.calltouch.ru/calls-service/RestAPI/requests/'+ct_site_id+'/register/',      
  dataType: 'json',         
  type: 'POST',          
  data: ct_data,
  async: false /* Предположим, после отправки формы на сайте настроен редирект на другую страницу, поэтому используем параметр async: false для синхронной отправки запроса */
});  
}
});
</script>

Скрипт выше является примером и требует адаптации под конкретные формы Вашего сайта. Его использование и внесение в него изменений требует наличие на сайте библиотеки jQuery и навыков ее использования.

Реализация на серверной стороне

В случае, если основной функционал обработки, валидации и отправки формы организован на стороне сервера, то можно встроить функционал отправки заявок в Calltouch скриптом на сервере. Приведем пример реализации скрипта на PHP с использованием CURL:

$call_value = $_COOKIE['_ct_session_id']; /* ID сессии Calltouch, полученный из cookie */
$ct_node_id = 'X';
$ct_site_id = '{site_id}';
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-type: application/x-www-form-urlencoded;charset=utf-8"));
curl_setopt($ch, CURLOPT_URL,'https://api-node'.$ct_node_id.'.calltouch.ru/calls-service/RestAPI/requests/'.$ct_site_id.'/register/');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
	"fio=".urlencode($_POST['name'])
	."&phoneNumber=".$_POST['phone']
	."&email=".$_POST['email']
	."&subject=".urlencode('Заявка с сайта')
	."".($call_value != 'undefined' ? "&sessionId=".$call_value : ""));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$calltouch = curl_exec ($ch);
curl_close ($ch);

Где:

X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
{site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":

______________2019-06-13___12.45.45.png

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

ID сессии Calltouch, который необходимо отправить в качестве параметра sessionId API-запроса на создание заявки, необходимо передавать в PHP-обработчик с клиентской стороны, получая значение ID сессии из соответствующей переменной (по умолчанию window.call_value).
Для корректной передачи кириллических символов в запросе и обхода проблем с кодировкой, необходимо применять PHP-функцию urlencode ко всем PHP-переменным, передаваемым в качестве входных параметров API-запроса. Т.е., если ФИО клиента находится в $_POST['name'], то в API-запрос ее надо добавить как urlencode($_POST['name']).
В API-запросе в явном виде должна быть указана кодировка utf-8.

Во входных параметрах fio, phoneNumber, email и subject скрипта выше указаны тестовые данные формы соответственно: $_POST['name'], $_POST['phone'], $_POST['email'] и значение "Заявка с сайта". При написании реального скрипта на сервере для отправки заявок в Calltouch, необходимо настроить передачу данных, введенных клиентом на отправляемой форме, в качестве значений соответствующих входных параметров API-запроса на создание заявки.

Видеоинструкция - как подключить заявки с форм сайта за 5 минут

Кол-во запросов в секунду к API Calltouch ограничено – не более 5 запросов (+5 запросов в очередь) в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, 5 поставятся в очередь, и 1 API-запрос завершится с ошибкой.

Управление заявками через API

Отображение заявок в статистике

API-метод для создания заявок

Запрос

Пример GET-запроса на создание заявки

Формат тела запроса при использовании метода POST

Ответ

API-метод для выгрузки заявок

Запрос

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

Примеры GET-запросов на выгрузку заявок

Ответ

Подключение к отслеживанию заявок с форм сайта

Реализация на клиентской стороне

Реализация на серверной стороне

Видеоинструкция - как подключить заявки с форм сайта за 5 минут

0 Комментарии