Дополнительно
11 минут

Комментирование лидов

Запрос

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 тип маппинга в приоритете. Тип матчинга. Возможные значения:
  • 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.addComment string Да

Добавление комментария к лиду

Ответ

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

{
    "meta": [],
    "data": {
        "comments": [
            {
                "callInfo": { "callId": 12692441, "callReferenceId": "test321", "sipCallId": null }, "requestInfo": null, "commented": true, "error": null
            }
        ]
    }
}
Если API-токен не указан, то комментирование не выполняется и выводится ошибка:

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

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


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

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

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

Описание

data.comments[i].commented boolean

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

  • true
  • false
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."
            }]
        }
    }
}