Опис протоколу IP2SMS
Цей документ містить опис протоколу взаємодії програмного забезпечення компаній-партнерів з IP2SMS-платформою в межах проєкту IP2SMS [завантажити Опис протоколу IP2SMS
]. Протокол надає програмному забезпеченню партнерів такі можливості:
- надсилання коротких повідомлень (SMS) мобільним абонентам
- отримання інформації про статус надісланих повідомлень
Як тіло SMS, що надсилаються, можуть використовуватися як текст, так і двійкові дані в різних форматах (наприклад, EMS, Nokia CLI тощо)
Основними цілями під час розроблення цього протоколу були:
- гнучкість і розширюваність
- простота реалізації
- відсутність потреби в складному програмному забезпеченні на боці партнерів
Виходячи з цих цілей, основою протоколу було обрано обмін XML-повідомленнями через протокол HTTP. Використання мови XML забезпечує потрібну гнучкість і розширюваність. Наявність великої кількості готових засобів генерування й оброблення XML, а також проста структура протоколу роблять реалізацію клієнтської частини не надто складною.
Протокол спирається на стандартну модель "клієнт-сервер", причому клієнтом виступає програмне забезпечення партнера, а сервером - IP2SMS-платформа. У подальших розділах ми для стислості вживатимемо терміни "клієнт" і "сервер" саме в цьому значенні.
Під час надсилання повідомлень клієнт надсилає серверу запит, що містить як власне повідомлення, так і супровідну інформацію. У відповідь сервер ініціює надсилання повідомлення й повертає статус завершення операції. Також сервер повертає унікальний ідентифікатор повідомлення для подальших посилань з боку клієнта. Для з’ясування статусу надісланого повідомлення клієнт надсилає серверу запит, що містить отриманий раніше унікальний ідентифікатор повідомлення. У відповідь сервер повертає клієнту поточний статус повідомлення.
Наступний розділ цього документа містить опис взаємодії клієнта й сервера на нижньому рівні (рівні HTTP). Подальші два розділи докладно описують два основні типи запитів.
Протокол нижнього рівня
Як уже зазначалося раніше, транспортним рівнем для описуваного протоколу було обрано протокол HTTP. Відповідно, на нижньому рівні всі запити клієнта до сервера мають вигляд звичайних HTTP-запитів, що використовують метод POST, у яких тіло запиту є XML-текстом. У результаті виконання запиту IP2SMS-платформа повертає XML-текст, що містить результат. Тип результату, що повертається (Content-Type), завжди text/xml.
Надсилання повідомлень
Щоб надіслати повідомлення, клієнт передає серверу XML-запит такого вигляду:
Надсилання одиночного повідомлення:
<message>
<service id="single" start="час початку" validity="період актуальності" source="вихідний номер"/>
<to>номер одержувача</to>
<body content-type="тип вмісту"
encoding="кодування"
тіло
</body>
</message>
УВАГА: заборонено використовувати режим надсилання одиночних повідомлень «single» для надсилання масових розсилок — для цього необхідно використовувати режими «bulk» або «individual».
Надсилання одного тексту на кілька номерів:
<message>
<service id="bulk" start="час початку" validity="період актуальності" rate="швидкість надсилання" desc="назва розсилки" source="вихідний номер" uniq_key="унікальний ключ розсилки"/>
<to>number1</to>
<to>number2</to>
...
<to>numberN</to>
<body content-type="тип вмісту" encoding="кодування">тіло</body>
</message>
УВАГА: заборонено використовувати режими надсилання масових розсилок «bulk» і «individual» для створення розсилок, що складаються з одного повідомлення, — для цього необхідно використовувати режим «single».
Надсилання індивідуального тексту на кілька номерів:
<message>
<service id="individual" start="час початку" validity="період актуальності" rate="швидкість надсилання" desc="назва розсилки" source="вихідний номер" uniq_key="унікальний ключ розсилки"/>
<to>number1</to>
<body content-type="тип вмісту1" encoding="кодування1">тіло1</body>
<to>number2</to>
<body content-type="тип вмісту2" encoding="кодування2">тіло2</body>
...
<to>numberN</to>
<body content-type="тип вмістуN" encoding="кодуванняN">тілоN</body>
</message>
Тут:
- час початку – час початку розсилки в стандартному форматі. Може задаватися в абсолютному вигляді («Mon, 02 Apr 2007 11:58:24 +0300») або відносно поточного часу («+2 hour», «+1 day», «+3 hour 20 min»). Якщо параметр пропущено - розсилка починається одразу після отримання запиту.
- період актуальності – час актуальності доставки повідомлення в стандартному форматі. Може задаватися в абсолютному вигляді («Mon, 02 Apr 2007 11:58:24 +0300») або відносно часу надсилання повідомлення («+2 hour», «+1 day», «+3 hour 20 min»). Якщо параметр пропущено, значення за замовчуванням дорівнює 2 годинам від моменту надсилання повідомлення абоненту.
- швидкість надсилання – обмеження швидкості надсилання повідомлень абонентам. Задається кількістю повідомлень, що надсилаються за хвилину. Може набувати значень від 1 до 100. Якщо параметр пропущено – розсилка виконується з максимально можливою швидкістю.
- назва розсилки – текстова назва розсилки (необов’язковий параметр). Використовується у web-інтерфейсі.
- вихідний номер – вихідний номер, з якого здійснюється розсилка.
- унікальний ключ розсилки – випадкове число від 0 до 231, що не змінюється під час кількох спроб надсилання однієї розсилки. Слугує для запобігання додаванню однієї розсилки більше одного разу в разі випадкових збоїв зв’язку;
- номер одержувача - номер одержувача – Мобільного абонента. Номер має задаватися в повному міжнародному форматі, що складається зі знака + і дванадцяти цифр. Наприклад: +380671234567
-
тип вмісту - рядок, що задає тип вмісту повідомлення, яке надсилається. Спосіб задання рядка збігається з визначеним стандартом MIME. Наразі можуть використовуватися такі типи вмісту:
- text/plain - текстове повідомлення. У разі використання цього типу атрибут encoding ігнорується. Мається на увазі, що тіло повідомлення містить виключно текст у кодуванні UTF-8.
- кодування - задає кодування тіла повідомлення, якщо тіло повідомлення двійкове. Для текстових повідомлень (тип повідомлення - text/plain) цей параметр можна опустити або встановити рівним plain. Допустимі значення кодування - такі:
- plain - кодування відсутнє. Цей тип допустимий лише для текстових повідомлень в UTF-8
- base64 - тіло повідомлення закодовано як BASE64 (див. стандарт MIME)
У результаті оброблення запиту сервер повертає клієнту результат такого вигляду:
У разі service id="single":
<status id="ід повідомлення" date="дата і час">
<state
error="повідомлення про помилку">
статус
</state>
</status>
У разі service id="bulk" або "individual":
<status groupid='ід групи повідомлень' date='дата і час'>
<id>ід повідомлення1</id><state error="повідомлення про помилку">статус1</state>
<id>ід повідомлення2</id><state error="повідомлення про помилку">статус2</state>
...
<id>ід повідомленняN</id><state error="повідомлення про помилку">статусN</state>
</status>
Тут:
- ід групи повідомлень - унікальний ідентифікатор групи повідомлень. Може використовуватися клієнтом для подальших запитів сумарної статистики для цієї групи повідомлень.
- ід повідомлення - унікальний ідентифікатор повідомлення. Може використовуватися клієнтом для подальших запитів статусу повідомлення. Цей атрибут може бути відсутнім, якщо повідомлення не може бути доставлено (помилка XML, помилка формату, неправильна IP-адреса, неіснуючий ідентифікатор послуги тощо)
- дата і час - дата і час, для яких зазначається статус. Слід особливо зазначити, що дата і час, установлені на IP2SMS-платформі, можуть відрізнятися від установлених на комп’ютері клієнта
- повідомлення про помилку - повідомлення про помилку, якщо вона сталася. Повідомлення є текстовими рядками й призначені для аналізу людиною, а не програмою. Якщо безсумнівної помилки немає, цей атрибут пропускається
-
статус - власне статус повідомлення. Перелік можливих статусів може розширюватися. Наразі це:
- Accepted - повідомлення прийнято IP2SMS-платформою, але спроби доставки ще не було
- Enroute - здійснюються спроби доставити повідомлення, проте воно ще не доставлено
- Delivered - повідомлення доставлено одержувачеві
- Expired - вичерпано ліміт часу на спроби доставити повідомлення; подальших спроб не буде
- Deleted - повідомлення примусово видалено із системи адміністратором
- Undeliverable - повідомлення з тих чи інших причин не може бути доставлено одержувачеві (наприклад, спроба доставити на неіснуючий телефонний номер)
- Rejected - повідомлення відхилено через помилки в ньому (порушення формату, спроба надіслати повідомлення за межі українських операторів тощо)
- Unknown - стан повідомлення невідомий.
Якщо статус відрізняється від Accepted, Enroute і Delivered, атрибут error тегу state може містити уточнювальну інформацію про помилку
Приклад надсилання повідомлення
Нижче наведено приклади запиту на надсилання повідомлення та відповіді IP2SMS-платформи. Запит:
<message>
<service id="single"/>
<to>+380671234567</to>
<body content-type="text/plain">
This is a sample message
</body>
</message>
Відповідь:
<status id="3806712345671174984921384" date="Wed, 28 Mar 2007 12:35:00 +0300">
<state>Accepted</state>
</status>
Отримання інформації про статус повідомлення
Щоб отримати інформацію про статус повідомлення, клієнт має надіслати серверу запит такого вигляду:
<request id="ід повідомлення">status<request>
де ід повідомлення - ідентифікатор повідомлення, отриманий у результаті надсилання (див. вище)
У відповідь сервер надсилає клієнту інформацію про статус повідомлення в описаному вище вигляді. Єдина відмінність - можливість появи статусу not found, який означає, що повідомлення із зазначеним ідентифікатором не знайдено.
Приклад запиту статусу
Нижче наведено приклад запиту статусу повідомлення та відповіді IP2SMS-платформи.
Запит:
<request id="3806712345671174984921384">status</request>
Відповідь:
<status id="3806712345671174984921384" date="Wed, 28 Mar 2007 12:35:00 +0300">
<state>Delivered</state>
</status>
Отримання сумарної інформації про групу повідомлень
Щоб отримати сумарну інформацію про групу повідомлень, клієнт має надіслати серверу запит такого вигляду:
<request groupid="ід групи повідомлень">status<request>
де ід групи повідомлень - ідентифікатор групи повідомлень, отриманий у результаті надсилання (див. вище).
У результаті сервер дає відповідь у такій формі:
<status groupid="ід групи повідомлень" date="дата" desc="назва розсилки" state="стан розсилки" reports="стан приймання звітів">
<total>кількість</total>
<queued>кількість</queued>
<accepted>кількість</accepted>
<enroute>кількість</enroute>
<delivered>кількість</delivered>
<expired>кількість</expired>
<undeliverable>кількість</undeliverable>
<unknown>кількість</unknown>
</status>
Деякі теги можуть бути відсутні, якщо відповідна кількість дорівнює нулю.
Поле «стан розсилки» містить інформацію про поточний стан розсилки й може набувати таких значень:
- waiting – розсилка ще не почалася;
- sending – розсилка триває;
- sent – розсилку завершено;
- paused – розсилку призупинено;
- canceled – розсилку частково скасовано.
Поле «стан приймання звітів» містить інформацію про поточний стан приймання звітів про доставку повідомлень від операторів. Воно з’являється лише тоді, коли надсилання повідомлень завершено (state="sent"), і може набувати таких значень:
- waiting – період актуальності повідомлень ще не минув, система очікує звіти про доставку повідомлень;
- completed – приймання звітів про доставку завершено.
Керування розсилками
Розсилку, що перебуває в системі, користувач може призупинити, продовжити або скасувати. Для керування розсилкою користувач має надіслати команду такого вигляду:
<request groupid="ід групи повідомлень">команда</request>
У відповідь система видасть звіт:
<status groupid="ід групи повідомлень" date="дата" state="стан"> </status>
якщо операція пройшла успішно, або:
<status groupid="ід групи повідомлень" date="дата" error="опис помилки"></status>
якщо команду виконати не вдалося.
команда – може набувати значень pause, resume або cancel;
стан може бути paused, resumed, canceled або deleted.
У разі команди cancel система аналізує стан розсилки і, якщо розсилка ще не почалася, – вона повністю видаляється із системи (deleted), інакше видаляється частина розсилки, яку ще не було надіслано абонентам (canceled). Команду cancel можна подавати лише для розсилок, що перебувають у стані waiting або paused.
Автоматичне надсилання звітів про стан повідомлень
Для роботи в цьому режимі клієнт надає url власної системи, на який надсилатиметься звіт після встановлення остаточного стану надісланого повідомлення. Вигляд звіту:
<status id="3806712345671174984921384" date="Wed, 28 Mar 2007 12:35:00 +0300">
<state error="текст помилки">стан</state>
</status>
Де “стан” може набувати значень “undeliverable”, “expired”, “unknown” “delivered”. Поле “текст помилки” може містити уточнювальну інформацію в разі встановлення стану “undeliverable”.
Система клієнта має надати підтвердження в такій формі:
<status>accepted</status>
Приклад реалізації на php:
<?php
$from="TEST_NUMBER";
$to="380987654321";
$start="14:00";
$text="Тестове повідомлення";
$xml="<message><service id='single' validity='+2 hour' source='$from'
start='$start'/><to>$to</to><body content-type='plain/text'
encoding='plain'>$text</body></message>";
$answ=post_request($xml, ' http://bulk.startmobile.com.ua/clients.php ', 'super-login', 'mega-password');
function post_request($data, $url, $login, $pwd)
{
$credent = sprintf('Authorization: Basic %s',base64_encode($login.":".$pwd) );
$params=array('http'=>array('method'=>'POST','content'=>$data, 'header'=>$credent));
$ctx = stream_context_create($params);
$fp=@fopen($url, 'rb', FALSE, $ctx);
if ($fp)
{
$response = @stream_get_contents($fp);
}else
{
$response = false;
}
return $response;
}
?>
Параметри авторизації:
Логін і пароль ті самі, що й для доступу до web-інтерфейсу системи.