API-метод для пользовательских событий триггерных сценариев

Читать 8

Запрос

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 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-запросы завершатся с ошибкой.