Тегирования лидов
Запрос
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 тип маппинга в приоритете. |
Тип матчинга. Возможные значения:
|
leads.matching .requestParams |
object | Обязательно, если "type": "request" | Параметры матчинга заявки по ID |
leads.matching .requestParams.requestId |
integer / string | Обязательно, если "type": "request" |
Возможные параметры:
|
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" |
Возможные параметры:
|
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" |
Типы заявок, среди которых будет происходить поиск для тегирования. Возможные значения:
|
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": { |
leads.addTags.overwrite | boolean | Нет | Перезаписывать ли существующие теги у лида или нет. Обязательно, если указывается addTags. |
Ответ
Процесс тегирования запускается сразу же после отправки запроса, после чего сразу же возвращается и ответ, пример:
{
"meta": [],
"data": {
"leads": [
{
"callInfo": null,
"requestInfo": {
"requestId": 1257513,
"requestNumber": "1257513"
},
"error": null
}
]
}
}
{
"meta": [],
"data": {
"message": "Ошибка доступа"
}
}
Если API-токен указан не верно, то тегирование не выполняется и выводится ошибка:
{
"message": "Access token не найден"
}
Параметры ответа
Параметр | Формат |
Описание |
leads.orders.tagged | boolean |
Флаг тегирования лида. Возможные значения:
|
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": "Не указан список тегов"
}
]
}
}
}