SMS Services

Introduction

The SMS API sends SMS messages to Australian mobile phones in a single request. This API allows you to send and receive messages. You can also query the status of a previously sent SMS message.

The first step to use the Telstra SMS API is to create a developer account and apply for a new API key by registering your application on the portal. If you want your application to receive SMS messages from mobile devices it is important to register your call back URL. We are keeping the first release of the SMS API simple! So there is no need to select a longnumber or shortcode; the API will assign a number for each message that is being submitted.

There is a limit of 1000 free SMS messages per month and 100 per day. If you would like more volume then contact us at t.dev@team.telstra.com

Authentication

To get an OAuth 2.0 Authentication token, pass through your client_id and client_secret that you received when you registered for the SMS API key. The grant_type should be left as ‘client_credentials’ and the scope as ‘SMS’. The token will expire in one hour.

Response

Send SMS

The Send SMS method sends an SMS message to a single Australian mobile phone number. A unique identifier (messageId) returned in the response, which may be used to query for the delivery status of the message.

Considerations
  • Australian mobile phone numbers only.
  • You can only send to one number at a time.
  • The maximum message length is 160 characters.
Response

Get Message Status

Use the unique identifier (messageId) returned as returned in the response from the Send SMS method to get the status.

Considerations
  • Some status responses are dependent on the network that the receiving number belongs to. We can provide more more detailed status information for recipients who are on the Telstra network.

Response Status list
Status Description
PEND The message is pending and has not yet been sent to the intended recipient
SENT The message has been sent to the intended recipient, but has not been delivered yet
DELIVRD The message has been delivered to the intended recipient
READ The message has been read by intended recipient and the recipient's response has been received
Response

Get Message Response

The recipients of your SMS messages can send a reply which you can retrieve using the Get Message Response method. Pass through the unique identifier (messageId) returned as returned in the response from the Send SMS method and you will receive the reply and the timestamp.

Considerations
  • If no reply has been received, the acknowlegedTimestamp and the content will return “N/A”.
Response

SMS reply callbacks

SMS reply callbacks enable clients of the SMS API to be notified of replies to messages previously been sent out through the API. This works with client publishing an internet accessible url to which the Telstra API will send a POST request to. This approach removes the need for clients of the API to constantly poll the API for any replies, reducing unnecessary network traffic and logic.

Below is the callback flow for message reply:

  1. The user requests the API to send out a message to a recipient using send sms.
  2. After the message has been sent out and recieved by the recipient, the recipient replies.
  3. When the reply is recieved by Telstra, an HTTP POST request is made to the callback url (as defined by the client developer) containing the reply content along with the message id and status code

Considerations
  • The client application will need to publish an public URL on the internet that the Telstra API can access
  • The URL will need to handle an HTTP POST request
  • The POST request will contain a JSON payload
Callback payload format
Name Description
messageId ID returned from the Send SMS operation
status

READ - The message has been received by the network and is being processed for delivery to the handset or the message has been received by the handset.

UNDVBL - SMS API was not able to deliver the message to the intended recipient on the specified channel.

acknowledgedTimestamp The timestamp when the message is received.
content The content of the response message
Example payload

HTTP Status Codes

Status Code Description
200 OK Successful request
201 Created Successfully created the resource
202 Accepted Successfully accepted the request for processing
204 No Content Successfully processed the request, but no content was sent back
301 Moved Permanently Successful request, but the resource is no longer available at this location
302 Found Successful request, but the resource is temporarily not available at this location
304 Not modified Content hasn’t changed since last request
400 Bad Request Invalid or missing request parameters
401 Unauthorized Invalid or no credentials passed in the request
403 Forbidden Authorization credentials passed and accepted but account does not have permission
404 Not Found The requested URI does not exist
405 Method not allowed The requested resource does not support the supplied verb
415 Unsupported Media Type API does not support the requested content type
422 Unprocessable Entity The request is formed correctly, but due to some condition the request cannot be processed e.g. email is required and it is not provided in the request
500 Internal Server An internal error occurred when processing the request
501 Method Not Implemented The HTTP method being used has not yet been implemented for the requested resource
503 Service Unavailable The service requested is currently unavailable

Demo application - 'LetMeIn'

A sample application has been developed to illustrate how you might use the Telstra API to send an SMS to someone named Frank, asking him to open a door for you.

The application is written in Ruby, making use of the Sinatra framework.

The source of the demo application can be accessed from https://github.com/TelstraAPI/letmein.

Things you need to know

Telstra does not Guarantee that the provision of the SMS developer service will be fault free or continuous, or that SMS messages will be sent in a timely manner.

  • You are not permitted to use SMS services for the purpose of sending marketing messages (which are designed to promote the sale or demand for goods or services) unless you comply with the Spam Act 2003 (Cth), the ACIF guidelines for SMS, the eMarketing Code and any other applicable laws, industry standards and codes. Telstra may cancel your access to the Telstra API system if it has reason to believe that your are not complying with the law.
  • Important restrictions apply on the sending of large volumes of message. You should read the terms and conditions available at https://www.telstra.com.au/content/dam/tcom/personal/consumer-advice/pdf/business-b/bg-enhanced.pdf and on the developer portal https://dev.telstra.com/legal before using the SMS service. The send SMS API should not be used for time based initiatives that may result in a sudden peak of message traffic to the Telstra Mobile SMS network.
  • Delivery reporting – delivery reports may not be available where the SMS is sent to another carrier’s network.
  • Two-way messaging capability – you will only be able to send to and receive SMS messages from non-Telstra customers where we and the other phone company have agreed and fully implemented the necessary technology.

Telstra has no control over the networks of other carriers and cannot guarantee that a message will reach a final destination on another carrier’s network.