Перейти к содержанию

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

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

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

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

Для создания списка контактов необходимо вызвать 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 Описание ошибки.

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

{
  "result": "3576515602081985000"
}
{
  "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 Описание ошибки.

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

{
  "result": [
    {
      "code": "OK",
      "result": {
        "contactId": "3379c731a0734800-337a7406f274fe80"
      }
    }
  ]
}
{
  "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 для валидации запроса. Однако в самих фильтрах он использоваться не будет. Прочитайте пояснение к примерам запроса для лучшего понимания.

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

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

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

В данном запросе содержатся два фильтра: в сегмент добавятся контакты с номером телефона, начинающимся на 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"
            }
          ]
        }
      ]
    }
  ]
}

В данном запросе содержатся три фильтра: в сегмент добавятся контакты с номером телефона, начинающимся на 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 для валидации запроса. Однако в самих фильтрах он использоваться не будет. Прочитайте пояснение к примерам запроса для лучшего понимания.

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

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

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

В данном запросе содержатся два фильтра: в сегмент добавятся контакты с номером телефона, начинающимся на 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"
            }
          ]
        }
      ]
    }
  ]
}

В данном запросе содержатся три фильтра: в сегмент добавятся контакты с номером телефона, начинающимся на 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-уведомлений.

Совет

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