- Quick start guide
- System requirements
- Installation guide
- User guide
- Developers guide
- SMS from SQL
- C# SMS API
- HTTP SMS API
- HTTP API user
- Get Started
- Send message
- Receive message
- URL encode
- PHP SMS API
- VB.NET SMS API
- Programming APIs
- Service providers
- Administrators guide
HTTP API - 'receivemessage' action
This action can be used to receive SMS messages from 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 action, what are the parameters, and you will be presented with an example HTTP request to download incoming messages.
To download incoming text messages use the following URL format:https://127.0.0.1:9508/api?action=receivemessage&username=UUUUU&password=PPPPP&
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 9508 is the default HTTP port number of the Ozeki SMS gateway. It port number can be configured in the user interface of Ozeki 10 SMS Gateway, by clicking on the Advanced button in the toolbar.
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.
Example URL Request
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>
|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 action to download messages from other folders as well.||
|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.||
|responseformat||You can specify the format of the user's incoming messages.||xml, html, urlencoded||responseformat=xml||O|
* M = Mandatory parameter, O = Optional parameter
(xml response format)
|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>2028-01-16 10:04:00</senttime> <receivedtime>2028-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>2028-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>2028-01-18 20:58:04</senttime>|
In this article, you found all the information necessary to use the ‘receivemessage’ action with our HTTP SMS API.
With this solution, you can utilize the benefits of http polling to receive the incoming text messages. We did our very best to make it simple and to walk you through all the details as painlessly as possible. If you have already completed the steps, you have seen the benefits of using our HTTP SMS API. If you yet to start working on completing your SMS system using API, do not waste any time. Start now!
If you would like to get to know more useful insights about the advantages of other smiliar SMS solutions, please open the page about sending messages with the same system.
I hope this page will be useful to all the readers and especially to beginners.
- Create an HTTP SMS API user account
- Send and receive SMS through the HTTP API
- HTTP SMS API send SMS example
- HTTP SMS API url encoder
- Top 10 SMS API for programmers
- How to send SMS over HTTPS