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

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

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

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

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

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

Параметр Тип данных Описание
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-уведомлений.

Совет

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