Читать 7

Тегирование лидов


Описание

В статье описан 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": "nearestUniq",
                        "searchDepth": 120
                     }
                },
                {
                     "type": "leadContact",
                     "leadContactParams": {
                        "emails": ["name@server.com"],
                        "phones": ["79157771122", "+7 (915) 888-11-22"],
                        "date":"01-10-2020 12:00:00",
                        "tags": ["тег1","тег2"],
                        "tagsLogic": "and",
                        "leadTypeToMatch": "nearestUniq",
                        "searchDepth": 120
                      }
                 }
                 ],
                "addTags": {
                       "overwrite": false,
                       "tags":
                           [
                           {"tag": "Тег 1"},
                           {"tag": "Тег 2"},
                           {"tag": "Тег N"}
                           ]
                 }
                 },

                 // Лид N

                ...
    ]
}

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

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

Здесь задается приоритет использования разных типов матчинга, по которым мы будем пытаться найти лид для тегирования. Чем выше находится строка с типом матчинга, тем больший приоритет она имеет. Если матчинга завершится на каком-либо типе, остальные типы ниже будут проигнорированы. Одинаковые типы матчинга могут повторяться, но общее кол-во типов не должно превышать 20 строк.

leads.matching

.type

string
 Обязательно нужно указать хотя бы 1 тип матчинга в приоритете.

Тип матчинга. Возможные значения:

  • call — поиск звонка по ID
  • request — поиск заявки по ID
  • callContact — поиск звонка по номеру телефона / дате
  • requestContact — поиск заявки по номеру телефона / почте / дате
  • leadContact — поиск лида по номеру телефона / почте / дате.
Подробное описание полей в объекте matching в этой статье.
leads.addTags object Нет

Добавление тегов к лиду.

leads.addTags.tags array Нет

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

Формат: 

"tags": [
    { "tag": "Тег 1" },
    { "tag": "Тег 2" }
]
leads.addTags.overwrite boolean Нет Перезаписывать ли существующие теги у лида или нет. Не обязательный если указывается addTags. Возможные значения:
  • true — все существующие теги перезапишутся теми что были переданы
  • false — переданные в запросе теги добавяться к существующим.

Ответ

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

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

{
    "meta": [],
    "data": {
        "leads": [{
            "callInfo": {
                "callId": 12692441,
                "callReferenceId": "test321",
                "sipCallId": null
            },
            "requestInfo": null,
            "tagged": true,
            "error": null
        }]
    }
}

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

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

Описание

data.leads.tagged boolean

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

  • true
  • false
data.leads.callInfo object

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

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

 

Типовые ошибки

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

{
    "meta": [],
    "data": {
        "type": "validationError",
        "apiErrorData": null,
        "validationErrorData": {
            "violations": [{
                "fieldPath": "leads[0].addTags.tags",
                "message": "This value should not be blank."
            }]
        }
    }
}

Если в запросе указаны некорректные авторизационные данные — то выводится ошибка. 
Список типовых ответов при запросах с некорректными авторизационными данными, или некорректными данными в теле API запроса вы можете посмотреть в этой статье.

Система баллов API Calltouch

Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов. За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch.

Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).

Не нашли решение проблемы?
Заполните форму, и мы вам поможем.
Похожие статьи
Недавно просмoтренные