|
» SMS Gateway 2.2.4 API Documentation - Denmark
The following document can be used to send SMS (Short Message Service) using the Wannafind.dk SMS Gateway. Sending an SMS
To send an SMS you must submit an HTTP POST request to http://sms.wannafind.dk/api/
The following keys and values can be passed to the above URL. | Parameter | Value | Required? | Default | Default Description | | username | (string) | Yes | | Specify the username to your SMS account | | password | (string)(md5) | Yes | | Specify the password to your SMS account, encrypted as a lowercase md5 sum. | limit
| (integer) | No | 10 | If a message larger than 160 chars is provided, it will be split into two or more messages to accomidate the SMS protocol. The limit specifies how many messages a message may be split into. If the limit is reached, the remaining data is dropped. The user will be charged for each resulting message. A limit of 1 is recommended to avoid unforseen charges. | | recipient | (integer)(8) | Yes | | Specifies the recipient of the SMS. Multiple Recipients can be provided by submitting multiple recipient fields named "recipient[]". Each receiver will receive the messages calculated by the limit parameter. Each recipient number has to be 8 chars, all numeric. When sending the SMS, the server will prepend 0045 to all numbers.
| | message | (string) | Yes | | Specifies the message to be sent. All chars allowed by the SMS protocol are accepted. If the message contains any illegal chars, they are automatically removed, and the message shortened. Multiple spaces are trimmed to only a single space. Trailing spaces are also removed.
| | from | (string)(11-22) | No | 0 | Set the number that the receiver will see as the sender of the SMS. Numeric values have a limit of 22 chars, while alphanumeric values have a limit of 11 chars. Should you desire to use a phonenumber in this string, a recommended syntax is "+4512345678" to avoid problems with some mobile phones not being able to correctly reply to the SMS received.
| | reference | (integer)
| No | | Allows the sender to attach an internal ID to the SMS transmission, this is usefull if you want to match the SMS with a reference in your own system. | | priority | (integer)
| No | 1 | Assigns a priority integer to the SMS transmission. Messages with a priority of 0 will receive a higher priority than those with 3. It is HIGHLY recommended to lower the priority of mass-SMS transmissions, to avoid queues for more urgent transmissions. | flash
| (any) | No | unset | If set, the message will be delivered as a flash message, appearing directly in the message display on the receiver's phone | | dlr | (string) | No
| unset | Requires a valid URL. This URL will be opened when the SMS Gateway receives a Delivery Report. The URL will be opened by the gateway and contain special arguments in the querystring, see below for details.
Enabling DLR reporting to an URL will disable any logging done by the SMS Gateway, this includes being able to see status details inside the SMS Gateway login for the transmission in question. | Parameters other than the above are simply ignored.
Result
The following values may be returned from a client-server conversation.
All errors are prefixed with "ERR". Only one error is displayed at any given time, even if multiple errors may exist. An example of an error could be "ERR: Message rejected"
Upen success, the following message will appear: "SUCCESS: [n] SMS was scheduled for delivery", where "[n]" is the total number of messages queued for transmission.
Delivery Report Return Values
status Internal status value from SMS server:
1 Delivery successful
2 Delivery failure
4 Message buffered
8 SMSC submit
16 SMSC reject
answer A text answer from the SMS Center, can be returned in any language, normally Danish.
This message will also contain an EMI status value, documented in the EMI-UCP specifications, Appendix B, table B-3.
to The receiving number the SMS was transmitted to
ts A timestamp of the transmission, provided in UNIX EPOC.
id Internal queue ID from the Gateway, used for debugging
refid Reference ID as provided by the parameter `reference` during SMS scheduling. 0 is returned if no reference was attached to the transmission.
Example:
A dlr value of "http://example.com/dlr.php?page=dlr" is provided, the SMS gateway will then open this URL like so: "http://example.com/dlr.php?page=dlr&status=[status]&answer=[answer]&to=[to]&ts=[ts]&id=[id]"
each time a DLR is received from the SMS Center.
The queue
The internal SMS queue is checked once every second.
All messages in the queue is then forwarded to the SMSC which will deliver the message to the recipient.
Delivery should take no more than two seconds for any SMS, at any given time.
Connecting
Connections should always be passed as a socket connection, and never as a plain HTML since username and password would then be present in the HTML code.
PHP classes like HTTP_Request from PEAR and ASPHTTP can be used for easier handling of the socket connection.
A guide to installing PEAR on a shared host, using go-pear.org, can be found here.
Example 1
The following example is given of a plain socket conversation with the webserver.
The client:
POST /api/ HTTP/1.1
Host: sms.wannafind.dk
Keep-Alive: 300
Connection: close
Content-Type: application/x-www-form-urlencoded
Content-Length: 109
username=testuser&password=179ad45c6ce2cb97cf1029e212046e81&limit=1&recipient=12345678&message=this+is+a+test
The server (response):
HTTP/1.x 200 OK
Server: Apache/1.3.28 (Unix)
Keep-Alive: timeout=15, max=96
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/html
SUCCESS: 1 SMS was scheduled for delivery
Example 2
The following example is given of a plain socket conversation with the webserver, where the SMS is sent to multiple receipients.
The client:
POST /api/ HTTP/1.1
Host: sms.wannafind.dk
Keep-Alive: 300
Connection: close
Content-Type: application/x-www-form-urlencoded
Content-Length: 132
username=testuser&password=179ad45c6ce2cb97cf1029e212046e81&limit=1&recipient[]=12345678&recipient[]=87654321&message=this+is+a+test
The server (response):
HTTP/1.x 200 OK
Server: Apache/1.3.28 (Unix)
Keep-Alive: timeout=15, max=96
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/html
SUCCESS: 2 SMS was scheduled for delivery
PHP Example 1
Note: This example requires PEAR_Request.
require_once('HTTP/Request.php');
$req = & new HTTP_Request('http://sms.wannafind.dk/api/');
$req->setMethod(HTTP_REQUEST_METHOD_POST);
$req->addPostData('username', 'yourusername');
$req->addPostData('password', md5('yourpassword'));
$req->addPostData('recipient', '12345678');
$req->addPostData('from', 'Testuser');
$req->addPostData('message', 'This is a test');
$req->sendRequest();
# Print the output
echo $req->getResponseBody();
?>
ASP Example 1
Note: This example requires the ASPTear component
<%
Set objRequest = CreateObject("SOFTWING.ASPtear")
strPostData = "username=yourusername" _
& "&password=yourpasswordMD5" _
& "&recipient=12345678" _
& "&from=Testuser" _
& "&message="& Server.URLEncode("This is a test")
strResponse = objRequest.Retrieve("http://sms.wannafind.dk/api/", 1, strPostData, "", "")
' Print the output
response.write strResponse
%>
|
 Add to Favourites
 Print this Article
|
Knowledgebase