Наверх

API-метод тегирования лидов

Запрос

POST: https://api.calltouch.ru/lead-service/v1/api/tag/lead/add

HTTP-заголовки:

  • Access-Token – API-ключ
  • SiteId – ID ЛК Calltouch

Тело запроса в формате JSON:

{
    "leads": [

     // Лид 1

        {
            "matching": [
                {
                    "type": "request",
                    "requestParams": {
                        "requestId": 1,
                        "tags": ["тег1", "тег2"],
                        "tagsLogic": "and"
                    }
                },
                {
                    "type": "call",
                    "callParams": {
                        "callId": 2 ,
                        "tags": ["тег"],
                        "tagsLogic": "and"
                    }
                },
                {
                    "type": "requestContact",
                    "requestContactParams": {
                        "emails": ["name@server.com"],
                        "phones": ["79157771122", "+7 (915) 888-11-22"],
                        "date": "01-10-2020 12:00:00",
                        "tags": ["тег"],
                        "tagsLogic": "and",
                        "requestTypeToMatch": "nearestUniq",
                        "searchDepth": 120
                    },
                },
                {
                    "type": "callContact",
                    "callContactParams": {
                        "phones": ["84953338877"],
                        "date": "01-10-2020 12:00:00",
                        "tags": ["тег"],
                        "tagsLogic": "and",
                        "callTypeToMatch": "nearestUniqLead",
                        "searchDepth": 120
                        },
                },
                {
                    "type": "call",
                    "callParams": {
                        "callId": 2,
                        "tags": ["тег"],
                        "tagsLogic": "and"
                    }
                }
            ],
        "addTags": {
            "overwrite": false,
            "tags":
                [
                    {"tag": "Тег 1"},
                    {"tag": "Тег 2"},
                    {"tag": "Тег N"}
                ]
            }
        },

     // Лид N

        ...
    ]
}

 

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

Параметр Формат Обязательный Описание
leads array Да Массив лидов. Можно перечислить до 100 лидов за 1 запрос. Тегирование происходит в режиме онлайн, результат можно получить сразу же. Обязательно.
leads.matching object Да

Здесь задается приоритет использования разных типов матчинга, по которым мы будем пытаться найти лид для тегирования. Чем выше находится строка с типом матчинга, тем больший приоритет она имеет. Если матчинга завершится на каком-либо типе, остальные типы ниже будут проигнорированы. Одинаковые типы матчинга могут повторяться, но общее кол-во типов не должно превышать 20 строк. Возможные значения: call – поиск звонка по ID, request – поиск заявки по ID, callContact – поиск звонка по номеру телефона / дате сделки, requestContact – поиск заявки по номеру телефона / почте / дате. Обязательно нужно указать хотя бы 1 тип маппинга в приоритете.

leads.matching

.type

string Обязательно нужно указать хотя бы 1 тип маппинга в приоритете. Тип матчинга. Возможные значения:
  • call – поиск звонка по ID
  • request – поиск заявки по ID
  • callContact – поиск звонка по номеру телефона / дате
  • requestContact – поиск заявки по номеру телефона / почте / дате

leads.matching

.requestParams

object Обязательно, если "type": "request" Параметры матчинга заявки по ID

leads.matching

.requestParams.requestId

integer / string Обязательно, если "type": "request"

Возможные параметры:

  • requestId (integer)
  • requestNumber (string)

leads.matching

.requestParams.tags

array Необязательно

Если указан список тегов, то найденная заявка перед тегированием будет дополнительно проверена на наличие указанных тегов. И только если у заявки будут эти теги, то она будет протегирована другими тегами из запроса. Иначе заявка не тегируется, а матчинг переключается на следующий тип в приоритете. Необязательно.

Фильтрация по тегам может передаваться вместе с типами call, request, callContact и requestContact.

leads.matching

.requestParams.tagsLogic

string Обязательно, если указан параметр tags и в нем передается более 1 тега Логические условие между тегами. Возможные значения: and (у заявки должны быть все перечисленные теги) или or (у заявки должен быть хотя бы один из перечисленных тегов).

leads.matching

.callParams

object Обязательно, если "type": "call" Параметры матчинга звонка по ID

leads.matching

.callParams.callId

integer / string Обязательно, если "type": "call"

Возможные параметры:

  • callId (integer)
  • callReferenceId (string)
  • sipCallId (string)

leads.matching

.callParams.tags

array Необязательно Аналогично описанию из блока requestParams

leads.matching

.callParams.tagsLogic

string Обязательно, если указан параметр tags и в нем передается более 1 тега Аналогично описанию из блока requestParams

leads.matching

.requestContactParams

object Обязательно, если "type": "requestContact" Параметра матчинга заявки по номеру телефона / почте / дате

leads.matching

.requestContactParams.emails

array Должен быть передан хотя бы один из параметров – emails или phones или оба. Можно перечислить несколько почт, формат x@x.x, любые символы. Должен быть передан хотя бы один из параметров – emails или phones или оба.

leads.matching

.requestContactParams.phones

array

Можно перечислить несколько номеров телефонов. Номера могут быть в любом формате, 71234567890, +71234567890, 8 (123) 456-78-90 и любом другом – мы должны автоматически конвертировать на бэке их в 11-значный формат.

Если переданы и phones и emails, то поиск заявки идет сначала по номерам, если не найдем, то по почтам.

leads.matching

.requestContactParams.tags

array Необязательно Аналогично описанию из блока requestParams

leads.matching

.requestContactParams.date

string Обязательно, если "type": "requestContact" Дата лида для его поиска

leads.matching

.requestContactParams.tagsLogic

string Обязательно, если указан параметр tags и в нем передается более 1 тега Аналогично описанию из блока requestParams

leads.matching

.requestContactParams

.requestTypeToMatch

string Обязательно, если "type": "requestContact"

Типы заявок, среди которых будет происходить поиск для тегирования. Возможные значения:

  • nearest
    Любая ближайшая заявка
  • nearestUniq
    Уникальная ближайшая заявка
  • nearestTarget
    Целевая ближайшая заявка
  • nearestUniqTarget
    Уникально-целевая ближайшая заявка

leads.matching

.requestContactParams

.searchDepth

integer Обязательно, если "type": "requestContact" Глубина поиска подходящего лида от даты date, указывается в мин. Возможные значения от 1 до 525600 мин (1 год).

leads.matching

.callContactParams

object   Параметры матчинга звонка по номеру телефона / дате

leads.matching

.callContactParams.phones

array Обязательно, если "type": "callContact" Аналогично описанию из блока requestContactParams

leads.matching

.callContactParams.date

string Обязательно, если "type": "callContact" Дата лида для его поиска

leads.matching

.callContactParams.tags

array Необязательно Аналогично описанию из блока requestParams

leads.matching

.callContactParams.tagsLogic

string Обязательно, если указан параметр tags и в нем передается более 1 тега Аналогично описанию из блока requestParams

leads.matching

.callContactParams

.callTypeToMatch

string Обязательно, если "type": "callContact" Аналогично описанию из блока requestContactParams

leads.matching

.callContactParams.searchDepth

integer Обязательно, если "type": "callContact" Аналогично описанию из блока requestContactParams
leads.addTags.tags array Нет

Добавление тегов к лиду. Если такие теги уже есть в ЛК, новые не создаются, а используются существующие. Необязательно, максимум 100 тегов.

Формат:

"addTags": {
"tags": [
{
"tag": "Тег 1"
},
{
"tag": "Тег 2"
}
],
"overwrite": true
}

leads.addTags.overwrite boolean Нет Перезаписывать ли существующие теги у лида или нет. Обязательно, если указывается addTags.

 

Ответ

Процесс тегирования запускается сразу же после отправки запроса, после чего сразу же возвращается и ответ, пример:

{
    "meta": [],
    "data": {
        "leads": [
            {
                "matchedType": "request",
                "tagged": true,
                "callInfo": null,
                "requestInfo": {
                    "requestId": 1257513,
                    "requestNumber": "1257513"
                },
                "error": null
            }
        ]
    }
}

Если API-токен не указан, то тегирование не выполняется и выводится ошибка:

{
    "meta": [],
    "data": {
        "message": "Ошибка доступа"
    }
}

Если API-токен указан не верно, то тегирование не выполняется и выводится ошибка:

{
    "message": "Access token не найден"
}

 

Параметры ответа

Параметр Формат

Описание

leads.orders.matchedType string

Тип матчинга из параметра matching API-запроса на тегирование лида. Если ни один из переданных типов не нашел лид, то передается null.

leads.orders.tagged boolean

Флаг тегирования лида. Возможные значения:

  • true
  • false
leads.orders.callInfo object

Если тег привоился звонку, то блок callInfo не пустой.

leads.orders.callInfo.callId string ID звонка в Calltouch
leads.orders.callInfo.callReferenceId string ID звонка из API-метода импорта звонков, может быть null
leads.orders.callInfo.sipCallId string ID звонка с АТС
leads.orders.requestInfo object Если тег привоился заявке, то блок requestInfo не пустой
leads.orders.requestInfo.requestId string ID заявки в Calltouch
leads.orders.requestInfo.requestNumber string ID заявки, переданный из формы сайта
leads.orders.error string Отображется причина ошибки тегирования

 

Если в запросе обнаруживаются ошибки валидации, то тегирование не выполняется и выводится ошибка:

{
    "meta": [],
    "data": {
        "type": "validationError",
        "apiErrorData": null,
        "validationErrorData": {
            "violations": [
                {
                    "fieldPath": "leads[0].addTags",
                    "message": "Не указан список тегов"
                }
            ]
        }
    }
}