Migration FAQs 

When can I use v2 until?  

Messaging API v2 will be decommissioned in August 2024. During the transition period, you'll still be able to use v2 to send messages while we work to migrate our customers over. At the end of this transition period, however, any app integration with v2 will break. 

If you've already migrated to v3 during this period, you don't need to do anything further – you can continue using Messaging API v3. 

If for any reason you no longer wish to continue trialing v3 and opt to remain with v2, any v3 configurations – including changes made to Virtual Numbers and callbackUrls – will be removed.  

Authenticating and getting started 

Can I use my Messaging API v2 keys to authenticate in v3?  

No, you will need to generate a new client_id and client_secret to authenticate. Sign in to your Telstra Developer account to create your new v3 keys. Click on 'My Account' on the right-hand side of the homepage, then select 'API Keys'. Next, click the blue 'Create API Key' button at the top of the screen. Give your API key a name and select the required expiry date, then tick the selection box beside 'Messaging API v3' to create your v3 keys. 

Alternatively, if you want us to add v3 to your existing v2 keys, then email us the first four characters of your client_id.    

How do I send a message with Messaging v3?  

Read our Getting Started guide for step-by-step instructions on how to send your first message. Now, you can also use our new, web-based API Explorer[LINK] to send a message code-free.  

What SDKs are available in v3?  

We currently provide an SDK in Python.

Sending a message 

Can I still use an alphanumeric identifier to send messages? What is a senderName? 

An alphanumeric identifier is known as a senderName in v3. To send a message from a senderName (instead of a Virtual Number or privateNumber) simply include the name in the 'from' field.   

What is a Recipient Number?  

A Recipient Number was called a destinationAddress in v2. Recipient Numbers are the mobile phone numbers you want to send a message to. 

Do I need to register BNums?  

No, you can start sending messages right away in v3. 

How do I send an MMS in v3?  

Text and multimedia are sent from the one endpoint in v3. Use POST /messages and the multimedia parameter to send an MMS. Include a JSON payload with the file type, file name and your base64 encoded multimedia content. 

Can I set a deliveryWindow in v3?   

If you don't want to send your message right away, you can use the scheduleSend parameter (previously called deliveryWindow) to tell us when you want to add it to the queue for sending.  

What is retryTimeout?  

If your message is queued or unable to reach the recipient's device, you can use retryTimeout (previously called validity) to tell us how many minutes you want the network to keep trying.  

How does a recipient opt out of receiving messages from my Virtual Number?  

A recipient can opt out of receiving messages from a Virtual Number by replying with one of these English-language keywords: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END or QUIT. When the API receives an opt-out keyword from a recipient, the recipient is added to your recipient optouts list and you will no longer be able to message them from that Virtual Number.  

How do I know if a recipient has opted out of receiving messages?  

Call GET /recipient-optouts to fetch a list of your recipient optouts. 

Can messageIDs assigned in v2 be used in v3?  

No, messageIds assigned in v2 cannot be used in v3, and vice versa.  

Can I use a userMsgRef in v3?  

The userMsgRef feature has been replaced by tags in v3. You can assign up to 10 customisable tags per message or Virtual Number. 

Virtual Numbers / Subscriptions 

What are Virtual Numbers?  

A Virtual Number, previously called a Subscription, is the Australian mobile number your recipient will see in the "from" field when you send a message. You can assign a Virtual Number to your account using POST /virtual-numbers.  

Can I use my v2 Subscriptions / Virtual Numbers to send messages in v3?  

Yes, when you move to v3 any existing Subscriptions (now called Virtual Numbers) assigned to your account will travel with you. You can continue using them to send and receive messages in v3. Note: You will not be able to send/receive messages in V2 after August 2024. There will be more correspondence to impacted customers later in the year.  If you need more information, please contact telstradev@team.telstra.com

How much are Virtual Numbers?  

Your first five Virtual Numbers created in v3 are free, and any v2 numbers that you migrate over to v3 will not count towards this quota. A cost per Virtual Number applies thereafter for v3 virtual numbers. See our pricing page for more.  

Do I need a Virtual Number / Subscription?  

No, you don't need a Virtual Number to send a message in v3. You can send your message from a private number or Sender Name instead.   

Do Virtual Numbers expire?  

Virtual Numbers that have not been used to send a message in 3 months (Free Trial) or 24 months (paid plans) will be automatically unassigned from your account. Check the lastUse date of your Virtual Number using GET /virtual-numbers/{virtual-number}. 

Callback URLs – delivery notifications, status updates and replies 

I'm using a notifyUrl in v2. Can I use the same URL for callbacks in v3?  

Callbacks for replies and status notifications will trigger separately in v3 and v2. That means if you're currently using a notifyUrl to trigger reply callbacks in v2 and you use the same URL to trigger reply callbacks in v3, you will receive duplicate notifications. You can handle this duplication in your production code, or you can use the v3 endpoint PUT /virtual-numbers/{virtual-number} to update your replyCallbackUrl. V3 replies will then send to a new replyCallbackUrl, while v2 replies will send to the original notifyUrl. 

How do I trigger delivery receipt, status updates and reply callbacks? 

Please use the new v3 parameters (replyCallbackUrl and statusCalbackUrl) instead of notifyUrl to trigger callbacks.  

How do I trigger delivery notifications in v3?  

Set deliveryNotification to TRUE and supply a statusCallbackUrl (note: this is a paid feature).  

What is a replyCallbackUrl?  

This is the URL the API will send replies to. Previously you posted this notifyUrl using POST / messages/provisioning/subscriptions. In v3, send it as the replyCallbackUrl in POST /virtual-number.   

What is a statusCallbackUrl?  

This is the URL the API will call when the status of your message changes or – if you've set deliveryNotification to true – the URL the API will call when your message has been successfully delivered to the recipient's device.  

Billing 

What are the pricing differences between v2 and v3?  

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

Visit our pricing page for full details.  

How will I be billed for v3?  

To keep things simple, you'll receive one combined bill for both versions after you migrate.  

Is there a charge for receiving messages in v3?  

No, you will not be charged for receiving incoming messages.