Table of Contents    

 

HTTP API

  Introduction
  HTTP API Operations
     Operation: CONNECT()
     Operation: SEND_BRANDED_MESSAGE()
     Operation: SEND_TWO_WAY_MESSAGE()
     Operation: SCHEDULE_BRANDED_MESSAGE()
     Operation: SCHEDULE_TWO_WAY_MESSAGE()
     Operation: GET_REPLIES()
     Operation: GET_INBOUND_MESSAGES()
     Operation: GET_BALANCE()
     Operation: DISCONNECT()
  Errors
 
 Introduction  

This is one of the server-based forms of communication to the directSMS API. It can be used either in the form of a HTTP POST, or as an URL (GET). We recommend POST for larger data transfer due to the size limitations of GET. Communication to our API can be done via HTTP on port 80 or HTTPS on port 443. All calls to the API must be URL-encoded.

Table of Contents




 HTTP/S Operations  

This API allows clients to login and use the various message send and receive functions available through the directSMS S3 gateway.

The following operations are available through the HTTP/S API.

Table of Contents




 CONNECT()  

Description

This is the main way for users to authenticate using their directSMS username and password.

If the credentials supplied belong to a valid user account, a 32 byte connection id is returned.

This id is then used for the rest of the user's session with other operations.

If the user account used is not set up for API access, an error will be returned.

In order to use the API, you can either contact the directSMS Support team to enable this feature on your account. This will activate your 60 day API trial. Please note; this is a single seat licence, for use on one customer account only.

The second option is to purchase an enterprise licence which will require you to pass the licence key along with the login credentials for authentication when opening a new connection. This is the approach to take if you are developing an application that will be distributed to multiple customers.

HTTP URL:  http://api.directsms.com.au/s3/http/connect

HTTPS URL: https://api.directsms.com.au/s3/https/connect

Parameters

username     - directSMS username  [REQUIRED]
password - directSMS password [REQUIRED]
licence_key - A valid licence key [OPTIONAL]

Output   id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Error err: error message

Table of Contents




 SEND_BRANDED_MESSAGE()  

Description:

Send a branded sms. The user must supply a valid connection id, along with the various parameters required for a branded message. On success, a 32 byte message identifier is returned. If any error conditions are encountered, an appropriate error message is returned

HTTP URL:    http://api.directsms.com.au/s3/http/send_branded_message
HTTPS URL: https://api.directsms.com.au/s3/https/send_branded_message

Parameters:

connectionid -   The 32 character id returned by the connect() operation. i.e.
                 the portion of the message after id: [REQUIRED]
message - The SMS message [REQUIRED]
to - A list of one or more mobile phone numbers separated by "," [REQUIRED]
senderid - The sender id to appear on the message in place of a sending phone number. The sender id must not exceed 11 characters in length and it must not contain characters outside of: a-z, A-Z, . or 0-9. This can be set to your own mobile number which means when recipients reply, the replies will go to your phone. The replies however will not be tracked by directSMS' gateway [REQUIRED]

Output   id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Error err: error message

Table of Contents




 SEND_TWO_WAY_MESSAGE()  

Description:

Send a 2-way message. Works in the same way as the previous operation, with the difference of the user having the ability to specify a "message id" which they can then use to track replies. On success, a 32 byte message identifier is returned. If any error conditions are encountered, an appropriate error message is returned instead.

HTTP URL:    http://api.directsms.com.au/s3/http/send_two_way_message
HTTPS URL: https://api.directsms.com.au/s3/https/send_two_way_message

Parameters:
connectionid -   The 32 character id returned by the connect() operation. i.e.
                 the portion of the message after id: [REQUIRED]
message - The SMS message [REQUIRED]
to - A list of one or more mobile phone numbers separated by "," [REQUIRED]
messageid - A string to idenity this message and to associate its replies. This id is limited to 12 characters only [OPTIONAL]

Output   id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Error err: error message

Table of Contents




 SCHEDULE_BRANDED_MESSAGE()  

Description:

Send a branded sms. The user must supply a valid connection id, along with the various parameters required for a branded message. On success, a 32 byte message identifier is returned. If any error conditions are encountered, an appropriate error message is returned.

HTTP URL:    http://api.directsms.com.au/s3/http/schedule_branded_message
HTTPS URL: https://api.directsms.com.au/s3/https/schedule_branded_message

Parameters:

connectionid -   The 32 character id returned by the connect() operation. i.e.
                 the portion of the message after id: [REQUIRED]
message - The SMS message [REQUIRED]
to - A list of one or more mobile phone numbers separated by "," [REQUIRED]
senderid - The sender id to appear on the message in place of a sending phone number. The sender id must not exceed 11 characters in length and it must not contain characters outside of: a-z, A-Z, . or 0-9. This can be set to your own mobile number which means when recipients reply, the replies will go to your phone. The replies however will not be tracked by directSMS' gateway [REQUIRED]
timestamp - The date and time to send this SMS, represented as the number of seconds after the Unix Epoch (January 1 1970 00:00:00 GMT). This ensures time zone independance. [REQUIRED]

Output   id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Error err: error message

Table of Contents




 SCHEDULE_TWO_WAY_MESSAGE()  

Description:

Schedule a 2-way message. Works in the same way as the previous operation, with the difference of the user having the ability to specify a "message id" which they can then use to track replies to this message.

On success, a 32 byte message identifier is returned. If any error conditions are encountered, an appropriate error message is returned instead.

HTTP URL:    http://api.directsms.com.au/s3/http/schedule_two_way_message
HTTPS URL: https://api.directsms.com.au/s3/https/schedule_two_way_message

Parameters:
connectionid -   The 32 character id returned by the connect() operation. i.e.
                 the portion of the message after id: [REQUIRED]
message - The SMS message [REQUIRED]
to - A list of one or more mobile phone numbers separated by "," [REQUIRED]
messageid - A string to idenity this message and to associate its replies. This id is limited to 12 characters only [OPTIONAL]
timestamp - The date and time to send this SMS, represented as the number of seconds after the Unix Epoch (January 1 1970 00:00:00 GMT). This ensures time zone independance. [REQUIRED]

Output   id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Error err: error message

Table of Contents




 GET_REPLIES()  

Description:

Fetch the replies for All or a given 2-way message (depending on the parameters passed). The operation also takes an optional parameter to mark the replies as read (to avoid fetching them again).

HTTP URL:    http://api.directsms.com.au/s3/http/get_replies
HTTPS URL: https://api.directsms.com.au/s3/https/get_replies

Parameters:
connectionid -   The 32 character id returned by the connect() operation.
                 i.e. the portion of the message after id: [REQUIRED]
messageid - The 12 byte message id passed to an earlier call to the send_two_way_message() operation. This parameter is used to identify one and only one 2-way message. If this parameter is not present, new replies to all 2-way messages are returned. [OPTIONAL]
mark_as_read - Mark the returned reply messages as read, to avoid returning them again in future [OPTIONAL]

Output
        If the are no replies:

        replies: 0

        Otherwise:

        replies: xx
        messageid: xxxx mobile: xxxx message: xxxxxxxxxxxxxx when: xxx
        messageid: xxxx mobile: xxxx message: xxxxxxxxxxxxxx when: xxx
        messageid: xxxx mobile: xxxx message: xxxxxxxxxxxxxx when: xxx
        messageid: xxxx mobile: xxxx message: xxxxxxxxxxxxxx when: xxx

        The replies field on the first line will tell you how many reply
        messages were received matching your query. Each reply occupying
        a separate line in the output.

        The fields on each line will have the following widths:

        messageid:  12 characters

        mobile:     20 characters in the format +61412345678

        message:    160 characters

        when:       1 or more characters (this is the number of seconds
                    since the reply was received).

        Each field is separated from its heading and the next field's
        heading by 1 space.

Error
        err: error message

Table of Contents



 GET_INBOUND_MESSAGES()  

Description:

Retrieve All or some of the unread inbound SMS messages (depending on the parameters passed). The operation also takes an optional parameter to mark the messages retrieved as read (to avoid fetching them again).

HTTP URL:    http://api.directsms.com.au/s3/http/get_inbound_messages
HTTPS URL: https://api.directsms.com.au/s3/https/get_inbound_messages

Parameters:
connectionid -   The 32 character id returned by the connect() operation.
                 i.e. the portion of the message after id: [REQUIRED]
inbound_number - The number the inbound messages were sent to. If this is is not specified, unreas messages received on any inbound number is returned. [OPTIONAL]
mark_as_read - Mark the returned sms messages as read, to avoid returning them again in future [OPTIONAL]

Output
        If the are no replies:

        messages: 0

        Otherwise:

        messages: xx
        inbound: xxxx mobile: xxxx message: xxxxxxxxxxxxxx when: xxx
        inbound: xxxx mobile: xxxx message: xxxxxxxxxxxxxx when: xxx
        inbound: xxxx mobile: xxxx message: xxxxxxxxxxxxxx when: xxx
        inbound: xxxx mobile: xxxx message: xxxxxxxxxxxxxx when: xxx

        The messages field on the first line will tell you how many sms
        messages were received matching your query. Each message occupying
        a separate line in the output.

        The fields on each line will have the following widths:

        inbound:    20 characters in the format +61412345678

        mobile:     20 characters in the format +61412345678

        message:    160 characters

        when:       1 or more characters (this is the number of seconds
                    since the reply was received).

        Each field is separated from its heading and the next field's
        heading by 1 space.

Error
        err: error message

Table of Contents


 GET_BALANCE()  

Description:

Fetch the number of credits left on the customer's account.

HTTP URL:    http://api.directsms.com.au/s3/http/get_balance
HTTPS URL: https://api.directsms.com.au/s3/https/get_balance

Parameters:
connectionid -   The 32 character id returned by the connect() operation. i.e. the
                 portion of the message after id: [REQUIRED]
Output credits: xxxx
Error err: error message

Table of Contents




 DISCONNECT()  

Description:

End a directSMS connection.

HTTP URL:    http://api.directsms.com.au/s3/http/disconnect
HTTPS URL: https://api.directsms.com.au/s3/https/disconnect

Parameters:
connectionid -   The 32 character id returned by the connect() operation. i.e. the
                 portion of the message after id: [REQUIRED]

Output   id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Error err: error message

Table of Contents




 Errors  

The following is a listing of all the errors that may be encountered when interacting with the SMS gateway through the HTTP API.

Error Message Description
err: sms gateway unreachable, please try again later SMS gateway is temporarily down
err: invalid login credentials Username and/or password provided are not valid
err: message text is mandatory Message text is a mandatory field
err: mobile number(s) are mandatory No mobile numbers entered to receive the SMS
err: sender id is mandatory Sender ID is a mandatory field for Branded SMS
err: connection id is mandatory Connection ID is mandatory
err: invalid mobile number(s) detected One or more invalid mobile numbers were submitted. Mobile numbers must be in the format "0411 222 333" or "61 411 222 333"
err: insufficient sms credit balance to send submitted message(s) Insufficient funds in your account to send the given SMS
err: submitted message must not contain more than 200 mobiles There is a limit of 200 mobiles per SMS for performance reasons
err: internal sms gateway error SMS gateway is temporarily down
err: invalid connection id; please use the connect() operation before calling other operations Connection ID passed does not identify any gateway connections
err: connection already closed; disconnect() operation was called earlier Connection ID passed identifies a closed gateway connection
err: sender id must not contain any characters outside of 0-9, a-z, . or A-Z The Sender ID of a branded message contains invalid characters
err: sender id must not exceed 11 characters The Sender ID of a branded message can not be longer than 11 characters
err: inbound number is invalid The inbound number specified is invalid. It must be a valid mobile number
err: inbound account not found The inbound number specified is not linked to any inbound sms accounts
err: inbound account not found or is no longer active The inbound number specified is not lined to an active inbound sms account

Table of Contents