Адресная книга¶
Создание списка контактов¶
Для создания списка контактов необходимо вызвать POST /address-book-api/contact-groups, передавая параметры списка в теле запроса и данные авторизации в заголовке.
Параметры запроса¶
Параметр | Тип данных | Описание |
---|---|---|
fields (optional) |
array[Fields] | Параметры пользовательских макросов (полей) контактов в списке, в дополнение к основным полям контакта. |
name | string | Название списка контактов. |
type (optional) |
string | Тип списка контактов. Возможные значения: |
autoDeleteEnabled (optional) |
boolean | Автоматическое удаление контактов, если: ○ контакт не использовался больше двух недель. ○ у контакта отсутствовали какие-либо данные (телефон, email и т.д.). |
Fields¶
Параметр | Тип данных | Описание |
---|---|---|
name | string | Название поля. |
displayName (optional) |
string | Название поля, которое будет отображаться в личном кабинете. |
type (optional) |
string | Тип поля. Возможные значения: |
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 | Проверка на дублирование данных контакта. Возможные значения: |
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 | Тип поля. Возможные значения: |
value | array[string] | Значение поля. |
PushInfo¶
Параметр | Тип данных | Описание |
---|---|---|
appId | string | ID приложения. |
os | integer | Операционная система. Возможные значения: |
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. |
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] | Тип списка контактов. Возможные значения: |
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 | Тип поля. Возможные значения: |
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 | Порядок сортировки. Возможные значения: |
limit (optional) |
integer | Количество выводимых в ответе строк. |
offset (optional) |
integer | Номер строки, с которой будет выводиться результат (смещение). |
pushToken (optional) |
string | Токен устройства. |
queryName (optional) |
string | Поле запроса для фильтра. |
queryOperator (optional) |
string | Оператор запроса для фильтра. Возможные значения: |
queryValue (optional) |
string | Значение запроса для фильтра. |
segmentId (optional) |
string | ID сегмента. |
sortByField (optional) |
string | Поле, по которому будет проходить сортировка. |
zoneOffset (optional) |
integer | Смещение времени для контакта от UTC+0 в минутах. |
subscriptionChannel (optional) |
string | Канал подписки. Возможные значения: |
subscriptionState (optional) |
string | Тип подписки. Возможные значения: |
Пример запроса¶
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] | Параметры макросов (полей) контактов в списке, в том числе и основных полей контакта. |
string | Email контакта. | |
phone | string | Номер телефона контакта. |
unsubscribedData | array[UnsubscribedData] | Данные об отписке контакта. |
pushInfo | array[PushInfo] | Данные, необходимые для получения push-уведомлений. |
Fields¶
Параметр | Тип данных | Описание |
---|---|---|
name | string | Название поля. |
displayName | string | Название поля в личном кабинете. |
type | string | Тип поля. Возможные значения: |
value | array[string] | Значение поля. |
values | array[string] | Массив возможных значений поля, если они предусмотрены. Например: ["gender.male", "gender.female"] . |
isDefault | boolean | Отображается ли поле по умолчанию. |
UnsubscribedData¶
Параметр | Тип данных | Описание |
---|---|---|
channelList | array[UnsubscribedChannel] | Данные каналов отписки. |
companyId | integer | ID компании. |
data | string | Данные отписки (номер телефона, email или токен устройства). |
dataType | string | Тип данных отписки. Возможные значения: |
updatedAt | string | Дата последнего изменения отписки. |
UnsubscribedChannel¶
Параметр | Тип данных | Описание |
---|---|---|
channel | string | Канал отписки. Возможные значения: |
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. |
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. | |
gender | Пол с возможными значениями gender.male и gender.female . |
country | Страна. |
city | Город. |
birthdate | Дата рождения. |
creationDate | Дата создания контакта. |
lastUpdate | Дата последнего изменения контакта. |
timezone | Таймзона, в которой находится контакт. |
pushInfo | Данные, необходимые для получения push-уведомлений. |
Совет
Можно использовать не только базовые, но и пользовательские атрибуты. Их можно задать в личном кабинете или при создании списка контактов.