(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.)
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.
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
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.
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