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

Contact

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

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

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

Совет

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

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

Для создания списка контактов необходимо вызвать 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.
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	Канал отписки. Возможные значения: 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"
        }
      ]
    }
  ]
}