Адресная книга

Списки контактов

Сервис адресной книги позволяет работать со списками контактов для отправки рассылок.

Создание списка контактов

Для создания списка контактов необходимо вызвать POST /address-book-api/contact-groups, передавая параметры списка в теле запроса и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
fields (optional)	array[Fields]	Параметры пользовательских макросов (полей) контактов в списке, в дополнение к основным полям контакта.
name	string	Название списка контактов.
type (optional)	string	Тип списка контактов. Возможные значения: ○ STANDARD - обычный список. ○ STOPLIST - если контактам из списка не нужно делать рассылку. ○ PUSH - список для отправки push-уведомлений. ○ OMNI_API - используется только при отправке транзакционных сообщений, создать список данного вида вручную нельзя. Списки данного типа также не отображаются при получении всех списков.
autoDeleteEnabled (optional)	boolean	Автоматическое удаление контактов, если: ○ контакт не использовался больше двух недель. ○ у контакта отсутствовали какие-либо данные (телефон, email и т.д.).

Fields

Параметр	Тип данных	Описание
name	string	Название поля.
displayName (optional)	string	Название поля, которое будет отображаться в личном кабинете.
type (optional)	string	Тип поля. Возможные значения: ○ 0 - дата/время ○ 1 - TRUE/FALSE ○ 2 - число ○ 3 - текст ○ 5 - объект ○ 8 - дата
values	array[string]	Массив возможных значений поля, если они предусмотрены. Например: ["gender.male", "gender.female"].

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

{
  "fields": [
    {
      "displayName": "NickName",
      "name": "Nickname",
      "type": 3
    },
    {
      "displayName": "Automobile",
      "name": "Auto",
      "type": 3
    }
  ],
  "name": "TestList",
  "type": "STANDARD",
  "autoDeleteEnabled": true
}

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

Параметр	Тип данных	Описание
result	string	ID списка контактов.
reasons	array	Массив ошибок, произошедших во время обработки запроса. Указывается только при "code": "REJECTED".
reasons.key	string	Код ошибки.
reasons.ref	string	Ссылка на параметр, в котором произошла ошибка.
reasons.defaultMessage	string	Сообщение с описанием ошибки.
description	string	Описание ошибки.

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

OK

{
  "result": "3576515602081985000"
}

NULL

{
  "result": null,
  "reasons": [
    {
      "key": "name.must.be.not.null",
      "ref": "name",
      "defaultMessage": "не должно равняться null"
    }
  ],
  "description": "Ошибки аргумента: (поле: name -> не должно равняться null)"
}

Загрузка контактов в список

Для загрузки контактов в список необходимо вызвать POST /address-book-api/contacts/batch, передавая параметры контактов в теле запроса и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
zoneOffset (optional)	integer	Смещение времени для контакта от UTC+0 в минутах.

Тело запроса

Параметр	Тип данных	Описание
contactGroupId	integer	ID списка контактов.
contacts	array[Contacts]	Массив контактов.
duplicateCheckField (optional)	integer	Проверка на дублирование данных контакта. Возможные значения: ○ phone - проверка номера телефона. ○ email - проверка email.

Contacts

Параметр	Тип данных	Описание
email (optional)	string	Email контакта.
phone (optional)	string	Номер телефона контакта в международном формате, согласно стандарту E.164.
fields (optional)	array[Fields]	Параметры макросов (полей) контактов в списке, в том числе и основных полей контакта.
pushInfo (optional)	array[PushInfo]	Данные, необходимые для получения push-уведомлений. Используется только со списками типа PUSH.

Fields

Параметр	Тип данных	Описание
name	string	Название поля.
displayName (optional)	string	Название поля в личном кабинете.
type (optional)	string	Тип поля. Возможные значения: ○ 0 - дата/время ○ 1 - TRUE/FALSE ○ 2 - число ○ 3 - текст ○ 5 - объект ○ 8 - дата
value	array[string]	Значение поля.

PushInfo

Параметр	Тип данных	Описание
appId	string	ID приложения.
os	integer	Операционная система. Возможные значения: ○ 0 - iOS. ○ 1 - Android. ○ 2 - Huawei.
pushToken	string	Токен устройства.

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

{
  "contactGroupId": 3576505602081984000,
  "contacts": [
    {
      "email": "john@ggl.cm",
      "fields": [
        {
          "name": "name",
          "type": 3,
          "value": "John"
        },
        {
          "name": "surname",
          "type": 3,
          "value": "Smith"
        },
        {
          "name": "gender",
          "type": 3,
          "value": "gender.male"
        }
      ],
      "phone": "79100000000",
      "pushInfo": [
        {
          "appId": "23244532534",
          "os": 0,
          "pushToken": "23fsdivfwrq34frvsfgwgrst4334rfw"
        }
      ]
    }
  ],
  "duplicateCheckField": "phone"
}

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

Параметр	Тип данных	Описание
code	string	Указывает на результат обработки запроса. 1. OK - успешно обработано. 2. REJECTED - запрос отклонен.
result	array	Результат запроса.
result.contactId	string	ID добавленного контакта. Указывается только при "code": "OK".
result.localizationKey	string	Код ошибки.
result.fieldName	string	Ссылка на параметр, в котором произошла ошибка.
result.displayName	string	Название параметра.
description	string	Описание ошибки.

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

OK

{
  "result": [
    {
      "code": "OK",
      "result": {
        "contactId": "3379c731a0734800-337a7406f274fe80"
      }
    }
  ]
}

REJECTED

{
  "result": [
    {
      "code": "REJECTED",
      "result": {
        "localizationKey": "DUPLICATE_VALUE",
        "fieldName": "phone",
        "displayName": "Телефон"
      },
      "description": "Дубликат"
    }
  ]
}

Получение всех списков контактов

Для получения всех списков контактов необходимо вызвать GET /address-book-api/contact-groups, передавая параметры списков и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
limit (optional)	integer	Количество выводимых в ответе строк.
offset (optional)	integer	Номер строки, с которой будет выводиться результат (смещение).
name (optional)	string	Название списка контактов.
from (optional)	string	Фильтр по дате создания рассылки - начало диапазона. Формат: YYYY-MM-DD HH:MM:SS.
to (optional)	string	Фильтр по дате создания рассылки - конец диапазона. Формат: YYYY-MM-DD HH:MM:SS.
type (optional)	array[string]	Тип списка контактов. Возможные значения: ○ STANDARD - обычный список. ○ STOPLIST - если контактам из списка не нужно делать рассылку. ○ PUSH - список для отправки push-уведомлений.
zoneOffset (optional)	integer	Смещение времени для контакта от UTC+0 в минутах.
autoDeleteEnabled (optional)	boolean	Автоматическое удаление контактов, если: ○ контакт не использовался больше двух недель. ○ у контакта отсутствовали какие-либо данные (телефон, email и т.д.).

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

curl https://api.devino.online/address-book-api/contact-groups?limit=10&offset=0 \
-h 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' 

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

Параметр	Тип данных	Описание
companyId	integer	ID компании.
contactGroupId	string	ID списка контактов.
name	string	Название списка контактов.
creationDate	string	Дата создания списка контактов.
lastUpdate	string	Дата последнего изменения списка контактов.
fields (optional)	array[Fields]	Параметры макросов (полей) контактов в списке, в том числе и основных полей контакта.
contactsCount	integer	Количество контактов в списке.
segmentsCount	integer	Количество сегментов в списке.
type	string	string

Fields

Параметр	Тип данных	Описание
name	string	Название поля.
displayName	string	Название поля в личном кабинете.
type	string	Тип поля. Возможные значения: ○ 0 - дата/время ○ 1 - TRUE/FALSE ○ 2 - число ○ 3 - текст ○ 5 - объект ○ 8 - дата
values	array[string]	Массив возможных значений поля, если они предусмотрены. Например: ["gender.male", "gender.female"].
isDefault	boolean	Отображается ли поле по умолчанию.

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

{
  "result": [
    {
      "contactGroupId": "23556345674567625",
      "companyId": 452345234,
      "name": "ContactsList",
      "creationDate": "2022-10-22T18:14:21",
      "lastUpdate": "2022-10-22T18:14:21",
      "fields": [
        {
          "name": "name",
          "displayName": "Имя",
          "type": 3,
          "isDefault": true
        }
        {
          "name": "gender",
          "displayName": "Пол",
          "type": 3,
          "isDefault": true,
          "values": [
            "gender.male",
            "gender.female"
          ]
        },
        {
          "name": "country",
          "displayName": "Страна",
          "type": 3,
          "isDefault": true
        },
        {
          "name": "city",
          "displayName": "Город",
          "type": 3,
          "isDefault": true
        }
      ],
      "contactsCount": "34234",
      "segmentsCount": "2",
      "type": "STANDARD",
      "autoDeleteEnabled": false
    }
  ]
}

Получение всех контактов из конкретного списка

Для получения всех контактов из конкретного списка необходимо вызвать GET /address-book-api/contacts/http/range, передавая параметры контактов и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
contactGroupId	string	ID списка контактов.
descOrder (optional)	boolean	Порядок сортировки. Возможные значения: ○ false - по возрастанию (asc) ○ true - по убыванию (desc)
limit (optional)	integer	Количество выводимых в ответе строк.
offset (optional)	integer	Номер строки, с которой будет выводиться результат (смещение).
pushToken (optional)	string	Токен устройства.
queryName (optional)	string	Поле запроса для фильтра.
queryOperator (optional)	string	Оператор запроса для фильтра. Возможные значения: ○ ex - существует (EXISTS) ○ eq - равняется (EQUALS) ○ neq - не равняется (NOT_EQUALS) ○ gt - больше чем (GREATER_THAN) ○ lt - меньше чем (LESS_THAN) ○ ngt - не больше чем (NOT_GREATER_THAN) ○ nlt - не меньше чем (NOT_LESS_THAN) ○ inc - содержит (CONTAINS) ○ ninc - не содержит (NOT_CONTAINS) ○ sw - начинается с (STARTS_WITH) ○ ew - заканчивается на (ENDS_WITH) ○ nsw - не начинается с (NOT_STARTS_WITH) ○ new - не заканчивается на (NOT_ENDS_WITH) ○ range - в диапазоне (RANGE) ○ nrange - не в диапазоне (NOT_IN_RANGE) ○ ma - совпадает (MATCHES) ○ nma - не совпадает (NOT_MATCHES)
queryValue (optional)	string	Значение запроса для фильтра.
segmentId (optional)	string	ID сегмента.
sortByField (optional)	string	Поле, по которому будет проходить сортировка.
zoneOffset (optional)	integer	Смещение времени для контакта от UTC+0 в минутах.
subscriptionChannel (optional)	string	Канал подписки. Возможные значения: EMAIL, FLASHCALL, HLR, PUSH, SMS, VIBER, VK, VOICE, WHATSAPP.
subscriptionState (optional)	string	Тип подписки. Возможные значения: ○ ALL - все контакты. ○ SUBSCRIBED - контакты, подписанные на рассылку. ○ UNSUBSCRIBED - отписавшиеся контакты.

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

curl https://api.devino.online/address-book-api/contacts/http/range?limit=10&offset=0&contactGroupId=3576515602081985000 \
-h 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
-h 'Content-Type: application/json'
-h 'Accept: application/json'

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

Параметр	Тип данных	Описание
companyId	integer	ID компании.
contactGroupId	integer	ID списка контактов.
contactId	string	ID контакта.
creationDate	string	Дата создания контакта.
lastUpdate	string	Дата последнего изменения контакта.
fields	array[Fields]	Параметры макросов (полей) контактов в списке, в том числе и основных полей контакта.
email	string	Email контакта.
phone	string	Номер телефона контакта.
unsubscribedData	array[UnsubscribedData]	Данные об отписке контакта.
pushInfo	array[PushInfo]	Данные, необходимые для получения push-уведомлений.

Fields

Параметр	Тип данных	Описание
name	string	Название поля.
displayName	string	Название поля в личном кабинете.
type	string	Тип поля. Возможные значения: ○ 0 - дата/время ○ 1 - TRUE/FALSE ○ 2 - число ○ 3 - текст ○ 5 - объект ○ 8 - дата
value	array[string]	Значение поля.
values	array[string]	Массив возможных значений поля, если они предусмотрены. Например: ["gender.male", "gender.female"].
isDefault	boolean	Отображается ли поле по умолчанию.

UnsubscribedData

Параметр	Тип данных	Описание
channelList	array[UnsubscribedChannel]	Данные каналов отписки.
companyId	integer	ID компании.
data	string	Данные отписки (номер телефона, email или токен устройства).
dataType	string	Тип данных отписки. Возможные значения: EMAIL, PHONE, TOKEN.
updatedAt	string	Дата последнего изменения отписки.

UnsubscribedChannel

Параметр	Тип данных	Описание
channel	string	Канал отписки. Возможные значения: EMAIL, FLASHCALL, HLR, PUSH, SMS, VIBER, VK, VOICE, WHATSAPP.
unsubscribedAt	integer	Дата отписки.
unsubscribedType	string	Тип отписки. Возможно только значение SPAM.

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

{
  "result": [
    {
      "contactId": "31a24ce55d4a8e00-31a251fea18b9280",
      "companyId": 112233,
      "contactGroupId": "3576515602081985000",
      "creationDate": "2020-10-20 09:01:05",
      "lastUpdate": "2020-10-20 09:01:05",
      "phone": "79100000000",
      "email": "valya@yandex.ru",  
      "fields": [
        {
          "name": "name",
          "displayName": "Имя",
          "type": 3,
          "isDefault": true
        },
        {
          "name": "surname",
          "displayName": "Фамилия",
          "type": 3,
          "isDefault": true
        },
        {
          "name": "gender",
          "displayName": "Пол",
          "type": 3,
          "isDefault": true,
          "values": [
            "gender.male",
            "gender.female"
          ]
        }
      ],
      "unsubscribedData": [
        {
          "companyId": 112233,
          "data": "valya@yandex.ru",
          "dataType": "EMAIL",
          "channelList": [
            {
              "channel": "EMAIL",
              "unsubscribedAt": "2020-10-21T08:13:55",
              "unsubscribedType": "SPAM"
            }
          ],
          "updatedAt": "2020-10-21 08:13:55"
        }
      ]
    }
  ]
}

Удаление списка контактов

Для удаления списка или списков контактов необходимо вызвать DELETE /address-book-api/contacts-groups, передавая ID списков контактов и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
ids	array[integer]	ID списка контактов. Можно передавать несколько.

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

curl -X DELETE https://api.devino.online/address-book-api/contact-groups?ids=5435476543542&ids=435467586654&ids=4325364758 \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

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

Параметр	Тип данных	Описание
result	array	Массив с результатами запроса. Для каждого списка контактов будет свой результат.
result.code	string	Указывает на результат обработки запроса. 1. OK - успешно обработано. 2. REJECTED - запрос отклонен.
result.result	string	ID списка контактов.
result.description	string	Описание ошибки. Указывается только при "code": "REJECTED".
reasons	array	Массив ошибок, произошедших во время обработки запроса. Указывается только при "code": "REJECTED".
reasons.key	string	Код ошибки.
reasons.ref	string	Ссылка на параметр, в котором произошла ошибка.

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

{
  "result": [
    {
      "code": "OK",
      "result": "5435476543542"
    },
    {
      "code": "OK",
      "result": "435467586654"
    },
    {
      "code": "OK",
      "result": "4325364758"
    }
  ]
}

Сегменты

Списки контактов могут подразделяться на сегменты. Сегменты позволяют отфильтровать контакты из списка.

Внимание

У одного списка контактов может быть не более 20 сегментов.

Создание сегмента

Для создания сегмента списка контактов необходимо вызвать POST /address-book-api/segments, передавая параметры сегмента в теле запроса и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
contactGroupId	integer	ID списка контактов.
name	string	Название сегмента. Внутри одного списка контактов имена сегментов не могут повторяться.
query	array[object]	Параметры отбора контактов для сегмента.

Query

Параметр	Тип данных	Описание
filterOperator	string	Оператор фильтров. Доступны значения: ○ AND - и ○ OR - или ○ EXCLUDE - исключить
filterElements	array[object]	Данные фильтров. Внутри массива может быть не более двух объектов.
name (optional)	string	Название атрибута контакта для отбора контактов.
operator (optional)	string	Оператор фильтра контактов.
value (optional)	string	Значение атрибута контакта для отбора контактов.

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

Важно

При составлении запроса важно учитывать условия:

1. Внутри массива filterElements может быть только два объекта (фильтра).
2. Если используется параметр filterOperator, то параметры name, operator, value будут указаны только во вложенном объекте внутри массива filterElements.
3. Если используются параметры name, operator, value, в том же объекте необходимо указать параметр filterOperator для валидации запроса. Однако в самих фильтрах он использоваться не будет. Прочитайте пояснение к примерам запроса для лучшего понимания.

Для удобства лучше использовать не более трех фильтров на один сегмент.

Без filterElements

Параметр "filterOperator": "AND" в данном случае нужен лишь для валидации запроса, в самом сегменте он использоваться не будет.

{
  "contactGroupId": 3648143200368952320,
  "name": "segmentName",
  "query": [
    {
      "filterOperator": "AND",
      "filterElements": [
        {
          "name": "name",
          "operator": "sw",
          "value": "John"
        }
      ]
    }
  ]
}

С одним filterElements

В данном запросе содержатся два фильтра: в сегмент добавятся контакты с номером телефона, начинающимся на 7999, ИЛИ с именем John. Параметры "filterOperator": "AND" в данном случае нужны лишь для валидации запроса, в самом сегменте они использоваться не будут.

{
  "contactGroupId": 3648143200368952320,
  "name": "segmentName",
  "query": [
    {
      "filterOperator": "OR",
      "filterElements": [
        {
          "filterOperator": "AND",
          "filterElements": [
            {
              "name": "name",
              "operator": "sw",
              "value": "John"
            }
          ]
        },
        {
          "filterOperator": "AND",
          "filterElements": [
            {
              "name": "phone",
              "operator": "eq",
              "value": "79995854330"
            }
          ]
        }
      ]
    }
  ]
}

С двумя filterElements

В данном запросе содержатся три фильтра: в сегмент добавятся контакты с номером телефона, начинающимся на 7999, ИЛИ с именем John ИЛИ с фамилией, начинающейся на A. Параметры "filterOperator": "AND" в данном случае нужны лишь для валидации запроса, в самом сегменте они использоваться не будут.

{
  "contactGroupId": 3648143200368952320,
  "name": "segmentName",
  "query": [
    {
      "filterOperator": "OR",
      "filterElements": [
        {
          "filterOperator": "AND",
          "filterElements": [
            {
              "filterOperator": "OR",
              "filterElements": [
                {
                  "filterOperator" : "AND",
                  "filterElements" : [
                    {
                      "name" : "surname",
                      "operator" : "sw",
                      "value" : "А"
                    }
                  ]
                },
                {
                  "filterOperator": "AND",
                  "filterElements": [
                    {
                      "name": "name",
                      "operator": "eq",
                      "value": "John"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "filterOperator": "AND",
          "filterElements": [
            {
              "name": "phone",
              "operator": "sw",
              "value": "7999"
            }
          ]
        }
      ]
    }
  ]
}

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

Параметр	Тип данных	Описание
result	string	ID созданного сегмента списка контактов.

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

{
  "result": "3775660349864609792"
}

Редактирование сегмента

Для редактирования сегмента списка контактов необходимо вызвать PUT /address-book-api/segments/{segmentId}, передавая параметры сегмента в теле запроса и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
segmentId	integer	ID сегмента. Path-параметр.
name	string	Название сегмента. Внутри одного списка контактов имена сегментов не могут повторяться.
query	array[object]	Параметры фильтров контактов для сегмента.

Query

Параметр	Тип данных	Описание
filterOperator	string	Оператор фильтров. Доступны значения: ○ AND - и ○ OR - или ○ EXCLUDE - исключить
filterElements	array[object]	Данные фильтров. Внутри массива может быть не более двух объектов.
name (optional)	string	Название атрибута контакта для отбора контактов.
operator (optional)	string	Оператор фильтра контактов.
value (optional)	string	Значение атрибута контакта для отбора контактов.

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

Важно

При составлении запроса важно учитывать условия:

1. Внутри массива filterElements может быть только два объекта (фильтра).
2. Если используется параметр filterOperator, то параметры name, operator, value будут указаны только во вложенном объекте внутри массива filterElements.
3. Если используются параметры name, operator, value, в том же объекте необходимо указать параметр filterOperator для валидации запроса. Однако в самих фильтрах он использоваться не будет. Прочитайте пояснение к примерам запроса для лучшего понимания.

Для удобства лучше использовать не более трех фильтров на один сегмент.

Без filterElements

Параметр "filterOperator": "AND" в данном случае нужен лишь для валидации запроса, в самом сегменте он использоваться не будет.

{
  "contactGroupId": 3648143200368952320,
  "name": "segmentName",
  "query": [
    {
      "filterOperator": "AND",
      "filterElements": [
        {
          "name": "name",
          "operator": "sw",
          "value": "John"
        }
      ]
    }
  ]
}

С одним filterElements

В данном запросе содержатся два фильтра: в сегмент добавятся контакты с номером телефона, начинающимся на 7999, ИЛИ с именем John. Параметры "filterOperator": "AND" в данном случае нужны лишь для валидации запроса, в самом сегменте они использоваться не будут.

{
  "contactGroupId": 3648143200368952320,
  "name": "segmentName",
  "query": [
    {
      "filterOperator": "OR",
      "filterElements": [
        {
          "filterOperator": "AND",
          "filterElements": [
            {
              "name": "name",
              "operator": "sw",
              "value": "John"
            }
          ]
        },
        {
          "filterOperator": "AND",
          "filterElements": [
            {
              "name": "phone",
              "operator": "eq",
              "value": "79995854330"
            }
          ]
        }
      ]
    }
  ]
}

С двумя filterElements

В данном запросе содержатся три фильтра: в сегмент добавятся контакты с номером телефона, начинающимся на 7999, ИЛИ с именем John ИЛИ с фамилией, начинающейся на A. Параметры "filterOperator": "AND" в данном случае нужны лишь для валидации запроса, в самом сегменте они использоваться не будут.

{
  "contactGroupId": 3648143200368952320,
  "name": "segmentName",
  "query": [
    {
      "filterOperator": "OR",
      "filterElements": [
        {
          "filterOperator": "AND",
          "filterElements": [
            {
              "filterOperator": "OR",
              "filterElements": [
                {
                  "filterOperator" : "AND",
                  "filterElements" : [
                    {
                      "name" : "surname",
                      "operator" : "sw",
                      "value" : "А"
                    }
                  ]
                },
                {
                  "filterOperator": "AND",
                  "filterElements": [
                    {
                      "name": "name",
                      "operator": "eq",
                      "value": "John"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "filterOperator": "AND",
          "filterElements": [
            {
              "name": "phone",
              "operator": "sw",
              "value": "7999"
            }
          ]
        }
      ]
    }
  ]
}

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

При успешном результате возвращается HTTP-статус 200 и переменная result со значением null.

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

{
  "result":null
}

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

Для получения информации обо всех сегментах списка контактов необходимо вызвать GET /address-book-api/segments, передавая параметры сегмента и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
contactGroupId	integer	ID списка контактов.

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

curl -X GET 'https://api.devino.online/address-book-api/segments?contactGroupId=3763139836589723520' \
-H "Authorization:Key dfb35a79-81eb-4b73-bc38-4089770a484d"

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

Параметр	Тип данных	Описание
segmentId	string	ID сегмента.
companyId	integer	ID компании, к которой принадлежит пользователь.
contactGroupId	string	ID списка контактов, к которому принадлежит сегмент.
name	string	Название сегмента.
creationDate	string	Дата и время создания сегмента.
lastUpdate	string	Дата и время последнего обновления сегмента.
query	array[object]	Параметры фильтров контактов для сегмента.
contactsCount	string	Количество контактов в сегменте.

Query

Параметр	Тип данных	Описание
filterOperator	string	Оператор фильтров. Доступны значения: ○ AND - и. ○ OR - или. ○ EXCLUDE - исключить.
filterElements	array[object]	Данные фильтров. Внутри массива может быть не более двух объектов.
name	string	Название атрибута контакта для отбора контактов.
operator	string	Оператор фильтра контактов.
value	string	Значение атрибута контакта для отбора контактов.

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

Примечание

Для понимания работы параметра filterOperator рекомендуется изучить примеры создания сегментов.

{
  "result": [
    {
      "segmentId": "3782027397081381760",
      "companyId": 508833221,
      "contactGroupId": "3707311347799370752",
      "name": "segmentName",
      "creationDate": "2023-11-28 14:37:00",
      "lastUpdate": "2023-11-28 14:37:00",
      "query": [
        {
          "filterOperator": "OR",
          "filterElements": [
            {
              "filterOperator": "AND",
              "filterElements": [
                {
                  "name": "name",
                  "operator": "sw",
                  "value": "A"
                }
              ]
            },
            {
              "filterOperator": "AND",
              "filterElements": [
                {
                  "name": "phone",
                  "operator": "nsw",
                  "value": "7999"
                }
              ]
            }
          ]
        }
      ],
      "contactsCount": "34882"
    },
    {
      "segmentId": "3783239562062773120",
      "companyId": 508833221,
      "contactGroupId": "3707311347799370752",
      "name": "segment",
      "creationDate": "2023-12-05 07:10:25",
      "lastUpdate": "2023-12-05 08:47:43",
      "query": [
        {
          "filterOperator": "OR",
          "filterElements": [
            {
              "name": "name",
              "operator": "eq",
              "value": "John"
            }
          ]
        }
      ],
      "contactsCount": "29423"
    }
  ]
}

Получение информации о сегменте

Для получения информации о сегменте списка контактов необходимо вызвать GET /address-book-api/segments/{segmentId}, передавая параметры сегмента и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
segmentId	string	ID сегмента списка контактов. Path-параметр.

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

curl -X GET 'https://api.devino.online/address-book-api/segments/3775660349864609792' \
-H "Authorization:Key dfb35a79-81eb-4b73-bc38-4089770a484d"  

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

Параметр	Тип данных	Описание
segmentId	string	ID сегмента.
companyId	integer	ID компании, к которой принадлежит пользователь.
contactGroupId	string	ID списка контактов, к которому принадлежит сегмент.
name	string	Название сегмента.
creationDate	string	Дата и время создания сегмента.
lastUpdate	string	Дата и время последнего обновления сегмента.
query	array[object]	Параметры фильтров контактов для сегмента.
contactsCount	string	Количество контактов в сегменте.

Query

Параметр	Тип данных	Описание
filterOperator	string	Оператор фильтров. Доступны значения: ○ AND - и. ○ OR - или. ○ EXCLUDE - исключить.
filterElements	array[object]	Данные фильтров. Внутри массива может быть не более двух объектов.
name	string	Название атрибута контакта для отбора контактов.
operator	string	Оператор фильтра контактов.
value	string	Значение атрибута контакта для отбора контактов.

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

Примечание

Параметр "filterOperator": "AND" в данном случае нужен лишь для валидации запроса, в самом сегменте он не используется. Данный параметр используется только если фильтров в сегменте больше одного.

{
  "result": {
    "segmentId": "3783239562062773120",
    "companyId": 508833221,
    "contactGroupId": "3707311347799370752",
    "name": "segment",
    "creationDate": "2023-12-05 07:10:25",
    "lastUpdate": "2023-12-05 08:47:43",
    "query": [
      {
        "filterOperator": "AND",
        "filterElements": [
          {
            "name": "name",
            "operator": "sw",
            "value": "John"
          }
        ]
      }
    ],
    "contactsCount": "15640"
  }
}

Удаление сегмента

Для удаления сегмента списка контактов необходимо вызвать DELETE /address-book-api/segments/{segmentId}, передавая параметры сегмента и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
segmentId	string	ID сегмента, который необходимо удалить.

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

curl -i -X DELETE 'https://api.devino.online/address-book-api/segments/425874582738752834' \
-H "Authorization:Key QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

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

При успешном результате возвращается HTTP-статус 200 и переменная result со значением null.

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

{
  "result":null
}

Операторы сегментов

Оператор	Расшифровка	Описание
ex	EXISTS	Наличие данных
eq	EQUALS	Равно
neq	NOT_EQUALS	Не равно
inc	CONTAINS	Содержит
ninc	NOT_CONTAINS	Не содержит
sw	STARTS_WITH	Начинается с
nsw	NOT_STARTS_WITH	Не начинается с
ew	ENDS_WITH	Заканчивается на
new	NOT_ENDS_WITH	Не заканчивается на

Contact

Объект contact содержит персональные данные пользователя. Атрибуты контакта используются как переменные (макросы) в текстах транзакционных сообщений.

Базовые атрибуты контакта

Параметр	Описание
name	Имя.
surname	Фамилия.
phone	Номер телефона.
email	Email.
gender	Пол с возможными значениями male и female.
country	Страна.
city	Город.
birthdate	Дата рождения.
creationDate	Дата создания контакта.
lastUpdate	Дата последнего изменения контакта.
timezone	Часовой пояс контакта.
pushInfo	Данные, необходимые для получения push-уведомлений.

Совет

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