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).
- Яндекс Директ (раздел «Источники»)
- Конструктор интеграций (раздел «CRM»)
- RTB House (раздел «Отправка данных во внешние системы»)