Комментирование лидов
Запрос
POST: https://api.calltouch.ru/lead-service/v1/api/comment/lead/add
HTTP-заголовки:
- Access-Token – API-ключ
- SiteId – ID ЛК Calltouch
Тело запроса в формате JSON:
{
"comments": [
// Лид 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"
}
}
],
"addComment": "Комментарий к лиду"
},
// Лид N
...
]
}
Параметры запроса
Параметр | Формат | Обязательный | Описание |
comments | 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.addComment | string | Да |
Добавление комментария к лиду |
Ответ
Процесс добавления комментария запускается сразу же после отправки запроса, после чего сразу же возвращается и ответ, пример:
{
"meta": [],
"data": {
"comments": [
{
"callInfo": { "callId": 12692441, "callReferenceId": "test321", "sipCallId": null }, "requestInfo": null, "commented": true, "error": null
}
]
}
}
{
"meta": [],
"data": {
"message": "Ошибка доступа"
}
}
Если API-токен указан не верно, то комментирование не выполняется и выводится ошибка:
{
"message": "Access token не найден"
}
Параметры ответа
Параметр | Формат |
Описание |
data.comments[i].commented | boolean |
Флаг комментирования лида. Возможные значения:
|
data.comments[i].callInfo | object |
Если комментарий привоился звонку, то блок callInfo не пустой. |
data.comments[i].callInfo.callId | string | ID звонка в Calltouch |
data.comments[i].callInfo.callReferenceId | string | ID звонка из API-метода импорта звонков, может быть null |
ldata.comments[i].callInfo.sipCallId | string | ID звонка с АТС |
data.comments[i].requestInfo | object | Если комментарий привоился заявке, то блок requestInfo не пустой |
data.comments[i].requestInfo.requestId | string | ID заявки в Calltouch |
data.comments[i].requestInfo.requestNumber | string | ID заявки, переданный из формы сайта |
data.comments[i].error | string | Отображется причина ошибки добавления комментария |
Если в запросе обнаруживаются ошибки валидации, то комментирование не выполняется и выводится ошибка:
{ "meta": [], "data": { "type": "validationError", "apiErrorData": null, "validationErrorData": { "violations": [{ "fieldPath": "comments[0].addComment", "message": "This value should not be blank." }] } } }