API-метод для пользовательских событий триггерных сценариев
Запрос
URL: https://api.calltouch.ru/lead-service/v1/api/calltouch-leads/custom-event
Метод: POST
HTTP-заголовки:
- Access-Token — API-ключ
- SiteId — ID ЛК Calltouch
Тело
{ "scenarioId": 123, "uniqueKey": "everything", "phoneNumber": "79996665555", "email": "mail@domain.ru", "fio": "Василий Галкин", "clientId": 145236, "firstInteractionDate": "2023-11-10 08:00:02", "lastInteractionDate": "2023-11-10 08:00:02", "clientManager": "Вася", "clientTags": "Тег 1, Тег_афафа", "source": "yandex", "medium": "cpc", "utmCampaign": "rsy_msk", "utmContent": "content", "utmTerm": "слово", "ctClientId": "200008", "ctGlobalId": "ec6f6f17-1d06-565d-95e7-e66e8d1b0621", "gcid": "fs23rg", "yaClientId": "fs23rg", "domain": "site.ru", "urlEntry": "site.ru/uri", "urlExit": "site.ru/uri2", "sessionDuration": 32, "productsInBasket": "стул красный", "goals": "Цель 1, Цель 2", "orderedProducts": "стул красный", "tags": "fs23rg", "leadKind": "Звонок", "leadComment": "unique", "dealFunnel": "Продажи", "previousDealFunnel": "Сервис", "newDealFunnel": "Продажи", "dealStatus": "Текущий", "previousDealStatus": "Старый", "newDealStatus": "Новый", "dealManager": "Виктор", "dealName": "Квартира 63", "dealRevenue": "124.3", "clientLastLeadUrl": "https://my.calltouch.ru/accounts/123/sites/1234/reports/calls-journal?callId=111", "clientLastDealUrl": "https://my.calltouch.ru/accounts/123/sites/1234/reports/deals-journal?dealId=222" }
Передаваемые параметры
Параметр |
Название параметра |
Обязательный |
Формат |
Описание |
scenarioId | ID сценария | Да | Integer | Идентификатор сценария. Цифровые значения |
uniqueKey | Уникальный ключ | Да | String | Параметр, вводимый пользователем в настройках события в сценарии. Цифры и латиница. |
phoneNumber | Номер клиента | Да, если не передан email | String | Номер телефона клиента. Номер может быть в любом формате, 71234567890, +71234567890, 8 (123) 456-78-90 и любом другом – мы должны автоматически конвертировать его в 11-значный формат. Если клиент не обладает номером, не передавайте параметр. |
Email клиента | Да, если не передан phoneNumber | String | Формат x@x.x, любые символы. | |
fio | ФИО клиента | Нет | String | ФИО клиента, любые символы |
clientId | ID клиента | Нет | Int | ID клиента, в рамках которого осуществлено действие. |
firstInteractionDate | Дата и время первого касания | Нет | String |
Дата и время первого касания клиента. |
lastInteractionDate | Дата и время последнего касания | Нет | String | |
clientManager | Менеджер клиента | Нет | String | Менеджер клиента. |
clientTags | Теги клиента | Нет | String | Теги клиента. Передаются через точку с запятой. |
source | Источник | Нет | String | Источник сессии, в рамках которой клиент вернулся на сайт. |
medium | Канал | Нет | String | Канал сессии, в рамках которой клиент перешел на сайт. |
utmCampaign | Метка utm_campaign | Нет | String | Метка utm_campaign, в рамках которой клиент перешел на сайт. |
utmContent | Метка utm_content | Нет | String | Метка utm_content, в рамках которой клиент перешел на сайт. |
utmTerm | Метка utm_term | Нет | String | Метка utm_term, в рамках которой клиент перешел на сайт. |
ctClientId | ID посетителя сайта | Нет | String | Идентификатор посетителя в системе Calltouch. Он представляет из себя значение cookie _ct. |
ctGlobalId | Глобальный ID посетителя сайта | Нет | Uid | Глобальный идентификатор посетителя в системе Calltouch, общий для сайтов, на которых установлен скрипт Calltouch. Он представляет из себя значение сквозной cookie _ct_client_global_id. |
gcid | Google Client ID | Нет | String | Идентификатор Google Client ID. |
yaClientId | Yandex Client ID | Нет | String | Идентификатор Yandex Client ID. |
domain | Домен | Нет | String | Домен сайта в рамках сессии возвращения клиента. |
urlEntry | Страница входа на сайт | Нет | String | URL входа на сайт в рамках сессии возвращения клиента. |
urlExit | Страница выхода | Нет | String | URL выхода с сайта в рамках сессии возвращения клиента. |
sessionDuration | Время на сайте | Нет | INT | Время, проведенное на сайте в рамках сессии возвращения клиента, в секундах. |
goals | Достигнутые цели | Нет | String | Достигнутые цели в рамках сессии возвращения клиента. |
productsInBasket | Товары в корзине | Нет | String | Товары, которые были добавлены в корзину в рамках сессии. |
orderedProducts | Заказанные товары | Нет | String | Товары, по которым зафиксирован заказ в рамках сессии. |
tags | Теги | Нет | String | Теги лида или сделки. Передаются через точку с запятой. |
leadKind | Вид лида | Нет | String | Вид лида. |
leadTypes | Типы лида | Нет | String | Типы лида. |
leadComment | Комментарий | Нет | String | Комментарий звонка или заявки. |
dealFunnel | Воронка | Нет | String | Воронка сделки. |
previousDealFunnel | Предыдущая воронка | Нет | String | Предыдущая воронка сделки. |
newDealFunnel | Новая воронка | Нет | String | Новая воронка сделки. |
dealStatus | Этап | Нет | String | Этап сделки. |
previousDealStatus | Предыдущий этап | Нет | String | Предыдущий этап сделки. |
newDealStatus | Новый этап | Нет | String | Новый этап сделки. |
dealManager | Менеджер | Нет | String | Менеджер сделки. |
dealName | Название сделки | Нет | String | Название сделки. |
dealRevenue | Выручка | Нет | Float | Выручка сделки. |
clientLastLeadUrl | Ссылка на ближайший лид клиента | Нет | String | Ссылка на ближайший лид пользователя (звонок или заявка). |
clientLastDealUrl | Ссылка на ближайшую сделку клиента | Нет | String | Ссылка на ближайшую сделку пользователя. |
Если переданные параметры совпадают с настройками в личном кабинете и событие подходит по карте сценария, то запускается сценарий.
Ответ
Формат ответа
{ "scenarioLaunch": true, "error": null }
Ошибки
Передан неверный ключ
- Если переданные параметры не совпадают с настройками в личном кабинете, то сценарий не запускается. Пример: Клиент в ЛК Calltouch настроил ключ: "visited_the_page_X". В Calltouch приходит API с уникальным ключом: "send_sms".
- Если переданное событие не соответствует заданному сценарию, передано в некорректной последовательности, то сценарий не запускается. Ждем наступления ожидаемого события. Пример: «Аудитория — Пользовательское событие с ключом “aaa” — SMS — ожидание сделки — Исходящий вебхук — Пользовательское событие с ключом “bbb”». Если пришло событие с ключом “bbb”, а клиент по сценарию еще не проходил, то мы не пошлём вторую SMS.
{ "status": "error", "errors": [ {"uniqueKey": "Переданное событие не соответствует карте сценария. Либо ключа не существует в сценарии, либо ожидается другое событие."} ] }
Неверный сценарий
Если передан сценарий, которого нет в Calltouch или сценарий удален, то выводится информация об ошибке:
{ "status": "error", "errors": [ {"scenarioId": "Переданного сценария не существует, запуск невозможен."} ] }
Невалидный параметр
Если отсутствуют следующие параметры или они переданы некорректно: scenarioId, uniqueKey, phoneNumber/email, то запуск сценария невозможен.
Выводится информация об ошибке:
{ "status": "error", "errors": [ {"parameter": "Требуемый параметр отсутствует или не соответствует требованиям. Для запуска сценария не хватает данных."} ] }
Неактивный сценарий
Если переданы параметры, а сценарий неактивен, то выводится информация об ошибке.
{ "status": "error", "errors": [ {"scenarioId": "Сценарий, содержащий передаваемые параметры неактивен. Запуск сценария невозможен."} ] }
Ошибка токена
Если указан неверный API-токен или ID сайта, то сценарий не запускается и выводится ошибка:
{ "status": "error", "errors": [ {"apiKey": "API-токен и/или ID сайта указаны неверно. Запуск сценария невозможен."} ] }
Нет доступа к методу
Если поступает запрос с валидным токеном к методу, к которому у владельца токена нет доступа, выводится ошибка:
{ "meta": [], "data": { "message": "Пользователь {party_name} не имеет доступа к данному методу API" } }
Исчерпан лимит баллов API
Если закончились почасовые баллы, то выводится ошибка:
{ "meta": [], "data": { "type": "apiError", "apiErrorData": { "errorCode": 90001, "errorMessage": "Исчерпан часовой лимит баллов по сайту", "errorDescription": null }, "validationErrorData": null } }
Система баллов API Calltouch
Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов. За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch
Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).
- A/B тестирование (раздел «Подключение»)
- Email-трекинг (раздел «Подключение»)
- Отслеживание офлайн конверсии (раздел «Подключение»)
- Подключение к отслеживанию дополнительных доменов (раздел «Подключение»)
- Подмена номеров на AMP-страницах Google (раздел «Подключение»)