If you are working on telephone solutions, please check
out the Ozeki VoIP SIP SDK.
It can be used to create VoIP client and server software. |
|
HTTP SMS API - receivemessage method
(available in version: Ozeki
NG SMS Gateway v3.0.1 or newer)
This method can be used to receive an SMS message via the SMS Gateway using
HTTP polling. HTTP polling means that you download SMS messages from the inbox
folder of the gateway like you would download a webpage. In this section you
can get information about how you can use the receiveimessage method, what
are the parameters, and you will be presented with an example HTTP request to
download
incoming messages. (Please note, that there is another option if you wish
to receive SMS messages. The SMS gateway has a built in HTTP client, that
can be configured to initiate an HTTP request to your webserver to pass an
incoming message as soon as it arrives. More information about this option
can be found in the HTTP SMS API - HTTP
Client guide.)
Example URL Request
http://127.0.0.1:9501/api?action=receivemessage&username=admin&password=abc123&
folder=inbox&limit=2&afterdownload=delete
Example Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 824
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE response PUBLIC "-//OZEKI//DTD XML 1.0//EN" "http://www.ozekisms.com/DTD/response.xml">
<response>
<action>receivemessage</action>
<data>
<message>
<messageid>ERFAV23D</messageid>
<originator>06301234567</originator>
<recipient>06201112222</recipient>
<messagetype>SMS:TEXT</messagetype>
<messagedata>Hello world</messagedata>
<senttime>2008-01-16 10:04:00</senttime>
<receivedtime>2008-01-18 20:58:04</receivedtime>
</message>
<message>
<messageid>GYT4455D</messageid>
<originator>06209994444</originator>
<recipient>06201112222</recipient>
<messagetype>SMS:TEXT</messagetype>
<messagedata>Second message</messagedata>
<senttime>2008-01-16 10:08:00</senttime>
<receivedtime>2008-01-18 20:58:05</receivedtime>
</message>
</data>
</response>
Description
To download incoming text messages use the following URL format:
http://127.0.0.1:9501/api?action=receivemessage&username=UUUUU&password=PPPPP&
folder=inbox&limit=2&afterdownload=delete
For 127.0.0.1, you should substitute the host name or the IP address of the
computer your SMS gateway is installed on. The port number 9501 is the default
HTTP port number of the Ozeki NG SMS gateway. It is should not be changed.
The username and the password should be substituted for "UUUUU" and "PPPPP". The
username and password identifies the user
you have created in the SMS gateway. When you invoke the receivemessage
action by
calling the URL, you will download messages from the inbox of the user specified
in the query with the username and the password.
The folder parameter of the message should be set to inbox.
The limit parameter specifies the number of messages that will be downloaded. It
is recommended to download less then 1000 messages in a single request. You can
download the remaining messages in subsequent requests.
The afterdownload parameter can be used to remove messages from the SMS gateway
once they have been successfully downloaded.
Request parameters
| Parameter |
Description |
Possible values |
Example |
M/O* |
| action |
Specifies the HTTP API command |
receivemessage |
action=receivemessage |
M |
| username |
Specifies the username.
The username and password parameters are used to
authenticate the user. Once the user is authenticated
messages will be downloaded from his inbox. The value
must be urlencoced.
|
string value, maximum length is 16 characters
|
username=admin |
M |
| password |
Specifies the password.
The username and password parameters are used to
authenticate the user. Once the user is authenticated
messages will be downloaded from his inbox.
The value
must be urlencoced.
|
string value, maximum length is 16 characters
|
password=abc123 |
M |
| folder |
Specifies the name of the folder. By default messages will
be downloaded from the inbox folder. You can use the receivemessage
method to download messages from other folders as well.
|
inbox (default)
outbox
deliveredtonetwork
deliveredtohandset
deliveryfailed
|
folder=inbox |
O |
| limit |
Specifies the maximum number of messages to be downloded from
the server within the request. You can download the remaining messages
with subsequent requests.
|
integer value, the default limit is 1000
|
limit=10 |
O |
| afterdownload |
Specifies the way messages should be handled after a successful
download. Messages can be deleted from the SMS gateway, they can
be marked as downloaded and they can be left untouched. If they
are left untouched, the next time you initiate a download request they
will be downloaded again.
|
delete (default)
mark
untouch
|
afterdownload=delete |
O |
| responseformat |
You can specify the format of the user's incoming messages.
|
xml, html, plain, urlencoded
|
responseformat=rss |
O |
* M = Mandatory parameter, O = Optional parameter
Response parameters
(xml response format)
| Parameter |
Description |
Possible values |
Example |
| message |
Contains a single message. The data section can contain many messages.
The number of messages in the message data can is less then or equal to
the value of the limit parameter
|
|
<message>
<messageid>ERFAV23D</messageid>
<originator>06301234567</originator>
<recipient>06201112222</recipient>
<messagetype>SMS:TEXT</messagetype>
<messagedata>Hello world</messagedata>
<senttime>2008-01-16 10:04:00</senttime>
<receivedtime>2008-01-18 20:58:04</receivedtime>
</message> |
| message.messageid |
Contains a message reference that can be used to track the
message in the SMS gateway. This message reference is also used
to identify delivered to network and delivered to handset reports or
to query information about the message.
|
string value, maximum length is 16 characters |
<messageid>ERFAV23D</messageid>
|
| message.originator |
Contains the sender telephone number. This is the telephone number of
the cellphone the sent the message.
|
string value, maximum length is 16 characters |
<recipient>06301234567</recipient>
|
| message.recipient |
Contains the recipient address. This is the telephone number that
was used to send the message to.
|
string value, maximum length is 16 characters |
<recipient>06201112222</recipient>
|
| message.messagetype |
Contains the message type identifier specified in the
Mobile Message Type Specification.
In most cases this will be SMS:TEXT.
|
string value, maximum length is 1024 characters |
<recipient>SMS:TEXT</recipient>
|
| message.messagedata |
Contains the message data. For text messages this is the text of the
SMS messages. For other message types this is an XML structure specified in
the
Mobile Message Type Specification.
The messagedata is encoded as UTF8.
|
string value |
<messagedata>Hello world</messagedata>
|
| message.senttime |
Contains the timestamp that tells when the message was submitted
from the sender phone.
|
Date time value in the following format: YYYY-MM-DD hh:mm:ss |
<senttime>2008-01-16 10:04:00</senttime>
|
| message.receivedtime |
Contains the timestamp that tells when the message was received
by the SMS gateway.
|
Date time value in the following format: YYYY-MM-DD hh:mm:ss |
<senttime>2008-01-18 20:58:04</senttime>
|
Next page:
Billing methods
|
