NXT\ WEB SERVICES - SMS SOAP API - Page 2. Directors: W.H ... Tel: (011) 322
3225 Fax: +27 (0) 86 616 5861 E-mail:
www.nxtnow.co.za .....
Version 3 06/10/2011 Functionality: SMS Delivery Receipts Retrieval Method.
NXT\ SPECIFICATION SMS SOAP WEB SERVICES Version: 4 Released: Wednesday, 25 September 2013 Authors: David Oosthuizen and Wayne Kruger Vendor: The NXT Thing Now (Pty) Ltd
CONTACT Tel: +27 (0) 11 322 3225 Fax: +27 (0) 11 217 3418 Email:
[email protected] Web: www.nxt.co.za
POSTAL Postnet Suite 432 Private Bag X1 Melrose Arch 2076
PHYSICAL Level 6 3 Sandown Valley Crescent Sandton 2196
The NXT Thing Now (Pty) Ltd Reg Number 2006/016657/07 VAT Number 4390233973 © 2008 - 2013 All Rights Reserved Directors: W.H Levine, A. Teeger
NXT\ WEB SERVICES - SMS SOAP API - Page 2
Table of Contents Overview ........................................................................... 3 Method: Sending SMS ...................................................... 4 Method: Inbox Retrieval .................................................... 5 Method: SMS Delivery Receipts Retrieval ........................ 6 NXT\ Support .................................................................... 7 Confidentiality & Ownership .............................................. 8 Version History.................................................................. 9
Directors: W.H Levine, A Teeger Physical Address Level 6, 3 Sandown Valley Crescent, Sandton, 2196 Tel: (011) 322 3225 Fax: +27 (0) 86 616 5861 E-mail:
[email protected] www.nxtnow.co.za Postal Address Postnet Suite 432, Private bag X1, Melrose Arch, 2076 The NXT Thing now (Pty) Ltd, Reg Number 2006/016657/07, VAT Number 4390233973, 2008 – 2010 All Rights Reserved
NXT\ WEB SERVICES - SMS SOAP API - Page 3
Overview The SMS SOAP Web Service Specifications from NXT\ will • Enable you to develop your applications and use NXT\ for sending SMS Messages, locally in South Africa; Access to this Web Service is over the Internet and will be limited based on the Client IP Address for extra security. •
Enable you to submit a message for delivery and get a confirmation that the request has been accepted; and You specify the Message, Mobile Number (MSISDN) and Source Brand (e.g. YOURNAME).
•
Enable you to retrieve a list of Inbox entries for the specified user within the specified Date Range.
NOTE: Credits are required to send SMS Messages. Credits are purchased on a prepaid basis from NXT\. Refer below for additional information.
? ?
Request SMS Credits from NXT\ on 011 322 3225 or
[email protected] SOAP (Simple Object Access Protocol) is a protocol specification for exchanging structured information in the implementation of Web Services. It relies on Extensible Markup Language (XML) as its message format. More info or the general SOAP specification from W3C can be found at: http://www.w3.org/TR/soap/ http://en.wikipedia.org/wiki/SOAP_(protocol)
Directors: W.H Levine, A Teeger Physical Address Level 6, 3 Sandown Valley Crescent, Sandton, 2196 Tel: (011) 322 3225 Fax: +27 (0) 86 616 5861 E-mail:
[email protected] www.nxtnow.co.za Postal Address Postnet Suite 432, Private bag X1, Melrose Arch, 2076 The NXT Thing now (Pty) Ltd, Reg Number 2006/016657/07, VAT Number 4390233973, 2008 – 2010 All Rights Reserved
NXT\ WEB SERVICES - SMS SOAP API - Page 4
Method: Sending SMS Web Service Address (Submit): http://[deckurl]/components/message.cfc?wsdl e.g.http://www.ciclops.co.za/components/message.cfc?wsdl Method Name: sendBulkMessage2 Parameters username password msisdn messages reference sourceNumber
Type string string string array string array string string
scheduledDateTime
date
Action The Username for the Deck Account to be used The Password for the Deck Account to be used The list of Mobile Numbers to send to * The list of Messages to send to ** A Unique Reference for this send The Source Number the send the SMS with (Only applicable to non South African MSISDN) Optional parameter to schedule a Bulk Message Batch for a future date
Returns: •
0 (Failed) or 1 (Success) followed by a PIPE (|) and a Message*** e.g. 1|Messages Successfully Submitted
Notes: •
* The MSISDN Parameter allows you to send an SMS to multiple recipients with one call. This will be limited to 4MB (this is the HTTP Request Size Limit).
•
** The Messages Parameter should either match up to the exact amount of MSISDN Array Elements (in which case each MSISDN will be sent it’s relating message), or it should contain only one element (in which case all the MSISDN will be sent the same message). An error will be returned otherwise.
•
*** If the return value is 1 the accompanying message will state „Messages successfully scheduled or „Messages Successfully Submitted , depending on the whether the scheduledDateTime is in the future. If the return value is 0 the accompanying message will state the reason for the failure e.g. “Insufficient Credits”.
• Please Note: Once the call has been made and the result returned it
does not mean the messages have been successfully delivered, it means that the batch has been submitted to the system for processing.
Directors: W.H Levine, A Teeger Physical Address Level 6, 3 Sandown Valley Crescent, Sandton, 2196 Tel: (011) 322 3225 Fax: +27 (0) 86 616 5861 E-mail:
[email protected] www.nxtnow.co.za Postal Address Postnet Suite 432, Private bag X1, Melrose Arch, 2076 The NXT Thing now (Pty) Ltd, Reg Number 2006/016657/07, VAT Number 4390233973, 2008 – 2010 All Rights Reserved
NXT\ WEB SERVICES - SMS SOAP API - Page 5
Method: Inbox Retrieval Method Name: getInboxByDateRange Description: Retrieves a list of Inbox entries for the specified user within the specified date range. Parameter username password startDateTime endDateTime
Type string string date/time date/time
Description The deck account’s username The deck account’s password The start of the date range to query The end of the date range to query
Returns: Returns an QueryBean object with two parameters: •
columnList: string array (string[ ]) with the list of column names: o MESSAGEID: Unique ID (GUID) for the message. o MESSAGEDATETIME: Date/Time message was received. o MESSAGEFROMNUMBER: Mobile number the message originated from. o MESSAGETONUMBER: Mobile number the message was sent to. o MESSAGETEXT: The actual text of the message. o OUTGOINGMESSAGEID: The Unique ID (GUID) of the original outgoing message
•
data: object array (object[ ] [ ]) with the data as defined in the column list.
Directors: W.H Levine, A Teeger Physical Address Level 6, 3 Sandown Valley Crescent, Sandton, 2196 Tel: (011) 322 3225 Fax: +27 (0) 86 616 5861 E-mail:
[email protected] www.nxtnow.co.za Postal Address Postnet Suite 432, Private bag X1, Melrose Arch, 2076 The NXT Thing now (Pty) Ltd, Reg Number 2006/016657/07, VAT Number 4390233973, 2008 – 2010 All Rights Reserved
NXT\ WEB SERVICES - SMS SOAP API - Page 6
Method: SMS Delivery Receipts Retrieval Method Name: getMessageStatus Description: Retrieves a list of SMS Delivery Receipts for the specified user based on the messageid. Parameter username password messageId
Type string string string
Description Sender account name Send account password Unique message id received upon submitting a message
Returns: The method returns a string in the following format: CODE|MESSAGE Currently there are 4 scenarios: •
The user supplied an invalid message ID: 0 | Invalid Message ID
•
The message was received by the system but it is either still scheduled for delivery or it was submitted and no response has been received yet: 1 | Message not yet submitted or awaiting response
•
A successfully delivered status report was received back for the message. 2 | Message successfully delivered
•
A delivery status was received but it was not successful. 3 | [Failed status code] Examples are: EXPIRED & REJECTED.
Directors: W.H Levine, A Teeger Physical Address Level 6, 3 Sandown Valley Crescent, Sandton, 2196 Tel: (011) 322 3225 Fax: +27 (0) 86 616 5861 E-mail:
[email protected] www.nxtnow.co.za Postal Address Postnet Suite 432, Private bag X1, Melrose Arch, 2076 The NXT Thing now (Pty) Ltd, Reg Number 2006/016657/07, VAT Number 4390233973, 2008 – 2010 All Rights Reserved
NXT\ WEB SERVICES - SMS SOAP API - Page 7
NXT\ Support Support
[email protected] Monday to Friday 9am to 5pm Business Days If you do not receive confirmation in 120 minutes Escalate
[email protected] Monday to Friday 9am to 5pm Business Days Support 011 322 3225 Monday to Friday 9am to 5pm Business days
Directors: W.H Levine, A Teeger Physical Address Level 6, 3 Sandown Valley Crescent, Sandton, 2196 Tel: (011) 322 3225 Fax: +27 (0) 86 616 5861 E-mail:
[email protected] www.nxtnow.co.za Postal Address Postnet Suite 432, Private bag X1, Melrose Arch, 2076 The NXT Thing now (Pty) Ltd, Reg Number 2006/016657/07, VAT Number 4390233973, 2008 – 2010 All Rights Reserved
NXT\ WEB SERVICES - SMS SOAP API - Page 8
Confidentiality & Ownership This Service Specification and the information herein is the sole property of The NXT Thing Now (Pty) Ltd. Use of this document and any of this information is strictly subject to Copyright © 2008 – 2010 The NXT Thing Now (Pty) Ltd All Rights Reserved. You may not in any manner reproduce, alter or copy anything contained herein, in part or as a whole, without the express prior written permission and consent of The NXT Thing Now (Pty) Ltd. This specification is a public draft release and is provided to NXT Clients only. The authors make no warrantees or representations regarding the specifications in any manner whatsoever.
Directors: W.H Levine, A Teeger Physical Address Level 6, 3 Sandown Valley Crescent, Sandton, 2196 Tel: (011) 322 3225 Fax: +27 (0) 86 616 5861 E-mail:
[email protected] www.nxtnow.co.za Postal Address Postnet Suite 432, Private bag X1, Melrose Arch, 2076 The NXT Thing now (Pty) Ltd, Reg Number 2006/016657/07, VAT Number 4390233973, 2008 – 2010 All Rights Reserved
NXT\ WEB SERVICES - SMS SOAP API - Page 9
Version History Revision Version 1 Version 2 Version 3
Date 19/03/2009 04/02/2010 06/10/2011
Changes First Specification Release Functionality: Retrieve a list of Inbox entries Functionality: SMS Delivery Receipts Retrieval Method
Directors: W.H Levine, A Teeger Physical Address Level 6, 3 Sandown Valley Crescent, Sandton, 2196 Tel: (011) 322 3225 Fax: +27 (0) 86 616 5861 E-mail:
[email protected] www.nxtnow.co.za Postal Address Postnet Suite 432, Private bag X1, Melrose Arch, 2076 The NXT Thing now (Pty) Ltd, Reg Number 2006/016657/07, VAT Number 4390233973, 2008 – 2010 All Rights Reserved
