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

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

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

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 списков контактов и данные авторизации в заголовке.

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

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

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

curl -X DELETE https://api.devino.online/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"
    }
  ]
}

Contact¶

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

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

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

Совет

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