SMS Gateway. API & Application Technical Documentation. Revision 1. Current as at 10 th August Document ID: DOC-SMS-API-R1

Transcription

1 SMS Gateway API & Application Technical Documentation Revision 1 Current as at 10 th 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

2 Contents Welcome API Endpoint & Access Options o Direct HTTPS API Usage Direct HTTPS API Return Formatting o Command Line Interfaces (CLI) Command Line Interfaces (CLI) Downloads Command Line Interfaces (CLI) Usage Postbacks and delivery tracking o Postbacks HTTP / HTTPS API Postbacks Postbacks o Delivery Tracking Sample code o PHP Sample code Notes and FAQ s o Long Messages o Caller ID Formatting o Notes Questions / Need Help?

3 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 you re looking for product information such as pricing, or information on how Neural s SMS products can benefit your business, please see our website at: New versions of this technical documentation will be released periodically. Please see our website to download the latest revision API Endpoint & Access Options Neural s SMS API can be access by a number of different methods. The following sections detail the available endpoints and their usage. If you re unsure of which endpoint is most suitable for your application, please don t hesitate to contact Neural support and we d be happy to discuss your requirements.

4 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: POST Arguments are as follows: Field Name Example Description cid Test Inc. Caller ID displayed on the receiver s mobile to Destination mobile number in 04XXXXXXXX format msg Hi! This is a test message! Message content user User123 Your username pass t0ps3cret?@1 Your password service 1234 The service ID to send this message through confirm 0 Track delivery, and send postback as configured [0/1]

5 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 receiver s 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.

6 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 Command Line Interfaces (CLI) Downloads You can download these applications from the following addresses: Windows: d=40&nav=0,10,12 Linux / BSD / Solaris: d=41&nav=0,10, 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 s3cret "Testing SMS from CLI" "1800NEURAL" 1 * Service ID can be obtained from portal, under service properties

7 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 Postbacks Postbacks allow you to track the delivery of messages you ve sent via Neural s API. This is done by way of automated responses sent from Neural s 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 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 won t be sent as it is implied on sending, can be enabled on request) 1 Sending 2 Sent

8 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.

9 Postbacks Your account can be configured to send postbacks on message delivery success / delay or failure to an address of your choosing. This can be integrated with backend systems (by parsing the 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.

10 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 message s delivery status all the way form queued to received. You can access Neural SMS Manager at: 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

11 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.

12 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: 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, " 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]; };?>

13 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.

14 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 ID s 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.

15 5.0.0 Notes and FAQ s The following sections list some important notes, as well as frequently asked questions regarding Neural s SMS API services 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 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 Notes

16 6.0.0 Questions / Need Help? Neural support is on call 24 x 7 to assist. Whether you re stuck, or just have some general questions, please don t hesitate to ask! Call us 1800 NEURAL or (07) Option 2 (Support) us support@neural.com.au We ll call you! /callback More product information is available on our website /products Manage your existing services You can access your reseller account via portal.neural.net.au