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

Оцените статью