Специфікація

SENDLY SMS API

Специфікація v1.2

SENDLY SMS API працює за принципом передавання повідомлень за допомогою протоколу HTTP. Для обробки SMS-повідомлень доступні два взаємовиключні режими: SMS API та 3CX API

1. SMS API

1.1 Надсилання повідомлення

Це стандартний режим роботи API, призначений для використання з застосунками, що підтримують REST API. Для надсилання SMS доступний такий ендпоінт:

POST https://api.sendly.link/api/sms

Авторизація: Bearer token
Очікуваний тип вмісту: application/json

Поля тіла запиту:

Поле	Тип даних	Опис
`from`	Числовий рядок, мінімум 9 знаків, максимум 11 знаків (необов’язкове поле)	Віртуальний мобільний номер у SENDLY
`to`	Числовий рядок, мінімум 9 знаків, максимум 11 знаків	Цільовий мобільний номер
`body`	Рядок, мінімум 1 знак	Текст повідомлення

Приклад запиту:

curl -X POST https://api.sendly.link/api/sms \
     -H "Authorization: Bearer TWOJ_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "from": "48732129000",
           "to": "48732129001",
           "body": "Test SENDLY"
         }'

Токен можна згенерувати та завантажити в клієнтській панелі. Крім того, токен можна отримати через службу підтримки.

Можливі відповіді:

200 – повідомлення прийнято до надсилання

Тіло відповіді:

Поле	Тип даних	Опис
`message_id`	Рядок	Унікальний ідентифікатор повідомлення (16 hex-знаків)

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

{"message_id":"a906cff7719bd889"}

Можливі відповіді з помилкою:

403 – проблема з авторизацією
422 – проблема з валідацією даних
429 – Перевищено ліміт запитів

У разі помилок тіло відповіді може містити одне або декілька полів, описаних у таблиці нижче:

Поле	Тип даних	Опис
`errors.token`	Масив рядків	Опис помилки, пов’язаної з переданим токеном доступу
`errors.from`	Масив рядків	Опис помилки, пов’язаної з номером джерела
`errors.to`	Масив рядків	Опис помилки, пов’язаної з цільовим номером
`errors.body`	Масив рядків	Опис помилки, пов’язаної з тілом повідомлення

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

{"errors":{"token":["Invalid token"]}}

Вихідні повідомлення кодуються в UCS-2 і поділяються кожні 60 знаків. Опційно можливе надсилання SMS у кодуванні GSM7 з обмеженням до одного повідомлення максимальною довжиною 160 знаків. Цю опцію можна ввімкнути в клієнтській панелі або за запитом до служби підтримки.

1.2 Надсилання повідомлення на кілька номерів

Це метод API, що дозволяє надсилати те саме повідомлення на кілька номерів. Активація цієї функції для токена доступу відбувається виключно через звернення до служби підтримки. Доступний такий ендпоінт:

POST https://api.sendly.link/api/sms-multi

Авторизація: Bearer token
Очікуваний тип вмісту: application/json

Поля тіла запиту:

Поле	Тип даних	Опис
`from`	Числовий рядок, мінімум 9 знаків, максимум 11 знаків (необов’язкове поле)	Віртуальний мобільний номер у SENDLY
`to`	Масив числових рядків, мінімум 9 знаків, максимум 11 знаків, мінімум 1 елемент, максимум 100 елементів	Цільові мобільні номери
`body`	Рядок, мінімум 1 знак	Текст повідомлення

Приклад запиту:

curl -X POST https://api.sendly.link/api/sms-multi \
     -H "Authorization: Bearer TWOJ_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "from": "48732129000",
           "to": ["48732129001", "48732129002"],
           "body": "Test SENDLY"
         }'

Валідація надісланих номерів телефонів відбувається за принципом «все або нічого» – кожен із надісланих номерів має бути коректним польським мобільним номером, інакше весь запит буде відхилено. Надіслані номери мають бути унікальними; надсилання дубльованих номерів призведе до відхилення всього запиту.

Можливі відповіді:

200 – повідомлення прийнято до надсилання

Тіло відповіді:

Поле	Тип даних	Опис
`message_ids`	Масив об’єктів	Кожен повернений об’єкт містить поле „number”, що вказує на один із наданих цільових номерів, та „message_id”, що є ідентифікатором повідомлення, прийнятого до надсилання

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

{"message_ids":[{"number":"48732129001","message_id":"a906cff7719bd889"}]}

Можливі відповіді з помилкою:

403 – проблема з авторизацією
422 – проблема з валідацією даних
429 – Перевищено ліміт запитів

У разі помилок тіло відповіді може містити одне або декілька полів, описаних у таблиці нижче:

Поле	Тип даних	Опис
`errors.token`	Масив рядків	Опис помилки, пов’язаної з переданим токеном доступу
`errors.from`	Масив рядків	Опис помилки, пов’язаної з номером джерела
`errors.to`	Масив рядків	Опис помилки, пов’язаної з цільовим номером
`errors.body`	Масив рядків	Опис помилки, пов’язаної з тілом повідомлення

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

{"errors":{"token":["Invalid token"]}}

1.3 Отримання повідомлень

Вхідні повідомлення надсилаються на вказаний у клієнтській панелі вебхук. Вебхук також можна вказати у зверненні до служби підтримки. Буде здійснено одну спробу доставки повідомлення. Запит API не переходить за редиректами й не авторизується до вебхука. Запит надходитиме з поточної IP-адреси домену api.sendly.link.

Метод: POST
Тип вмісту: application/json

Поля тіла запиту:

Поле	Тип даних	Опис
`type`	Рядок	Тип повідомлення. Для вхідного повідомлення набуває значення „MESSAGE”
`from`	Рядок	Презентація номера джерела. Для повідомлення з підписаним номером у цьому полі міститься підпис (nadpis).
`to`	Числовий рядок	Цільовий номер телефону
`body`	Рядок	Текст повідомлення

Приклад тіла запиту:

{"type":"MESSAGE","from":"48732129000","to":"48732129001","body":"Test sms"}

1.4 Підтвердження доставки повідомлення

Якщо ви бажаєте отримувати сповіщення про доставку повідомлень, потрібно активувати цю опцію в клієнтській панелі або через звернення до служби підтримки. Активація цієї опції спричинить надсилання запиту на вказану адресу вебхука. Буде здійснено одну спробу доставки сповіщення. Запит API не переходить за редиректами й не авторизується до вебхука. Запит надходитиме з поточної IP-адреси домену api.sendly.link.

Метод: POST
Тип вмісту: application/json

Поля тіла запиту:

Поле	Тип даних	Опис
`type`	Рядок	Тип повідомлення. Для повідомлення про статус набуває значення „NOTIFICATION”
`message_id`	Рядок	Ідентифікатор повідомлення, повернений після прийняття до надсилання
`status`	Рядок	DELIVERED для сповіщення про доставку. ERROR для сповіщення про помилку.

Приклад тіла запиту:

{"type":"NOTIFICATION","message_id":"a906cff7719bd889","status":"DELIVERED"}

2. 3CX SMS API

Ця версія API підтримує надсилання та отримання повідомлень на основі актуальної специфікації АТС 3CX Phone System. Щоб активувати це api, у клієнтській панелі потрібно вибрати обидві опції: SMS API та 3CX SMS API.

Для обробки вихідного трафіку необхідно вказати в розділі SMS у 3CX токен, який можна згенерувати в клієнтській панелі, а також адресу url:

https://api.sendly.link/api/tcx

Щоб обробляти вхідні повідомлення, у клієнтській панелі вкажіть вебхук, доступний у вашій АТС 3CX.

Активацію також може виконати служба підтримки; у такому разі ви вказуєте вебхук, а у відповідь надсилається токен.