Вы находитесь на странице: 1из 16

SMS Gateway

API & Application Technical Documentation

Revision 1
Current as at 10th August 2010 Document ID: DOC-SMS-API-R1

Information in this document is subject to change without notice. This document is updated periodically, please contact Neural Networks to obtain the most up to date revision. All prices quoted are inclusive of GST and are not applicable to customers outside of Australia. Customers from countries other than Australia should contact Neural Networks at sales@neural.com.au for a quote. All prices are in AUD (Australian Dollars). Surcharges may apply depending on payment method.

(C) Copyright 2010 Neural Networks Data Services Pty. Ltd. All rights Reserved

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

Contents
1.0.0 Welcome 2.0.0 API Endpoint & Access Options o 2.1.0 Direct HTTPS API Usage 2.1.1 Direct HTTPS API Return Formatting o 2.2.0 Command Line Interfaces (CLI) 2.1.1 Command Line Interfaces (CLI) Downloads 2.1.2 Command Line Interfaces (CLI) Usage 3.0.0 Postbacks and delivery tracking o 3.1.0 Postbacks 3.1.1 HTTP / HTTPS API Postbacks 3.1.2 E-Mail Postbacks o 3.2.0 Delivery Tracking 4.0.0 Sample code o 4.1.0 PHP Sample code 5.0.0 Notes and FAQs o 5.1.0 Long Messages o 5.2.0 Caller ID Formatting o 5.3.0 Notes 6.0.0 Questions / Need Help?

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

1.0.0 Welcome
Thanks you for choosing Neural Networks SMS Gateway API Services. This technical documentation will provide you with all the information you need to start utilising your new SMS gateway service to enhance your business communication utilising SMS.

This document is intended for a technical audience. If youre looking for product information such as pricing, or information on how Neurals SMS products can benefit your business, please see our website at:

https://www.neural.com.au/sms

New versions of this technical documentation will be released periodically. Please see our website to download the latest revision.

2.0.0 API Endpoint & Access Options


Neurals SMS API can be access by a number of different methods. The following sections detail the available endpoints and their usage. If youre unsure of which endpoint is most suitable for your application, please dont hesitate to contact Neural support and wed be happy to discuss your requirements.

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

2.1.0 Direct HTTPS API Usage


An HTTPS API endpoint is available for direct access over the HTTPS protocol. This provides a universally accessible endpoint to any language or platform.

This endpoint can be accessed from many languages including: Any Microsoft .NET or Visual Studio Language o VB / VB .NET o C# / C# .NET o ASP / ASP .NET o etc. Perl Python Ruby PHP Java Practically any language that can make an HTTPS request with POST

For languages without a direct implementation of HTTPS and POST calls - an external library such as cURL may be used, or alternative API endpoints such as the command line applications may be used.

The HTTPS API Address that POST requests should be sent to is:

https://sms.neural.net.au:15000/
POST Arguments are as follows:
Field Name cid to msg user pass service confirm Example Test Inc. 0412345678 Hi! This is a test message! User123 t0Ps3cret?@1 1234 0 Description Caller ID displayed on the receivers mobile Destination mobile number in 04XXXXXXXX format Message content Your username Your password The service ID to send this message through Track delivery, and send postback as configured [0/1]

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

2.1.1 Direct HTTPS API Return Formatting


Responses to the direct HTTPS API are provided in the following format:

state|argument
The state field will be one of: queued error

queued The message was received by the API server successfully and has been queued to be sent. In this case, the argument contains the message ID, which is used to track the message for postbacks and audit.

error The message was not received successfully by the API server. In this case, the argument contains the error code. Please see the section Return codes error listing for a complete list of error codes.

Return states and arguments are always provided in lower case

Once a message has entered the queued sate, the SMS gateway servers will attempt to deliver it to the receivers handset. If the confirm field was set to 1 then a postback will be triggered when delivery is either successful, fails or times out. Please see the section Postbacks and delivery tracking for more information.

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

2.2.0 Command Line Interfaces (CLI)


Neural provides two command line applications to allow easy integration with scripts, 3 rd party applications and languages lacking HTTPS support.

2.2.1 Command Line Interfaces (CLI) Downloads


You can download these applications from the following addresses:

Windows: http://support.neural.com.au/index.php?_m=knowledgebase&_a=viewarticle&kbarticlei d=40&nav=0,10,12 Linux / BSD / Solaris: http://support.neural.com.au/index.php?_m=knowledgebase&_a=viewarticle&kbarticlei d=41&nav=0,10,12

2.2.1 Command Line Interfaces (CLI) Usage


Both the Windows and Linux command line clients accept the same arguments. Please see the readme.txt and usage.txt included with each for detailed instructions.

Usage: sms.exe user pass serviceID* destination message [callerid] [confirmation] Example: sms.exe john s3cret123 300 0400000000 "Testing SMS from CLI" "1800NEURAL" 1

* Service ID can be obtained from portal, under service properties

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

3.0.0 Postbacks and delivery tracking


If confirmation is requested on a message, postbacks and delivery tracking are made available for the message. The following sections cover postbacks and delivery tracking and their usage.

3.1.0 Postbacks
Postbacks allow you to track the delivery of messages youve sent via Neurals API. This is done by way of automated responses sent from Neurals API servers back to you, providing updates on a messages delivery status. Postback can be provided in a number of ways, as detailed in the following sections.

3.1.1 HTTP / HTTPS API Postbacks


Delivery confirmation can be provided by HTTP or HTTPS API postbacks to your servers. This requires a server with an internet accessible static IP running an HTTP or HTTPS server with a web application capable of receiving and processing POST requests. Callbacks are sent to a URL of your specification, with the following arguments:

[action] => smscallback Static, always contains this value. Useful for multi-purpose callback scripts.

[uid] => [Number] This will be the unique ID of the SMS that was returned when the message was originally sent.

[status] => 0 Status will be one of: 0 Queued (generally wont be sent as it is implied on sending, can be enabled on request) 1 Sending 2 Sent

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

3 Error 4 - Received

[error] => [Error Message] Only sent when status is 3. Contains error code as detailed in return codes error code listing.

[completetime] => [Date & Time] Date and time the action was completed (YYYY-MM-DD HH:MM:SS). GMT+10 AEST.

Please contact Neural support to have this feature enabled on your account.

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

3.1.2 E-Mail Postbacks


Your account can be configured to send e-mail postbacks on message delivery success / delay or failure to an address of your choosing. This can be integrated with backend systems (by parsing the e-mail postbacks) and provides an excellent manual audit and archive solution for SMS communications.

Please contact Neural support to have this feature enabled on your account.

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

3.2.0 Delivery Tracking


You can monitor the delivery of individual or bulk messages via Neural SMS manager. This provides a visual indication of a messages delivery status all the way form queued to received.

You can access Neural SMS Manager at:

http://sms.neural.net.au/
You can track message delivery by navigating to

Outbound > Outbound message listing


Here you will find a listing of your most recently sent messages.

The Confirm field shows the message delivery confirmation status of the message. Confirm states can include: Not requested Pending Confirmed Not Received

The processing column shows the current processing state of the message, processing states can include: Queued Sending Sent Received Failed

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

The manual delivery tracking method encompasses API with no postback.

Delivery tracking can optionally be combined with one of the other available postback methods to allow both automatic postback, as well as manual audit via the Neural SMS Manager interface.

Did you know: Neural SMS Manager also provides a quick and user-friendly way to manually send SMS messages without the use of the APIs.

Did you know: Neural SMS Manager is available as a white-label product. This means you can provide it to your customers with your branding and colour scheme. Contact our sales department today for more information.

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

4.0.0 Sample code


Sample code for API usage is provided in the following sections. Additional languages will be provided in later revisions of this document, and via our knowledge base at:

http://support.neural.com.au/

4.1.0 PHP Sample code


The following sample code demonstrates the use of the HTTP API using cURL. You will need the PHP cURL module installed and loaded, as well as the cURL package for your operating system.

<?php $postData = array(); $postData['cid'] = 'Test'; //Caller ID $postData['to'] = ''; //Destination number $postData['msg'] = 'This is a test message'; //Message test $postData['user'] =; //TT Username $postData['pass'] = ''; //TT Password $postData['service'] = ''; //Service ID - can be obtained from portal.neural.net.au under 'Service Information' $postData['confirm'] = '0'; //Send postback on completion (1 = yes, 0 = no) $postData['action'] = 'sendsms'; $ch = curl_init(); curl_setopt($ch, CURLOPT_USERAGENT, "Neural SMS PHP Example Code"); curl_setopt($ch, CURLOPT_HEADER, false); curl_setopt($ch, CURLOPT_VERBOSE, false); curl_setopt($ch, CURLOPT_URL, "https://sms.neural.net.au:15000/"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch, CURLOPT_POSTFIELDS, $postData); $result = explode('|',curl_exec($ch)); curl_close($ch); if($result[0] == 'queued'){ echo 'Message queued for sending with unique ID ' . $result[1]; }elseif($result[0] == 'error'){ echo 'Sending failed - error code ' . $result[1]; }elseif(!$result[0]){ echo 'No response received - communication issue'; }else{ echo 'Unexpected response received: ' . $result[0]; }; ?>

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

Return codes Error Code Listing


In the event of an error, you may receive one of the following return codes back from the API. Please note that there are additional return codes specific to SMS on the following page. Please see the previous pages for response formatting from the various API endpoints.

API Global Return Codes: 1 Authentication failure Please check your username and password. 2 You must specify a username and password Please supply a username and password. 7 Internal error An internal error has occurred on the API server, please try again. 10 Service identification error You may be using the incorrect service ID. This error may occur, for example, of the service ID of a fax service was sent to the SMS API. 11 Service ID access denied You may be using the incorrect service ID. This occurs when the service ID specified does not exist on your account. 12 No action specified You must specify an action for every API request, please refer to the documentation for proper action request methods. 16 Communications issue - check connection There was a problem communication with the API server, please check your internet connection. Not all API interfaces will provide this error code. For example, it is not provided if a connection fails to the direct HTTP API. 17 Unexpected response - check for proxies or filters The response from the API server was unexpected. There may be a proxy server or internet access filter / firewall in between the client and API server that is interfering with communication.

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

SMS Specific Return Codes: 3 Both a source and destination number are required You must include a source (caller ID) and destination number for every SMS. Source number may contain numbers, letters and spaces. Destination number must be a valid mobile number. 5 Invalid destination number The destination number specified is invalid. Numbers should be in standard Australian mobile number format (04XXXXXXXX). 8 Caller ID too long The caller ID specified is too long. The limit is 11 characters. Some older phones may not display caller IDs longer than 10 characters correctly 9 You must supply a message A message to send must be specified. You cannot send an empty message. 15 You must have an SMS service to access this API Your account may not have an SMS service. Please contact support if you receive this error code.

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

5.0.0 Notes and FAQs


The following sections list some important notes, as well as frequently asked questions regarding Neurals SMS API services.

5.1.0 Long Messages


Messages over 160 characters will be sent as normal, being automatically split into 160 character blocks. They will arrive as one message on the receivers mobile if it supports message fragmentation. All modern handsets support this, however some older ones may not. Please be aware that for fragmented messages, you will be charged for one message per 160 character fragment. For example, if you sent a 200 character message, two message charges would be incurred.

5.2.0 Caller ID Formatting


Caller ID can be up to 11 characters long, however we recommend using 10 characters or below to maintain universal handset compatibility. Spaces, numbers and letters can be used. Special characters are not supported, with the exception of full stops, exclamation marks and hyphens.

5.3.0 Notes

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Neural Networks Data Services Pty Ltd ABN 57 124 535 075 ACN 124 535 075

6.0.0 Questions / Need Help?


Neural support is on call 24 x 7 to assist. Whether youre stuck, or just have some general questions, please dont hesitate to ask!

Call us

1800 NEURAL
1800 638 725 or (07) 3123-5311

Option 2 E-Mail us

(Support)

support@neural.com.au

Well call you!

www.neural.com.au/callback

More product information is available on our website

www.neural.com.au/products

Manage your existing services

You can access your reseller account via portal.neural.net.au

Ph: 1800NEURAL or (07) 3123-5311 Fax: (07) 3123 - 5312 www.neural.com.au

Email: sales@neural.com.au PO Box 12017 George St QLD 4003

Вам также может понравиться