oneapi-php/QUICKSTART.html at master · nemanjavuk/oneapi-php · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
<html><head><title>OneApi doc</title><meta http-equiv="content-type" content="text/html; charset=UTF-8"></head><body><h3 id="SYSTEM_OVERVIEW">System overview</h3>
<p><a href="https://github.com/infobip/" target="_blank">Parseco</a> is an <a href="http://en.wikipedia.org/wiki/Application_programming_interface" target="_blank">API</a> implementation inspired by <a href="http://oneapi.gsma.com/api-list/" target="_blank">OneApi</a> specification which is issued by the Global System for Mobile Communications Association.
We felt the need to enrich the specification by adding a few fields in some requests and responses to make the API more comfortable for the developer.</p>
<p>Parseco API exposes the following mobile network functionalities:</p>
<ul>
<li><strong>Short message service</strong> (<strong>SMS</strong>) is the most widespread mobile network data application. The term stands for the service as well as the text message itself. We fully support <a href="http://en.wikipedia.org/wiki/Unicode" target="_blank">Unicode</a> <a href="http://en.wikipedia.org/wiki/UTF-16" target="_blank">UTF-16</a> character set so that you can use virtually any alphabet for composing your text. The only limitation for SMS messages is the message length which is 70 characters in case of a Unicode encoded message, or 160 characters in case the message is not Unicode encoded. If you want to send <a href="http://www.parseco.com/multipart-sms-messaging/">longer messages</a> then the appropriate length is 67 per Unicode encoded message part and 153 characters per non Unicode encoded message part.</li>
<li><strong>Unstructured supplementary services data</strong> (<strong>USSD</strong>) is mostly used for prepaid callback service, mobile-money services and menu-based information services. It is a connection-based data protocol which makes it more responsive than the message-based SMS. Connection-based means that a connection (session) is established and kept alive for the entire time during the communication. That is why it is sometimes used for WAP browsing. The length of the USSD message is up to 182 alphanumeric characters in length. Unfortunately, Unicode encoding is not supported.</li>
<li><strong><a href="http://www.infobip.com/services/number_context" target="_blank">Number Context</a></strong> Infobip's Number Context service communicates with a relevant mobile number's home network and can identify whether the subscribers handset is roaming on another network, currently active or has been disabled.
<br><sub><strong>* HLR service has been renamed to Number Context service</strong></sub></li>
</ul>
<p>Other mobile network-related functionalities are due to be implemented.
In order to use Parseco API and gain access to <a href="http://www.infobip.com" target="_blank">Infobip</a> mobile networks aggregator system you must <a href="http://www.parseco.com/sign-up/">register</a> at the Parseco website.
In other words, by using Parseco PHP library you can <a href="http://www.parseco.com/#features-list">send SMS messages</a> to <strong>any</strong> cell phone <a href="http://www.parseco.com/pricing-and-coverage/">around the globe</a>.</p>
<h3 id="PREREQUISITES">Prerequisites</h3>
<ul>
<li>You have <a href="http://php.net/manual/en/install.php" target="_blank">installed a PHP interpreter</a>.</li>
<li>You have downloaded the <a href="https://github.com/infobip/oneapi-php/tree/master/oneapi" target="_blank">Parseco OneAPI PHP library</a></li>
</ul>
<h3 id="GENERAL_ASSUMPTIONS_WHICH_MUST_BE_FULFILLED_FOR_ALL_THE_FOLLOWING_EXAMPLES">General assumptions which must be fulfilled for all the following examples</h3>
<ul>
<li>You must have an active Internet connection.</li>
<li>You have satisfied the prerequisites and <a href="http://www.parseco.com/sign-up/">signed up</a> at Parseco website. After sign-up, SMS message with the verification PIN will be sent to your cell phone.</li>
</ul>
<p><img id="quickstart-img-03" src="http://parseco.com/wp-content/themes/parseco/images/content/quickstart_03.png" title="Account verification" width="660" height="290" /></p>
<p>Input the four-digit PIN from the received SMS message in the verification box and press verify.
Congratulations on your successful registration - you can start using Parseco API! If you want, you can try out the <a href="http://www.parseco.com/demos/">live demos</a> now.</p>
<h3 id="ASSUMPTIONS_WHICH_MUST_BE_FULFILLED_FOR_THE_EXAMPLES_WITH_NOTIFICATION_PUSH">Assumptions which must be fulfilled for the examples with notification push</h3>
<p>In every example two different architectural approaches are shown.
In the first scenario the mobile-originated (see example 3 for term explanation) information is returned to the (web) application that requested the operation.</p>
<p>In the second scenario the mobile-terminated information is still being sent by your (web) application, but the mobile-originated information is returned to an URL predefined by you via HTTP POST request.
In other words, Parseco pushes the receiving inbound notifications (be it Number Context or delivery data, or messages) to your web application.</p>
<ul>
<li>You must have your own web application in order to provide the URL for the Parseco push notifications.</li>
<li>You must register the URL mentioned above as notification URL at Parseco site <a href="http://www.parseco.com/application/setup-wizard/">setup wizard</a></li>
<li>Your inbound messages will be available for a period of 48 h after being received by our gateways.</li>
</ul>
<p>For a given notification URL the <a href="http://www.parseco.com/application/setup-wizard/">setup wizard</a> generates a pair of subscription number and keyword. The just generated subscription will be shown in the list below:</p>
<ul>
<li><strong>Id</strong> - The id of the subscription.</li>
<li><strong>Address</strong> - Your GSM subscription number to which inbound messages are sent. <strong>Prefix it with '+' prior to sending SMS message.</strong></li>
<li><strong>Criteria</strong> - String which <strong>must</strong> be present at the start of the SMS message text, otherwise Parseco won't forward it to your code.</li>
<li><strong>Notify URL</strong> - The registered URL to receive Parseco push notifications</li>
<li><strong>Action</strong> - Action for subscription.</li>
</ul>
<p><img id="quickstart-img-02" src="http://parseco.com/wp-content/themes/parseco/images/content/quickstart_02.png" title="List of subscriptions" width="660" height="320" /></p>
<p>The "Notify URL" field is crucial.
If it is present, then the approach with notification push is chosen, meaning that all your mobile-originated information will be sent to it via HTTP POST request.</p>
<p>If it is not present then the approach without notification push is chosen, meaning that all your mobile-originated information will be returned to the (web) application that requested the operation.
If you make changes, a "Save" button will appear in the "Action" column. If you want to apply the changes, press it.</p>
<h3 id="NOTICE">Notice</h3>
<ul>
<li><strong>After signup you won't be able to use any of our services for 2 to 5 minutes until the system propagates the changes.</strong></li>
<li><strong>Until you make your first payment the only GSM number to which you can send messages is the one tied to your Parseco account. It is meant for demo purposes only, so you have a 5 &euro; budget for testing, which roughly translates to 500 or less SMS messages, <a href="http://www.parseco.com/pricing-and-coverage/">depending upon your location</a>.</strong></li>
<li>All examples are <a href="http://sscce.org/" target="_blank">valid, runnable</a> code snippets,  you can copy them to a new empty PHP file, and replace the PATH_TO_LIBRARY with a string containing the path to the client.php file from downloaded library. There may be other strings to replace, e.g. as in example 1.1. If your operating system supports it, don't forget to set appropriate file permissions. After you have done that, you can run them.</li>
</ul>
<h3 id="EXAMPLE_1_1_BASIC_MESSAGING_HELLO_WORLD">Example 1.1: Basic messaging (Hello world)</h3>
<p>The first thing that needs to be done is to initialize the client with username and password in plaintext.
You are basically logging in to Parseco, so an exception will be thrown if the username and/or password are incorrect. The next step is to prepare the message:</p>
<ul>
<li><strong>sender address</strong> - value which will appear in the FROM field on the destination cell phone</li>
<li><strong>address</strong> - GSM number of the destination cell phone</li>
<li><strong>message</strong> - the contents of the SMS message</li>
</ul>
<p>Sender address may be any string composed of printable characters but will it be delivered as such depends on the settings of the destination <a href="http://en.wikipedia.org/wiki/Mobile_network_operator" target="_blank">network operator</a>.
Therefore, our recommendation (but not a guarantee) is to use the <a href="http://en.wikipedia.org/wiki/English_alphabet" target="_blank">English</a> <a href="http://en.wikipedia.org/wiki/Alphanumeric" target="_blank">alphanumeric</a> character subset.</p>
<p>When you execute the send method it will return an object which is used to query the message delivery status.
These are possible states of the message once you have sent it: </p>
<ul>
<li><strong>DeliveredToTerminal</strong> - the message has been delivered to the cell phone</li>
<li><strong>DeliveredToNetwork</strong> - the message has been delivered to the cell phone network operator</li>
<li><strong>MessageWaiting</strong> - message is pending delivery to the cell phone network operator</li>
<li><strong>DeliveryImpossible</strong> - message will not be delivered</li>
<li><strong>DeliveryUncertain</strong> - delivery cannot be confirmed due to network operator settings. It still may be delivered but we will never know it.</li>
</ul>
<p>Now you are ready to send the message.</p>
<pre><code>&lt;?php

require_once(PATH_TO_LIBRARY);

$smsClient = new SmsClient(USERNAME, PASSWORD);

$smsMessage = new SMSRequest();
$smsMessage-&gt;senderAddress = SENDER_ADDRESS;
$smsMessage-&gt;address = DESTINATION_ADDRESS;
$smsMessage-&gt;message = 'Hello world';

$smsMessageSendResult = $smsClient-&gt;sendSMS($smsMessage);

// The client correlator is a unique identifier of this api call:
$clientCorrelator = $smsMessageSendResult-&gt;clientCorrelator;

// You can use $clientCorrelator or $smsMessageSendResult as an method call argument here:
$smsMessageStatus = $smsClient-&gt;queryDeliveryStatus($smsMessageSendResult);
$deliveryStatus = $smsMessageStatus-&gt;deliveryInfo[0]-&gt;deliveryStatus;

echo 'Success:', $smsMessageStatus-&gt;isSuccess(), "\n";
echo 'Status:', $deliveryStatus, "\n";
if( ! $smsMessageStatus-&gt;isSuccess()) {
    echo 'Message id:', $smsMessageStatus-&gt;exception-&gt;messageId, "\n";
    echo 'Text:', $smsMessageStatus-&gt;exception-&gt;text, "\n";
    echo 'Variables:', $smsMessageStatus-&gt;exception-&gt;variables, "\n";
}

?&gt;
</code></pre>
<h3 id="EXAMPLE_1_2_BASIC_MESSAGING_HELLO_WORLD_WITH_NOTIFICATION_PUSH">Example 1.2: Basic messaging (Hello world) with notification push</h3>
<p>Set the notify URL when sending message:</p>
<pre><code>&lt;?php

require_once(PATH_TO_LIBRARY);

$smsClient = new SmsClient(USERNAME, PASSWORD);

$smsMessage = new SMSRequest();
$smsMessage-&gt;senderAddress = SENDER_ADDRESS;
$smsMessage-&gt;address = DESTINATION_ADDRESS;
$smsMessage-&gt;message = 'Hello world';
$smsMessage-&gt;notifyURL = NOTIFY_URL;

$smsMessageSendResult = $smsClient-&gt;sendSMS($smsMessage);

?&gt;
</code></pre>
<p>Parseco will send a HTTP POST request to this URL, and your web application must process it like this:</p>
<pre><code>&lt;?php

require_once(PATH_TO_LIBRARY);

$result = SmsClient::unserializeDeliveryStatus();

// Process $result here, e.g. just save it to a file:
$f = fopen(FILE_NAME, 'w');
fwrite($f, "\n-------------------------------------\n");
fwrite($f, 'status: ' . $result-&gt;deliveryInfo-&gt;deliveryStatus . "\n") ;
fwrite($f, 'address: ' . $result-&gt;deliveryInfo-&gt;address . "\n");
fwrite($f, 'messageId: ' . $result-&gt;deliveryInfo-&gt;messageId . "\n");
fwrite($f, 'clientCorrelator: '. $result-&gt;deliveryInfo-&gt;clientCorrelator . "\n");
fwrite($f, 'callback data: ' . $result-&gt;callbackData . "\n");
fwrite($f, "\n-------------------------------------\n");
fclose($f);

?&gt;
</code></pre>
<p>Note that there is nothing stopping you from running both code snippets on the same host or within the same web application, but it is not necessary.</p>
<h3 id="EXAMPLE_2_1_CELL_PHONE_ROAMING_STATUS_NUMBER_CONTEXT_QUERY">Example 2.1: Cell phone roaming status (Number Context query)</h3>
<p>When the cell phone is connected to a network other than his home operator network it is said to be <a href="http://en.wikipedia.org/wiki/Roaming" target="_blank">roaming</a>.
This is just a part of the information about a cell phone that can be obtained via a <a href="http://www.infobip.com/messaging/end_users/number_context_packages" target="_blank">Number Context</a> query like in the example below.</p>
<pre><code>&lt;?php

require_once(PATH_TO_LIBRARY);

$client = new DataConnectionProfileClient(USERNAME, PASSWORD);

$response = $client-&gt;retrieveRoamingStatus(DESTINATION_ADDRESS);
echo 'Number context result: \n&lt;br&gt;';
echo 'servingMccMnc: ', $response-&gt;servingMccMnc,'\n&lt;br&gt;';
echo 'address: ', $response-&gt;address,'\n&lt;br&gt;';
echo 'currentRoaming: ', $response-&gt;currentRoaming,'\n&lt;br&gt;';
echo 'resourceURL: ', $response-&gt;resourceURL,'\n&lt;br&gt;';
echo 'retrievalStatus: ', $response-&gt;retrievalStatus,'\n&lt;br&gt;';
echo 'callbackData: ', $response-&gt;callbackData,'\n&lt;br&gt;';
echo 'extendedData: ', $response-&gt;extendedData,'\n&lt;br&gt;';
echo 'IMSI: ', $response-&gt;extendedData-&gt;imsi,'\n&lt;br&gt;';
echo 'destinationAddres: ', $response-&gt;extendedData-&gt;destinationAddress,'\n&lt;br&gt;';
echo 'originalNetworkPrefix: ', $response-&gt;extendedData-&gt;originalNetworkPrefix,'\n&lt;br&gt;';
echo 'portedNetworkPrefix: ', $response-&gt;extendedData-&gt;portedNetworkPrefix,'\n&lt;br&gt;';

?&gt;
</code></pre>
<h3 id="EXAMPLE_2_2_CELL_PHONE_ROAMING_STATUS_NUMBER_CONTEXT_QUERY_AS_NOTIFICATION_PUSH">Example 2.2: Cell phone roaming status (Number Context query) as notification push</h3>
<p>Set the notify URL when sending message:</p>
<pre><code>&lt;?php

require_once(PATH_TO_LIBRARY);

$client = new DataConnectionProfileClient(USERNAME, PASSWORD);

$response = $client-&gt;retrieveRoamingStatus(DESTINATION_ADDRESS, NOTIFY_URL);
// if there is no error the query has been succesfully executed
if(!$response-&gt;isSuccess()) {
    echo 'Error:', $response-&gt;exception, "\n";
    Logs::printLogs();
}

?&gt;
</code></pre>
<p>Parseco will send a HTTP POST request to this URL, and your web application must process it like this:</p>
<pre><code>&lt;?php

require_once(PATH_TO_LIBRARY);

$result = DataConnectionProfileClient::unserializeRoamingStatus();

// Process $result here, e.g. just save it to a file:
$f = fopen(FILE_NAME, 'w');
fwrite($f, "\n-------------------------------------\n");
fwrite($f, 'callbackData: ' . $result-&gt;callbackData . "\n") ;
fwrite($f, 'servingMccMnc: '. $result-&gt;terminalRoamingStatus-&gt;servingMccMnc . "\n") ;
fwrite($f, 'address: '. $result-&gt;terminalRoamingStatus-&gt;address . "\n") ;
fwrite($f, 'currentRoaming: ' . $result-&gt;terminalRoamingStatus-&gt;currentRoaming . "\n") ;
fwrite($f, 'resourceURL: ' . $result-&gt;terminalRoamingStatus-&gt;resourceURL . "\n") ;
fwrite($f, 'retrievalStatus: ' . $result-&gt;terminalRoamingStatus-&gt;retrievalStatus . "\n") ;
fwrite($f, 'terminalRoamingStatus callbackData: ' . $result-&gt;terminalRoamingStatus-&gt;callbackData . "\n") ;
fwrite($f, 'extendedData: ' . $result-&gt;terminalRoamingStatus-&gt;extendedData . "\n") ;
fwrite($f, 'IMSI: ', $response-&gt;extendedData-&gt;imsi,'\n');
fwrite($f, 'destinationAddres: ', $response-&gt;extendedData-&gt;destinationAddress,'\n');
fwrite($f, 'originalNetworkPrefix: ', $response-&gt;extendedData-&gt;originalNetworkPrefix,'\n');
fwrite($f, 'portedNetworkPrefix: ', $response-&gt;extendedData-&gt;portedNetworkPrefix,'\n');
fwrite($f, "\n-------------------------------------\n");
fclose($f);

?&gt;
</code></pre>
<p>Note that there is nothing stopping you from running both code snippets on the same host or within the same web application, but it is not necessary.</p>
<h3 id="EXAMPLE_3_1_PROCESS_INBOUND_MESSAGES_TWO_WAY_COMMUNICATION">Example 3.1: Process inbound messages (two way communication)</h3>
<p>Two way communication with cell phone is also possible via Parseco.
The messages your application sends to cell phones are outbound or mobile-terminated messages.
It is a scenario much like in the first example.
The messages which your application receives from cell phones are inbound or mobile-originated messages.</p>
<p>In order to be able to receive inbound messages programmatically you must have a valid GSM subscription number.
For demo purposes, a valid 30-day trial GSM subscription number is tied to your Parseco account.
Our paid services include (info coming soon, mail to <a href="mailto:info@parseco.com">info@parseco.com</a>):</p>
<ul>
<li>you may register a single subscription number </li>
<li>you may register a single subscription number paired-up with a keyword of your choice</li>
<li>you may register a single subscription number paired-up with multiple keywords oy our choice</li>
<li>you may register for all or some of the above as many times as you like </li>
</ul>
<p>In order for the below example to work make sure that you have a subscription with no notify URL set at your <a href="http://www.parseco.com/application/setup-wizard/">Parseco account</a>.</p>
<pre><code>&lt;?php

require_once(PATH_TO_LIBRARY);

$smsClient = new SmsClient(USERNAME, PASSWORD);

$inboundMessages = $smsClient-&gt;retrieveInboundMessages();

foreach($inboundMessages-&gt;inboundSMSMessage as $message) {
    echo $message-&gt;dateTime;
    echo $message-&gt;destinationAddress;
    echo $message-&gt;messageId;
    echo $message-&gt;message;
    echo $message-&gt;resourceURL;
    echo $message-&gt;senderAddress;
}

?&gt;
</code></pre>
<h3 id="EXAMPLE_3_2_PROCESS_INBOUND_MESSAGES_TWO_WAY_COMMUNICATION_AS_NOTIFICATION_PUSH">Example 3.2: Process inbound messages (two way communication) as notification push</h3>
<p>In order for the below example to work make sure that you have a subscription with a notify URL set at your <a href="http://www.parseco.com/application/setup-wizard/">Parseco account</a>.
Of course, the notify URL must be mapped to your web application.</p>
<pre><code>&lt;?php

require_once(PATH_TO_LIBRARY);

// returns a single message not array of messages
$inboundMessages = SmsClient::unserializeInboundMessages();

// Process $inboundMessages here, e.g. just save it to a file:
$f = fopen(FILE_NAME, 'w');
fwrite($f, "\n-------------------------------------\n");
fwrite($f, 'dateTime: ' . $inboundMessages-&gt;dateTime . "\n");
fwrite($f, 'destinationAddress: '  . $inboundMessages-&gt;destinationAddress . "\n");
fwrite($f, 'messageId: '  . $inboundMessages-&gt;messageId . "\n");
fwrite($f, 'message: '  . $inboundMessages-&gt;message . "\n");
fwrite($f, 'resourceURL: '  . $inboundMessages-&gt;resourceURL . "\n");
fwrite($f, 'senderAddress: '  . $inboundMessages-&gt;senderAddress . "\n");

?&gt;
</code></pre></body></html>