Having trouble creating/renewing a subscription, or sending an SMS/MMS with Telstra’s Messaging API? You’ve come to the right place. I’m Vinodh from the TelstraDev Support team, and I’ve put together this three-step guide to help you troubleshoot common Messaging API issues quickly and easily.
Use this guide to figure out the best next course of action and – if you need to reach out to support – find out which details you should include to help us solve the problem.
Free Trial users:
If you're using the Free Trial, you can only use the default keys on your profile. Any additional keys created for the Messaging API won't work. Check out the video instructions on our blog here for more info. Need further support? Leave us a post in the Messaging API forum.
Companies using a credit card billing method:
If you've signed up to Telstra Dev and selected a credit card as your billing method, you won't be able to use the Messaging API. You will need to sign up and select a Telstra Billing Account as your billing method instead. If you don't have a Telstra Billing Account, request one using the portal here. Need more support? Leave us a post in the Messaging API forum.
Pre-requisites:
Before we start, make sure you have:
- Signed in to your company in TelstraDev (dev.telstra.com) and selected Telstra Billing Account as the default billing method. Note that if you've selected a credit card as the billing method, the Messaging API won't work.
- Installed Postman (with the Telstra Messaging API Postman collections) OR have an equivalent app or command line utility that you can use to interact with the API.
- Got the Keys to the Messaging API. Make sure you're using the production Keys and have switched to your company profile in the top menu bar, Go to Develop > My Apps & Keys and expand the application "Production Keys" (or the application that require troubleshooting).
1. Check your authentications
- Read detailed instructions on authentication for the Messaging API here.
- Get your API Key and Secrets (See Pre-requisites).
- Generate OAuth token. To do this, perform a POST https://tapi.telstra.com/v2/oauth/token in Postman (or your preferred method) using the request body provided in the below example and replacing your Key and Secret.
- An example response is below. If you received this response, you can go straight to the next step. If you didn’t get this response, please e-mail TelstraDev at telstradev@team.telstra.com. If applicable, include the company name you registered with us. Remember: please do not share client secret or client keys via email.
Create Authentication example request:
{
"client_id": “clientIDABCDEFGH”,
"client_secret": “secretxyzabc”,
"grant_type": "client_credentials"
}
Create Authentication example (200 OK) succesful response
{
"access_token": "z3uJa7SFILabcdefghy5YFWN9ql",
"token_type": "Bearer",
"expires_in": "3599"
}
2. Check that you have an active subscription
- Read detailed instructions for creating/renewing a subscription here.
- Check the subscription that's currently associated with your API keys. To do this, run GET https://tapi.telstra.com/v2/messages/provisioning/subscriptions using Postman (Request body is not required).
- If you didn’t get the successful response (see an example below) then your subscription may have expired. Subscriptions have a limited number of "Active Days". After those days have elapsed, you need to create the subscription again (the next step will show you how to do this). If you do so within 90 days, you’ll be assigned the same Virtual Number. If you ran the call more than 90 days after the Active Days expired, you’ll be assigned a new Virtual Number.
- If you don't have an active subscription, or it's about to expire, you can extend your subscription using a POST https://tapi.telstra.com/v2/messages/provisioning/subscriptions. Find instructions on how to do this here. Note: If your subscription is already active, performing a POST create subscription again will not replace your Virtual Number, it will just extend the number of Active Days.
- If you get a successful response from the Create subscription call (i.e. 201 Created) then wait 5 minutes and repeat GET Subscription to confirm that your subscription is now ready to use. Once you get a successful response, it will return your Virtual Number.
- If you didn’t get a successful response, please e-mail TelstraDev (dev.telstra.com) at telstradev@team.telstra.com. Include the above request and response details and any company name registered with us. Remember: do not share your client Key or Secret via email.
Get Subscription example (200 OK) successful response:
{
"destinationAddress": “+61412345678”,
"activeDays": "1824”
}
Create Subscription example request:
(if you are not using the notifyURL feature)
{
"activeDays": 1825
}
OR (if you are using the NotifyURL feature)
{
"activeDays": 1825,
“NotifyURL”: “http://yournotifyurl.com/“
}
Create Subscription Example Response: (201 created)
{
"destinationAddress": "+61412345678”,
"activeDays": “1824”
}
3. See if you can send a message
- Read detailed instructions for creating/renewing a subscription here.
- Using the Send Message Postman Collection, perform POST https://tapi.telstra.com/v2/messages/sms.
- If you didn't get a successful response, or if you did get a successful response but the SMS was not received by your test handset, please e-mail TelstraDev (dev.telstra.com) at telstradev@team.telstra.com. Include the company name you registered with us, and the messageId (optional). Please do not share your client Key or Secret via email.
Send SMS example request:
{
"to”:”+61XXXXXXXXXX”,
"validity":"60",
"priority":false,
"body":"Message text goes here"
}
Send SMS expected response (200 OK):
{
to: '+61XXXXXXXXXX',
deliveryStatus: 'MessageWaiting',
messageId: 'XYZ’,
messageStatusURL: 'https://tapi.telstra.com/v2/messages/sms/XYZ/status'
}
],
Country: [ { AUS: 1 } ],
messageType: 'SMS',
numberSegments: 1
}
By now you should have checked your authentication, confirmed that you have an active subscription to the Messaging API, and successfully sent a message.
If these steps worked for you, or if you found other ways to improve upon them, please let us know in the comments!