Key differences between v2 and v3.

What's new in Messaging v3?  

Get more done with the new and improved Telstra Messaging API v3. We've redesigned our REST API to make it easier than ever to send feature-rich messages across the globe. Learn more about the key differences between V2 and V3 and the new features and functionalities you can look forward to in this release.  

Name changes 

We've changed the name of some features and parameters to make it easier to understand our API and the accompanying documentation. 

*In the previous version of the API, notifyUrl referred to either the URL you wanted replies to be sent to, or the URL you wanted us to notify when the status of your message changed. In the new version, these parameters are called replyCallbackURL and statusCallbackUrl respectively.  

Start sending right away 

Sending your first message is now easier than ever. If you’re using the Free Trial, you no longer need to register a B Number beforehand. Instead, the first five people you message will be automatically added to your Free Trial Numbers list. That means once you’ve authenticated, you can start messaging right away. 

View our Getting Started guide for step-by-step instructions on how to send your first message.  

Choose what your recipients see in the ‘from’ field 

Virtual Numbers (previously subscriptions) are now completely optional, so you can send a message without setting one up. If you don’t want to use a Virtual Number, you can message from a senderName (paid plans only) or privateNumber instead.  

If you do want to assign a Virtual Number to your account, just use POST /virtual-numbers. Paid plan users can now assign up to 100 Virtual Numbers per account at a cost of $15 per number, and the first five are free. Free Trial users can assign one optional Virtual Number free of charge. 

We’ve also removed the expiry on Virtual Numbers (subscriptions). In V3, your Virtual Number will only be unassigned from your account if you haven't used it to send a message in three months (Free Trial) or 24 months (paid plans). You can always check the lastUse date of your Virtual Number using GET /virtual-numbers/{virtual-number}. 

Set a sender name  

An alphanumeric identifier is now called a sender name. If you're on a paid plan, you can use the senderName parameter to set a unique string of up to 15 characters that will appear in the "from" field when a recipient receives a message. 

Message from a single endpoint  

Sending text messages or multimedia? You can now send both SMS and MMS from POST /messages.  

Create your own customisable tags 

You can now fetch, sort and report on your messages and Virtual Numbers by assigning them tags. 

Use a single endpoint to fetch SMS and MMS replies  

Use GET /messages to fetch both SMS and MMS replies. You can filter the results by direction: choose either inbound (messages sent to your account) or outbound (messages sent from your account). You can also filter your results by tag, messageContent, virtualNumber or Recipient Number.  

Note that if you're using a Virtual Number, you still have the option of posting a callback URL that we will ping when you receive a reply. Previously you posted this notifyUrl using POST / messages/provisioning/subscriptions. In V3, send it as the replyCallbackUrl in POST /virtual-number.  

Get more from status updates  

When you supply a valid statusCallbackURL, you’ll now receive more meaningful status updates: 

• sent – your message has been sent from the server.    

• delivered – the message has successfully reached the recipient’s network. Note that we will only be able to return this status if you set deliveryNotification to ‘TRUE’ (paid feature).  

• expired – we weren’t able to send the message within the retryTimeout timeframe.  

Message at scale and prioritise your queue 

Our new API can scale with you. We’ve raised the limit on messaging requests, so you can now send 1,000 messages or more at once. We'll automatically queue your messages for sending, plus you can also use queuePriority to tell us how you want to prioritise them.  

Keep track of your messages 

We now store your sent and received messages from the last 30 days, so you can easily fetch them when you need to. 

Generate reports 

Get a detailed overview of your account activity with our new reports endpoint. Generate a VSV report of messages sent/to from your account within the last three months as well as daily volume outputs, plus use filters to refine your report results.  

Let us take care of any optouts 

Recipients can now opt out of receiving messages from a Virtual Number by replying with STOP, STOPALL, UNSUBSCRIBE, CANCEL, END or QUIT. When we receive an optout keyword, we'll automatically add the recipient to your optouts list. 

Troubleshoot with clearer error messages 

We've introduced a standardised error schema with more descriptive codes and detailed suggested actions, so you have everything you need to handle errors.  

Pricing differences 

• In V2, MMS were charged at a rate of $0.25 (under 600KB) and $0.40 (over 600KB). MMS in V3 will be charged at the flat rate of $0.25 per message, regardless of size.   

• Delivery notifications will be charged upfront, at a cost of $0.01.   

• You now have the option to purchase additional Virtual Numbers after your allocation of five free Virtual Numbers has been exhausted, at a cost of $15 per number. 

Additional features 

Plus, here are some improved capabilities to take advantage of: 

• scheduleSend – don't want to send your message right away? Tell us when you want to add it to the queue for sending.  

• replyCallbackUrl – set a replyCallbackUrl to receive replies to your Virtual Number (previously called notifyUrl).  

• retryTimeout – if your message is queued or unable to reach the recipient’s device, you can now tell us how many minutes you want the network to keep trying.