Документація API для SMS-розсилок Selzy

Selzy API — це спеціальний інтерфейс для вбудовування можливостей розсилок на інший веб-сервіс або десктоп-додаток.

Наш API для SMS-розсилок дозволяє керувати списками контактів, створювати та надсилати SMS-повідомлення, аналізувати статистику. Крім того, є методи партнерів.

Користуватися API можна безкоштовно на будь-якому обліковому записі сервісу. Щоб отримати доступ до API для SMS-розсилок, потрібен ключ, який можна знайти в особистому кабінеті.

Не передавайте ключ доступу іншим людям і не робіть видимим у коді веб-сторінок. Інакше шахраї зможуть відправити будь-яку SMS-розсилку від імені Вашої компанії.

Принцип використання API

Виклик методу

Звернення до методів API для SMS-розсилок — це HTTPS-запит до URL виду:

https://api.selzy.com/LANG/api/METHOD?format=json&api_key=KEY&arg1=ARG_1&argN=ARG_N

де:

LANG *	мова повідомлень сервера API (наразі підтримується en, ua, ru)
METHOD *	назва методу
ключ доступу до API	ключ доступа к API
ARG_1 ... ARG_N	аргументи методу (свої для кожного методу)

Усі параметри запиту мають бути в кодуванні UTF-8. Параметри в прикладі зазначено в GET-запиті. Також можна передавати їх у POST-запиті. Параметр api_key рекомендується передавати лише через POST. Тоді він не зберігатиметься в логах проксі-серверів.

Відповідь на запит надходить у вигляді об'єкта формату JSON. Якщо Ви хочете стиснути запит або відповідь, скористайтеся алгоритмами gzip або bzip2.

Результат успішного виклику методу

Якщо виклик успішний, об'єкт міститиме поле "result", вміст якого залежить від викликаного методу. При цьому відповідь не міститиме поля "error".

Також у разі успішного виклику допустима наявність поля “warnings”. Воно містить масив об'єктів-попереджень із єдиним рядковим полем "warning".

Приклад відповіді успішного виклику методу:

{
    "result": {
        "message_id":34423432
    },
    "warnings": [
        {"warning":"probably not a mobile phone"}
    ]
}

Результат неуспішного виклику методу

Якщо під час виконання методу виникла помилка, у відповіді Ви побачите поле "error" із HTML-повідомленням про помилку та поле "code", в якому зазначається код помилки.

Приклад відповіді з помилкою:

{
    "code": "invalid_arg",
    "error": "fields: This value \"mymail@@@@gmail.com\" is not a valid email address.",
    "result": ""
}

Основні коди помилок під час роботи з API

Список доступних методів для створення та надсилання SMS

Робота зі списками контактів
Створення та надсилання повідомлень
Отримання статистики
Робота з додатковими полями та мітками
Методи для партнерських сайтів

Робота зі списками контактів:

getLists — отримати списки для розсилок із їх кодами;
createList — створити новий список розсилки;
updateList — змінити властивості списку розсилки;
deleteList — видалити список розсилки;
subscribe — підписати адресата на один або кілька списків розсилки;
exclude — виключити адресата зі списків розсилки;
unsubscribe — відписати адресата від розсилки;
importContacts — масовий імпорт і синхронізація контактів;
exportContacts — експорт даних контактів;
getTotalContactsCount — отримати інформацію про розмір бази користувача;
getContactCount — отримати кількість контактів у списку;
getContact — отримати інформацію про один контакт.

Створення та надсилання повідомлень:

createSmsMessage — створити SMS для масового надсилання;
createCampaign — запланувати надсилання SMS повідомлення;
cancelCampaign — скасувати заплановане раніше масове надсилання;
sendSms — надіслати SMS-повідомлення;
checkSms — перевірити статус доставки SMS;
deleteMessage — видалити повідомлення.

Отримання статистики:

getCampaignDeliveryStats — отримати звіт про статус доставки повідомлень для зазначеної розсилки SMS;
getCampaignCommonStats — отримати загальні відомості про результати доставки для зазначеної SMS-розсилки;
getVisitedLinks — отримати статистику переходів за посиланнями;
getCampaigns — отримати список розсилок;
getCampaignStatus — отримати статус розсилки SMS;
getMessages — отримати список повідомлень;
getMessage — отримати інформацію про SMS-повідомлення;
listMessages — отримати список повідомлень без тіла та вкладень.

Робота з додатковими полями та мітками:

getFields — отримати список полів користувача;
createField — створити нове поле;
updateField — змінити параметри поля;
deleteField — видалити поле;
getTags — отримати список користувацьких міток;
deleteTag — видалити мітку.

Методи для партнерських сайтів:

validateSender — підтвердити зворотну адресу;
register — зареєструвати користувача (для партнерських сайтів);
checkUserExists — перевірити існування користувача за логіном або email;
getUserInfo — отримати інформацію про користувача (для партнерських сайтів);
getUsers — отримати інформацію про користувачів (для партнерських сайтів);
transferMoney — переказати гроші на рахунок користувача (для партнерських сайтів);
getAvailableTariffs — отримати список тарифів (для партнерських сайтів);
changeTariff — переключити тариф користувачеві (для партнерських сайтів);
setSenderDomain — отримати DKIM-ключ для домену відправника.

Порядок виклику методів SMS-розсилки

У Вас може бути один або кілька списків контактів. Перш ніж розсилати SMS за списком, дізнайтесь код списку в сервісі методом getLists або створіть новий список за допомогою createList.

Додайте контакти до списку за допомогою методу importContacts (масове додавання контактів) або subscribe (додавання контактів по одному).

Тепер можна надсилати повідомлення. Розсилка створюється за допомогою методу createSmsMessage. Не забудьте зазначити ID списку з телефонами. Тоді повідомлення буде надіслано всім підписникам із цього списку, які були активні на момент виклику createSmsMessage.

Залишилось надіслати SMS-розсилку. Для надсилання SMS використовуйте метод createCampaign. Зазначте message_id, який Ви отримали після надсилання методу createSmsMessage. Ви можете надіслати розсилку відразу або запланувати на будь-який час.

Якщо хочете надіслати ще одне повідомлення за тим самим списком, то знову викличте createSmsMessage і далі дотримуйтесь поданих інструкцій.

Ланцюжок createSmsMessage -> createCampaign надсилає масову SMS-розсилку за списком. Також можна надсилати одиничні SMS методом sendSms і перевіряти статус доставки за допомогою checkSms.

Після розсилки використовуйте метод getCampaignDeliveryStats, щоб отримати результати надсилання SMS.

Швидкий старт

Якщо Ви хочете швидко додати можливість надсилання SMS до Вашого проєкту, скористайтеся нашою бібліотекою для класу PHP.

Також для налаштування API використовуйте базову інструкцію щодо створення інтеграції.