API-метод для пользовательских событий триггерных сценариев
Описание
В статье описан 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 (раздел «Подключение»)