![Sending a SMS
URL: http://www.smsglobal.com/http‐api.php
HTTP Request
Find below a list of parameters when issuing a HTTP Request.
Parameter Description Presence
Action to be taken. [Default: sendsms] Mandatory
action
Your SMSGlobal username Mandatory
user
Your SMSGlobal password Mandatory
password
MSIDSN or Sender ID that the message will Mandatory
from appear from. Eg: 61409317436 (Do not use +
before the country code)
MSIDSN of the recipient that the message will be Mandatory
to sent to. Eg: 61409317436 (Do not use + before
the country code)
Message to be sent. Must be URL encoded. Mandatory
text
Enables splitting of message if text exceeds 160 Optional
maxsplit characters. Specifies number of times allowed to
split.
To schedule the message to be sent some Optional
scheduledatetime time/date in the future. Time/Date format is:
"yyyy‐mm‐dd hh:mm:ss" which is URL encoded.
Page 4 of 11](https://image.slidesharecdn.com/pdf3257-120911010112-phpapp01/85/pdf-4-320.jpg)
- 1. SMSGlobal – HTTP‐API August 2011 Copyright SMSGlobal Pty Ltd (AU) & Global Messaging FZ-LLC (UAE) No part of this document may be reproduced except as authorised by written permission. The copyright and foregoing restrictions extend to reproduction in all media. © SMSGlobal Pty Ltd. All rights reserved. CONFIDENTIAL
- 2. HTTP‐API Contents HTTP‐API ................................................................................................................................................. 3 Preface ................................................................................................................................................ 3 Introduction ........................................................................................................................................ 3 Features .............................................................................................................................................. 3 Sending a SMS ..................................................................................................................................... 4 HTTP Request ...................................................................................................................................... 4 HTTP Response ................................................................................................................................... 5 . Status Codes ........................................................................................................................................ 5 Examples ............................................................................................................................................. 5 Delivery Receipts ................................................................................................................................ 6 . Email ................................................................................................................................................... 6 . HTTP Post Back (URL) .......................................................................................................................... 7 Message Limitations ........................................................................................................................... 8 Sender ID ............................................................................................................................................. 8 Unicode (International Languages / Special Characters) .................................................................... 9 Scheduling ........................................................................................................................................... 9 Check User Balance ........................................................................................................................... 10 HTTP Request .................................................................................................................................... 10 HTTP Response ................................................................................................................................. 10 . Status Codes ...................................................................................................................................... 10 SMSGlobal Contact Details ............................................................................................................... 11 Page 2 of 11
- 3. HTTP‐API Preface Welcome to the SMSGlobal HTTP‐API. This document provides a reference for all features available to you via the HTTP interface for sending SMS. Further documentation can be found on our MobileWorks Administration in regards to configuration settings for this interface. Introduction The HTTP‐API allows you to integrate your Application (Client) to SMSGlobal (Vendor) using the HTTP protocol to send SMS. HTTPS is also supported for secure transactions using SSL encryption. The Client issues either a HTTP GET or POST request to the SMSGlobal HTTP interface supplying a list of required parameters. SMSGlobal issues back a HTTP Response which indicates the validity of the transaction. The HTTP‐API is used for 1 way messaging only. Therefore you need to provide a valid MSISDN as the Sender ID of the message to allow the recipient the ability to respond. Features Please find below a list of features for this API. Custom Sender ID Dedicated Virtual Numbers Delivery Receipt Notifications via Email/SMS Recipient OPT Out Option 24/7 support via our support system Page 3 of 11
- 4. Sending a SMS URL: http://www.smsglobal.com/http‐api.php HTTP Request Find below a list of parameters when issuing a HTTP Request. Parameter Description Presence Action to be taken. [Default: sendsms] Mandatory action Your SMSGlobal username Mandatory user Your SMSGlobal password Mandatory password MSIDSN or Sender ID that the message will Mandatory from appear from. Eg: 61409317436 (Do not use + before the country code) MSIDSN of the recipient that the message will be Mandatory to sent to. Eg: 61409317436 (Do not use + before the country code) Message to be sent. Must be URL encoded. Mandatory text Enables splitting of message if text exceeds 160 Optional maxsplit characters. Specifies number of times allowed to split. To schedule the message to be sent some Optional scheduledatetime time/date in the future. Time/Date format is: "yyyy‐mm‐dd hh:mm:ss" which is URL encoded. Page 4 of 11
- 5. HTTP Response The HTTP Response from SMSGlobal contains the following: Status Code Sent Queued Message ID (Internal use only) SMSGlobalMsgId Error message (if present) Status Codes If the message has been sent successfully the status code will return OK: 0 Example: OK: 0; Sent queued message ID: 941596d028699601 SMSGlobalMsgID:6764842339385521 If the message was unable to be delivered it will return ERROR: {Status code} {Error Msg} Example: ERROR: Missing parameter: from Examples Below are example requests when using the HTTP interface. Sending a SMS Username: testuser Password: secret From: 61447100300 To: 61447100250 Message: Hello World http://www.smsglobal.com/http‐ Request: api.php?action=sendsms&user=testuser&password=secret& from=61447100300&to=61447100250&text=Hello%20world Output: OK: 0; Sent queued message ID: 941596d028699601 SMSGlobalMsgID:6764842339385521 Page 5 of 11
- 6. Scheduling a SMS Username: testuser Password: secret From: 61447100300 To: 61447100250 Message: Hello World Schedule Date: 10th Jan, 2010 at 3pm Request: http://www.smsglobal.com/http‐ api.php?action=sendsms&user=testuser&password=secret& from=61447100300&to=61447100250&text=Hello%20world&scheduledatetime=2010‐ 01‐10%2015%3A00%3A00 Output: SMSGLOBAL DELAY MSGID:19736759 Note: A SMSGlobal Delay MSG ID is not the same as a SMSGlobal Message ID. Delivery Receipts Delivery notification on sent messages is provided by the following methods. Email – Each receipt will be sent via email HTTP Post Back – each receipt will be sent to your server to monitor These can be configured under preferences in your SMSGlobal account. Please refer to the Mobileworks Administration documentation further information. Email Upon delivery confirmation SMSGlobal can send an email to notify of delivery status. The email address that it will send these types of notifications to is the main email account associated with your SMSGlobal account. Warning: Bulk SMS will generate large numbers of delivery receipts and could flood your inbox. Page 6 of 11
- 7. HTTP Post Back (URL) Upon delivery confirmation SMSGlobal can Post Back to your own server to allow you to monitor the status of messages sent. Please refer to Delivery Receipt documentation for further information. Please find below the list of parameters that are sent. Parameter Description msg_id Unique SMSGlobal Message ID dlrstatus The status of the delivery for SMS. dlr_err The error code. The 10 digit date/time representation in the format of yymmddhhmm (year donedate month day hour minute) Page 7 of 11
- 8. Status Codes Parameter Description delivrd The message has been received by the handset. expired The carrier has timed out. undeliv The messages failed to reach the handset. Message Limitations SMS Length (160 characters) A single SMS has the limitation of being 160 characters in length. By default, if you attempt to send a message which is more than 160 characters, the message will be truncated. However you can explicitly indicate that you would like a message to be split into multiple message parts if it exceeds this limit. Each message part is equal to sending a single SMS. This is by passing the optional parameter MAXSPLIT with your request indicating how many times to split the message if it exceeds this limit. If a message exceeds 160 characters, it will be split into multiple message parts. Each message part is restricted to 153 characters in length (7 bytes for headers). MAXSPLIT Message Length / Parts 1 160 chars 2 306 chars (153*2) 3 459 chars (153*3) Note: A message will only be split if it exceeds 160 characters. If your message is under 160 characters and you specify a split parameter, you will only be charged for a single message. Sender ID It is possible to specify your Sender ID as an alphanumeric string. It must be between 3 – 11 characters. Page 8 of 11
- 10. Check User Balance URL: http://www.smsglobal.com/credit‐api.php HTTP Request Find below a list of parameters when issuing a HTTP Request. Parameter Description Presence user Your SMSGlobal username Mandatory password Your SMSGlobal password Mandatory country 2 digit ISO country code of SMS destination Mandatory ISO country codes can be found at http://en.wikipedia.org/wiki/ISO_3166‐1 the ISO code is a 2‐digit alpha representation of the country. An example is, Australia = AU, United Kingdom = GB HTTP Response The HTTP Response from SMSGlobal contains the following: User balance in credits Selected country User balance in SMS for selected country Status Codes If the message has been sent successfully the status code will return balance details. This includes how many credits are linked with the account, and how many SMS that relates to. Example: CREDITS:8658.44;COUNTRY:AU;SMS:3764.54; If there is an error with the request such as invalid details, the system will return Error:11; Invalid login details; All errors will be returned as Error:XX; STR_ERROR; Page 10 of 11
- 11. Example: Error:11; Invalid login details; SMSGlobal Contact Details SMSGlobal Headquarters SMSGlobal EMEA Office 96 ‐ 98 Market Street 3015 Shatha Tower South Melbourne Dubai Media City, Dubai Victoria 3205 UNITED ARAB EMIRATES Australia T: +971 4 440 9600 T: 1300 883 400 F: +971 4 445 8467 T: +61 3 9095 6245 F: +61 3 9646 8837 PO Box 502014 – Dubai, UAE Web Address: www.smsglobal.com Support: http://www.smsglobal.com/support/ Page 11 of 11