Читать 12

Получения информации о настройках пулов номеров


Описание

В статье представлен метод API, позволяющий получить информацию о настроенных в проекте пулах номеров.

Запрос

POST: 

https://api.calltouch.ru/phone-service/v1/api/calltracking/sub-pool/list

HEADERS:

  • Access-Token — API-ключ
  • SiteId — ID ЛК Calltouch

Тело запроса в формате JSON.

Пример тела запроса

{
  "poolIds": [3333,44444],
  "poolType": "onlineStatic", 
  "poolStatus": "on",
  "poolName": {
     "value": "Остальные",
     "filterMode": "contains"
  },
  "displayOptions":
     "source": {
        "value": "yandex",
        "filterMode": "contains"
     },
     "campaign": {
        "value": "кампания"
     }
  },
  "phoneNumbers": [ "79001112233", "79005554433" ],
  "templateName": {
     "value": "ct_class_",
     "filterMode": "startwith"
  },
  "templateIds": [6776767, 4334343]
}

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


Параметр  Формат  Обязательный  Описание 
poolType string Нет

Фильтр по типу пула.

При указании этого параметра будут выгружены только пулы выбранного типа.

Возможные значения:

  • dynamic — динамические пулы;
  • onlineStatic — статические онлайн пулы;
  • offlineStatic — статические оффлайн пулы;
  • callback — пулы для обратных звонков.
poolStatus string Нет

Фильтр по статусу пула.

При использовании данного параметра будут выгружены только пулы в выбранном статусе.

Возможные значения:

  • on — пул включен;
  • off — пул выключен.
poolIds array[integer] Нет

Фильтр по id пулов.

При использовании данного параметра будут выгружены только пулы с указанными id.

В массиве можно указать несколько id пулов. Максимум 100 штук.
poolName.value string Нет

Фильтр по названию пула. 

При использовании данного параметра будут выгружены только пулы с подходящими названиями.

Максимум 100 символов.
poolName.filterMode string Нет Режим фильтрации по названию пула.

Описание режимов:
  • startwith — начинается с;
  • contains — содержит;
  • exact — полное соответствие (по умолчанию, если value заполнено, а filterMode не задан).
displayOptions.source.value string Нет

Фильтр по настройкам отображения пула, параметр "Источник (utm_source)".

При использовании данного параметра будут выгружены только пулы с подходящими источниками в настройках отображения пула.

Максимум 100 символов.
displayOptions.source.filterMode string Нет Режим фильтрации по настройкам отображения источника.

Описание режимов:
  • startwith — начинается с;
  • contains — содержит;
  • exact — полное соответствие (по умолчанию, если value заполнено, а filterMode не задан).
displayOptions.medium.value string Нет

Фильтр по настройкам отображения пула, параметр "Канал (utm_medium)".

При использовании данного параметра будут выгружены только пулы с подходящими источниками в настройках отображения пула.

Максимум 100 символов.
displayOptions.medium.filterMode string Нет Режим фильтрации по настройкам отображения канала.

Описание режимов:
  • startwith — начинается с;
  • contains — содержит;
  • exact — полное соответствие (по умолчанию, если value заполнено, а filterMode не задан).
displayOptions.campaign.value string Нет

Фильтр по настройкам отображения пула, параметр "Кампания (utm_campaign)".

При использовании данного параметра будут выгружены только пулы с подходящими источниками в настройках отображения пула.

Максимум 100 символов.
displayOptions.campaign.filterMode string Нет Режим фильтрации по настройкам отображения кампании.

Описание режимов:
  • startwith — начинается с;
  • contains — содержит;
  • exact — полное соответствие (по умолчанию, если value заполнено, а filterMode не задан).
displayOptions.content.value string Нет

Фильтр по настройкам отображения пула, параметр "Объявление (utm_content)".

При использовании данного параметра будут выгружены только пулы с подходящими источниками в настройках отображения пула.

Максимум 100 символов.
displayOptions.content.filterMode string Нет Режим фильтрации по настройкам отображения объявления.

Описание режимов:
  • startwith — начинается с;
  • contains — содержит;
  • exact — полное соответствие (по умолчанию, если value заполнено, а filterMode не задан).
displayOptions.term.value string Нет

Фильтр по настройкам отображения пула, параметр "Ключевое слово (utm_term)".

При использовании данного параметра будут выгружены только пулы с подходящими источниками в настройках отображения пула.

Максимум 100 символов.
displayOptions.term.filterMode string Нет Режим фильтрации по настройкам отображения ключевого слова.

Описание режимов:
  • startwith — начинается с;
  • contains — содержит;
  • exact — полное соответствие (по умолчанию, если value заполнено, а filterMode не задан).
phoneNumbers array Нет

Массив из string, где указываются подменные номера, по которым необходимо получить пулы.

Максимум 100 номеров.
phoneTemplateOptions.phone
TemplateName.value 		string Нет

Фильтр по названию шаблона подмены, привязанного к пулу.

phoneTemplateOptions.phone
TemplateName.filterMode 		string Нет Режим фильтрации по настройкам отображения названия шаблона.

Описание режимов:
  • startwith — начинается с;
  • contains — содержит;
  • exact — полное соответствие (по умолчанию, если value заполнено, а filterMode не задан).
templateOptions.templateIds array[integer] Нет

Фильтр по ID шаблонов подмены, привязанных к пулу.

Максимум 100 ID.

Ответ

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

{
  "data": [
    {
      "poolName": "Название пула",
      "poolId": 12345,
      "poolStatus": "on",
      "poolType": "dynamic",
      "visits": 400,
      "phoneAmount": 4,
      "phones": [
        "74953080100",
        "74953080101",
        "74953080102",
        "74953080103"
      ],
      "redirectId": 22222,
      "redirectName": "Номер 74993703880",
      "poolDefinitions": [
          {"param":"utm_source", "mode":"equals", "value":"yandex"},
      ],
      [
          {"param":"utm_medium", "comparison":"equals", "value":"cpc"},
          {"param":"utm_source", "comparison":"equals", "value":"google"}
      ],
      [
          {"param":"utm_medium", "comparison":"equals", "value":"cpm"}
      ],
      "displayOptions": {
         "source": "Utm Source",
         "medium": "Utm Medium",
         "campaign": "Utm Campaign",
         "content": "Utm Content",
         "term": "Utm Term"
      },
      "geoEquals": {
        "country": [ "RU" ],
        "region": [ "moskovskaya oblast", "kaliningradskaya oblast" ]
      },
      "geoIdEquals": {
        "country": [ "148" ],
        "region": [ "765", "1289" ]
      },
      "geoNotEquals": {
        "city": [ "vladimir" ]
      },
      "geoIdNotEquals": {
        "city": [ "24548" ]
      },
      "tags": [ "Тег1", "Тег2" ],
      "phoneTemplateNames": [ "class_1", "ct_replace" ],
      "phoneTemplateIds": [ 163738, 163739 ]
    },
    {
      ...
    }
  ]

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

Параметр Формат  Описание 
data[n].poolName string

Название пула

data[n].poolId string

ID пула

data[n].poolStatus string

Статус пула. Варианты:

  • on — пул включен;
  • off — пул выключен.
data[n].poolType string Тип пула. Варианты:
  • dynamic — динамические пулы;
  • onlineStatic — статические онлайн пулы;
  • offlineStatic — статические оффлайн пулы;
  • callback — пулы для обратных звонков.
data[n].visits integer Посещаемость пула. Для всех пулов кроме динамики - null.
data[n].phoneAmount integer Количество номеров в пуле.
data[n].phones array[string] Массив из номеров телефонов в пуле.
data[n].redirectId integer ID используемого сценария переадресации в пуле.
data[n].redirectName string Название используемого сценария переадресации в пуле.
data[n].poolDefinitions array[object]

Условия отслеживания пула.

data[n].poolDefinitions[m][o].param string

Тип параметров отслеживания. 

Варианты:

  • utm_source — Метка utm_source;
  • utm_medium — Метка utm_medium;
  • utm_campaign — Метка utm_campaign;
  • utm_content — Метка utm_content;
  • utm_term — Метка utm_term;
  • gclid — Метка GCLID;
  • yclid — Метка YCLID;
  • ymclid — Метка YMCLID;
  • search — Органика;
  • referral — Реферал;
  • direct — Прямой заход;
  • url — Страница входа;
  • offline_yandex_direct — Визитка Яндекс.Директ;
  • offline_google_adwords — Визитка Google Ads;
  • phone_cpa_platform — Marketcall;
  • phone_auto_ru_show — AutoRu;
  • phone_avito_call — Авито Pro;
  • phone_cian_call — ЦИАН.
data[n].poolDefinitions[m][o].mode string

Режим проверки значения параметра. 

Варианты:

  • equals — полное соответствие;
  • contains — содержит;
  • start_with — начинается с;
  • end_with — заканчивается на;
  • regexp — регулярное выражение.

Для параметров, не имеющих заданных значений, присваевается null.

data[n].poolDefinitions[m][o].value string Значение параметра отслеживания.
Для параметров, не имеющих заданных значений, присваевается null.
data[n].displayOptions.source string Настройки отображения пула "Источник (utm_source)".
data[n].displayOptions.medium string Настройки отображения пула "Канал (utm_medium)".
data[n].displayOptions.campaign string Настройки отображения пула "Кампания (utm_campaign)".
data[n].displayOptions.content string Настройки отображения пула "Объявление (utm_content)".
data[n].displayOptions.term string Настройки отображения пула "Ключевое слово (utm_term)".
data[n].geoEquals object Настройки геотаргетинга пула, включённые названия локаций.
data[n].geoEquals.country array[string]

Страна, где пул должен работать. 

data[n].geoEquals.region array[string]

Регион, где пул должен работать.

data[n].geoEquals.city array[string]

Город, где пул должен работать.

data[n].geoIdEquals object Настройки геотаргетинга пула, включённые ID локаций.
data[n].geoIdEquals.country array[integer]

Страна, где пул должен работать. 

data[n].geoIdEquals.region array[integer]

Регион, где пул должен работать.

data[n].geoIdEquals.city array[integer]

Город, где пул должен работать.

data[n].geoNotEquals object Настройки геотаргетинга пула, исключённые названия локаций.
data[n].geoNotEquals.country array[string]

Страна, где пул не должен работать.

data[n].geoNotEquals.region array[string]

Регион, где пул не должен работать.

data[n].geoNotEquals.city array[string]

Город, где пул не должен работать.

data[n].geoIdNotEquals object Настройки геотаргетинга пула, исключённые ID локаций.
data[n].geoIdNotEquals.country array[integer]

Страна, где пул не должен работать.

data[n].geoIdNotEquals.region array[integer]

Регион, где пул не должен работать.

data[n].geoIdNotEquals.city array[integer]

Город, где пул не должен работать.

data[n].poolTags array[string] Теги, для автотегирования звонков на номера пула.
data[n].phoneTemplateNames array[string] Названия шаблонов подмены, привязанных к пулу.
data[n].phoneTemplateIds array[integer] ID шаблонов подмены, привязанных к пулу.

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

Ошибки валидации

Если в запросе во входных параметрах обнаруживаются ошибки валидации — отвечаем кодом 400 и выводим ошибку, указывающую на проблемное поле, с пояснением, вида:

{
    "meta": [],
    "data": {
        "type": "validationError",
        "validationErrorData": {
            "violations": [
                {
                    "fieldPath": "Указание на ошибочное поле",
                    "message": "Описание в чем именно ошибка"
                }
            ]
        }
    }
}

Список типовых ответов при запросах с некорректными данными в теле API запроса вы можете посмотреть в этой статье.

Ошибки авторизации

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

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

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

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


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