telstra / messagingapi-sdk-java

Telstra Messaging SDK - Java Library

TelstraMessaging V3

Send and receive SMS & MMS programmatically, leveraging Australia's leading mobile network. With Telstra's Messaging API, we take out the complexity to allow seamless messaging integration into your app, with just a few lines of code. Our REST API is enterprise grade, allowing you to communicate with engaging SMS & MMS messaging in your web and mobile apps in near real-time on a global scale.

Automatically generated by the Swagger Codegen

Requirements

Building the API client library requires:

1. Java 1.7+
2. Maven/Gradle

Installation

To install the API client library to your local Maven repository, simply execute:

mvn clean install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn clean deploy

Refer to the OSSRH Guide for more information.

Maven users

Please refer to https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry

Please update settings.xml as described above:

  <profiles>
    <profile>
      <id>github</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
        </repository>
        <repository>
          <id>github</id>
          <url>https://maven.pkg.github.com/telstra/MessagingAPI-SDK-Java</url>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <servers>
    <server>
      <id>github</id>
      <username>USERNAME</username>
      <password>TOKEN</password>
    </server>
  </servers>

Add this dependency to your project's POM:

<dependency>
  <groupId>com.telstra.messaging</groupId>
  <artifactId>telstra-messaging</artifactId>
  <version>3.0-SNAPSHOT</version>
</dependency>

Gradle users

Add this dependency to your project's build file:

compile "Telstra:TelstraMessaging:v3"

Others

At first generate the JAR by executing:

mvn clean package

Then manually install the following JARs:

• target/telstra-messaging-3.0-SNAPSHOT.jar
• target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

Documentation for API Endpoints

All URIs are relative to https://products.api.telstra.com/messaging/v3

Class	Method	HTTP request	Description
AuthenticationApi	authToken	POST /oauth/token	Generate an access token
FreeTrialNumbersApi	createTrialNumbers	POST /free-trial-numbers	create free trial number list
FreeTrialNumbersApi	getTrialNumbers	GET /free-trial-numbers	get all free trial numbers
HealthCheckApi	healthCheck	GET /health-check	health check
MessagesApi	deleteMessageById	DELETE /messages/{messageId}	delete a message
MessagesApi	getMessageById	GET /messages/{messageId}	fetch a specific message
MessagesApi	getMessages	GET /messages	fetch all sent/received messages
MessagesApi	sendMessages	POST /messages	send messages
MessagesApi	updateMessageById	PUT /messages/{messageId}	update a message
MessagesApi	updateMessageTags	PATCH /messages/{messageId}	update message tags
ReportsApi	getReport	GET /reports/{reportId}	fetch a specific report
ReportsApi	getReports	GET /reports	fetch all reports
ReportsApi	messagesReport	POST /reports/messages	submit a request for a messages report
VirtualNumbersApi	assignNumber	POST /virtual-numbers	assign a virtual number
VirtualNumbersApi	deleteNumber	DELETE /virtual-numbers/{virtual-number}	delete a virtual number
VirtualNumbersApi	getNumbers	GET /virtual-numbers	fetch all virtual numbers
VirtualNumbersApi	getRecipientOptouts	GET /virtual-numbers/{virtual-number}/optouts	Get recipient optouts list
VirtualNumbersApi	getVirtualNumber	GET /virtual-numbers/{virtual-number}	fetch a virtual number
VirtualNumbersApi	updateNumber	PUT /virtual-numbers/{virtual-number}	update a virtual number

Documentation for Authorization

Authentication schemes defined for the API:

bearer_auth

• Type: OAuth
• Flow: application
• Authorization URL:
• Scopes:
  • free-trial-numbers:read: read information for free trial numbers
  • free-trial-numbers:write: write information for free trial numbers
  • messages:read: read information for messages
  • messages:write: write information for messages
  • reports:read: read information for reports
  • reports:write: write information for reports
  • virtual-numbers:read: read information for virtual-numbers
  • virtual-numbers:write: write information for virtual numbers

import com.telstra.*;
import com.telstra.messaging.AuthenticationApi;
import org.junit.Before;
import org.junit.Test;
import static org.junit.Assert.assertNotNull;

public class AuthenticationApiExample {

    public static void main(String[] args) {
	ApiClient defaultClient = new ApiClient();
        String clientId = "YOUR CLIENT ID";
        String clientSecret = "YOUR CLIENT SECRET";
        String grantType = "client_credentials";
        String scope = "free-trial-numbers:read free-trial-numbers:write messages:read messages:write virtual-numbers:read virtual-numbers:write reports:read reports:write";

        defaultClient.setAccessSecret(clientId, clientSecret, grantType, scope);
        AuthenticationApi authenticationApi = new AuthenticationApi(defaultClient);
        try {
            OAuth oAuthResponse = authenticationApi.authToken(defaultClient.getClientId(), defaultClient.getClientSecret(), defaultClient.getGrantType(), defaultClient.getScope());
            System.out.println("getAuthToken: " + oAuthResponse.getAccessToken());
            assertNotNull(oAuthResponse.getAccessToken());
        } catch (ApiException e) {
            System.err.println("Exception when calling AuthenticationApi#authToken");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Author

Free Trial

Telstra offers a free trial for the messaging API to help you evaluate whether it meets your needs. There are some restrictions that apply compared to the full API, including a maximum number of messages that can be sent and requiring the registration of a limited number of destinations before a message can be sent to that destination. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#FreeTrial.

Registering Free Trial Numbers

ℹ️ Only required for the free trial accounts

Register destinations for the free trial. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#RegisteraFreeTrialNumber.

The function freeTrialNumbers.create can be used to register destinations.

It takes an object with following properties as argument:

• freeTrialNumbers: A list of destinations, expected to be phone numbers of the form 04XXXXXXXX.

It returns the list of phone numbers that have been registered.

For example:

import com.telstra.*;
import com.telstra.messaging.FreeTrialNumbersApi;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.*;


try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
	CreateTrialNumbersRequest createTrialNumbersRequest = new CreateTrialNumbersRequest();
	createTrialNumbersRequest.addFreeTrialNumbersItem("0400000001");
	createTrialNumbersRequest.addFreeTrialNumbersItem("0400000002");

	FreeTrialNumbersApi freeTrialNumbersApi = new FreeTrialNumbersApi(apiClient);
	FreeTrialNumbers response = freeTrialNumbersApi.createTrialNumbers(createTrialNumbersRequest);
	System.out.println(response);
	assertNotNull(response.getFreeTrialNumbers());

} catch (ApiException e) {
	System.err.println("Exception when calling FreeTrialNumbersApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}

Fetch all Free Trial Numbers

ℹ️ Only required for the free trial

Fetch the Free Trial Number(s) currently assigned to your account. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#FetchyourFreeTrialNumbers.

The function freeTrialNumbers.getAll can be used to retrieve registered destinations.

It takes no arguments.

It returns the list of phone numbers that have been registered.

For example:

import com.telstra.*;
import com.telstra.messaging.FreeTrialNumbersApi;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.*;


try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
	FreeTrialNumbersApi freeTrialNumbersApi = new FreeTrialNumbersApi(apiClient);
	FreeTrialNumbers response = freeTrialNumbersApi.getTrialNumbers();
	System.out.println(response);
	assertNotNull(response.getFreeTrialNumbers());

} catch (ApiException e) {
	System.err.println("Exception when calling FreeTrialNumbersApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}

Virtual Number

Gives you a dedicated mobile number tied to an application which enables you to receive replies from your customers. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#VirtualNumbers.

Assign Virtual Number

When a recipient receives your message, you can choose whether they'll see a Virtual Number or senderName (paid plans only) in the from field. If you want to use a Virtual Number, use this function to assign one. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#AssignaVirtualNumber.

The function virtualNumbers.assign can be used to create a subscription.

It takes a object with following properties as argument:

• replyCallbackUrl (optional): The URL that replies to the Virtual Number will be posted to.
• tags (optional): Create your own tags and use them to fetch, sort and report on your Virtual Numbers through our other endpoints. You can assign up to 10 tags per number.

It returns an object with the following properties:

• virtualNumber: The Virtual Number assigned to your account.
• lastUse: The last time the Virtual Number was used to send a message.
• replyCallbackUrl: The URL that replies to the Virtual Number will be posted to.
• tags: Any customisable tags assigned to the Virtual Number.

For example:

import com.telstra.*;
import com.telstra.messaging.VirtualNumbersApi;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	VirtualNumbersApi virtualNumbersApi = new VirtualNumbersApi(apiClient);
	AssignNumberRequest assignNumberRequest = new AssignNumberRequest()
			.replyCallbackUrl("http://www.example.com")
			.addTagsItem("minim qui")
			.addTagsItem("commodo")
			.addTagsItem("nostrud laborum minim")
			.addTagsItem("nulla proident ut voluptat")
			.addTagsItem("et consectetur dolor")
			.addTagsItem("est amet cillum")
			.addTagsItem("exercitation")
			.addTagsItem("non occaecat cupidatat Duis")
			.addTagsItem("adipisicing")
			.addTagsItem("ea aliqua incididunt");
	
	VirtualNumber response = virtualNumbersApi.assignNumber(assignNumberRequest);
	System.out.println(response);
	assertNotNull(response.getVirtualNumber());

} catch (ApiException e) {
	System.err.println("Exception when calling VirtualNumbersApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}

Fetch a Virtual Number

Fetch the tags, replyCallbackUrl and lastUse date for a Virtual Number. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#FetchaVirtualNumber.

The function virtualNumbers.get can be used to get the details of a Virtual Number.

It takes the following arguments:

• virtualNumber: The Virtual Number assigned to your account.

It returns an object with the following properties:

• virtualNumber: The Virtual Number assigned to your account.
• lastUse: The last time the Virtual Number was used to send a message.
• replyCallbackUrl: The URL that replies to the Virtual Number will be posted to.
• tags: Any customisable tags assigned to the Virtual Number.

For example:

import com.telstra.*;
import com.telstra.messaging.VirtualNumbersApi;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	VirtualNumbersApi virtualNumbersApi = new VirtualNumbersApi(apiClient);
	String virtualNumber = "0428180739";
	VirtualNumber response = virtualNumbersApi.getVirtualNumber(virtualNumber);
	System.out.println(response);
	assertNotNull(response.getVirtualNumber());
} catch (ApiException e) {
	System.err.println("Exception when calling VirtualNumbersApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}

Fetch all Virtual Numbers

Fetch all Virtual Numbers currently assigned to your account. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#FetchallVirtualNumbers.

The function virtualNumbers.getAll can be used to get the all virtual numbers associated to your account.

It takes an object with following prperties as argument:

• limit (optional): Tell us how many results you want us to return, up to a maximum of 50.
• offset (optional): Use the offset to navigate between the response results. An offset of 0 will display the first page of results, and so on.
• filter (optional): Filter your Virtual Numbers by tag or by number.

It returns an object with the following properties:

• virtualNumbers: A list of Virtual Numbers assigned to your account.
• paging: Paging information.

For example:

import com.telstra.*;
import com.telstra.messaging.VirtualNumbersApi;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
	VirtualNumbersApi virtualNumbersApi = new VirtualNumbersApi(apiClient);
	Integer limit = null;
	Integer offset = null;
	String filter = null;
	GetNumbers200Response response = virtualNumbersApi.getNumbers(limit, offset, filter);
	System.out.println(response);
	assertNotNull(response.getVirtualNumbers());

} catch (ApiException e) {
	System.err.println("Exception when calling virtualNumbersApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}

Update a Virtual Number

Update a virtual number attributes. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#UpdateaVirtualNumber.

The function virtualNumbers.update can be used to update a virtual number.

It takes an object with following properties as argument:

• virtualNumber: The Virtual Number assigned to your account.
• updateData (optional):
  • reply_callback_url (optional): The URL that replies to the Virtual Number will be posted to.
  • tags (optional): Create your own tags and use them to fetch, sort and report on your Virtual Numbers through our other endpoints. You can assign up to 10 tags per number.

It returns an object with the following properties:

• virtualNumber: The Virtual Number assigned to your account.
• lastUse: The last time the Virtual Number was used to send a message.
• replyCallbackUrl: The URL that replies to the Virtual Number will be posted to.
• tags: Any customisable tags assigned to the Virtual Number.

For example:

import com.telstra.*;
import com.telstra.messaging.VirtualNumbersApi;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	VirtualNumbersApi virtualNumbersApi = new VirtualNumbersApi(apiClient);
	String virtualNumber ="0428180739";
	String replyCallbackUrl = "http://www.example.com";

	UpdateNumberRequest updateNumberRequest = new UpdateNumberRequest()
			.replyCallbackUrl(replyCallbackUrl)
			.addTagsItem("minim qui")
			.addTagsItem("commodo")
			.addTagsItem("exercitation");

	VirtualNumber response = virtualNumbersApi.updateNumber(updateNumberRequest, virtualNumber);
	System.out.println(response);
	assertNotNull(response.getVirtualNumber());
} catch (ApiException e) {
	System.err.println("Exception when calling VirtualNumbersApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}	

Delete Virtual Number

Delete the a virtual number. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#DeleteaVirtualNumber.

The function virtualNumbers.get can be used to unassign a Virtual Number.

It takes the following arguments:

• virtualNumber: The Virtual Number assigned to your account.

It returns nothing.

For example:

import com.telstra.*;
import com.telstra.messaging.VirtualNumbersApi;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	VirtualNumbersApi virtualNumbersApi = new VirtualNumbersApi(apiClient);
	String virtualNumber = "0428180739";
	virtualNumbersApi.deleteNumber(virtualNumber);
} catch (ApiException e) {
	System.err.println("Exception when calling VirtualNumbersApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}

Fetch all Recipient Optouts list

Fetch any mobile number(s) that have opted out of receiving messages from a Virtual Number assigned to your account. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#Fetchallrecipientoptoutslist.

The function telstra.messaging.virtual_number.get_optouts can be used to get the list of mobile numbers that have opted out of receiving messages from a virtual number associated to your account. It takes the following arguments:

• virtual_number: The Virtual Number assigned to your account.
• limit: Tell us how many results you want us to return, up to a maximum of 50.
• offset: Use the offset to navigate between the response results. An offset of 0 will display the first page of results, and so on.

Raises telstra.messaging.exceptions.VirtualNumbersError if anything goes wrong.

It returns an object with the following properties:

• recipient_optouts: A list of recipient optouts.
• paging: Paging information.

For example:

import com.telstra.*;
import com.telstra.messaging.VirtualNumbersApi;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
	VirtualNumbersApi virtualNumbersApi = new VirtualNumbersApi(apiClient);
	Integer limit = null;
	Integer offset = null;
	String virtualNumber = "0428180739";
	GetRecipientOptouts200Response response = virtualNumbersApi.getRecipientOptouts(virtualNumber, limit, offset);
	System.out.println(response);
	assertNotNull(response.getRecipientOptouts());

} catch (ApiException e) {
	System.err.println("Exception when calling virtualNumbersApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}

Message

Send and receive messages. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#Messages.

Send Message

Send a message to a mobile number, or to multiple mobile numbers. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#SendanSMSorMMS.

The function messages.send can be used to send a message.

It takes an object with following properties as argument:

• to: The destination address, expected to be a phone number of the form +614XXXXXXXX or 04XXXXXXXX.
• from: This will be either one of your Virtual Numbers or your senderName.
• messageContent (Either one of messageContent or multimedia is required): The content of the message.
• multimedia (Either one of messageContent or multimedia is required): MMS multimedia content.
• retryTimeout (optional): How many minutes you asked the server to keep trying to send the message.
• scheduleSend (optional): The time (in Central Standard Time) the message is scheduled to send.
• deliveryNotification (optional): If set to true, you will receive a notification to the statusCallbackUrl when your SMS or MMS is delivered (paid feature).
• statusCallbackUrl (optional): The URL the API will call when the status of the message changes.
• tags (optional): Any customisable tags assigned to the message.

The type TMultimediacan be used to build an mms payload. It has following properties:

• type: The content type of the attachment, for example <TMultimediaContentType.IMAGE_GIF>.
• fileName (optional): Optional field, for example image.png.
• payload: The payload of an mms encoded as base64.

It returns an object with the following properties:

• messageId: Use this UUID with our other endpoints to fetch, update or delete the message.
• status: The status will be either queued, sent, delivered or expired.
• to: The recipient's mobile number(s).
• from: This will be either one of your Virtual Numbers or your senderName.
• messageContent: The content of the message.
• multimedia: The multimedia content of the message (MMS only).
• retryTimeout: How many minutes you asked the server to keep trying to send the message.
• scheduleSend: The time (in Central Standard Time) a message is scheduled to send.
• deliveryNotification: If set to true, you will receive a notification to the statusCallbackUrl when your SMS or MMS is delivered (paid feature).
• statusCallbackUrl: The URL the API will call when the status of the message changes.
• tags: Any customisable tags assigned to the message.

For example:

import com.telstra.*;
import com.telstra.messaging.MessagesApi;
import java.util.UUID;
import org.junit.Before;
import org.junit.Test;
import java.util.ArrayList;
import java.util.List;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	MessagesApi messagesApi = new MessagesApi(apiClient);
	String to = "0411220643";
	String from = "0400000004";
	String messageContent = "Hello customer, this is from CBA to confirme your offer!";
	Multimedia multimedia = new Multimedia();
	String type = "image/jpeg";
	String fileName = "image/jpeg";
	String payload =  "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==";
	multimedia.setType(type);
	multimedia.setFileName(fileName);
	multimedia.setPayload(payload);
	List<Multimedia> multimediaList = new ArrayList<>();
	multimediaList.add(multimedia);
	Integer retryTimeout = 10;
	String scheduleSend = "2023-09-11T03:48:47.096Z";
	Boolean deliveryNotification = false;
	String statusCallbackUrl = "http://www.example.com";
	List<String> tagsList = new ArrayList<>();
	tagsList.add("laborum");
	tagsList.add("esse");
	tagsList.add("irure Lorem");
	tagsList.add("dolore aliqu");
	tagsList.add("pariatur do proident magna ut");
	tagsList.add("id sunt");
	tagsList.add("u");
	tagsList.add("tempor velit minim");
	tagsList.add("sit dolo");
	tagsList.add("laborum qui");
    
    	SendMessagesRequest sendMessagesRequest = new SendMessagesRequest()
			.to(to)
			.from(from)
			.messageContent(messageContent)
			.multimedia(multimediaList)
			.retryTimeout(retryTimeout)
			.scheduleSend(scheduleSend)
			.deliveryNotification(deliveryNotification)
			.statusCallbackUrl(statusCallbackUrl)
			.tags(tagsList);
    
	MessageSent response = messagesApi.sendMessages(sendMessagesRequest);
	System.out.println(response);
	assertNotNull(response.getMessageId());

} catch (ApiException e) {
	System.err.println("Exception when calling MessagesApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}	

Get a Message

Use the messageId to fetch a message that's been sent from/to your account within the last 30 days. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#Fetchamessage.

The function messages.get can be used to retrieve the a message.

It takes the following arguments:

• messageId: Unique identifier for the message.

It returns an object with the following properties:

• messageId: Use this UUID with our other endpoints to fetch, update or delete the message.
• status: The status will be either queued, sent, delivered or expired.
• createTimestamp: The time you submitted the message to the queue for sending.
• sentTimestamp: The time the message was sent from the server.
• receivedTimestamp: The time the message was received by the recipient's device.
• to: The recipient's mobile number(s).
• from: This will be either one of your Virtual Numbers or your senderName.
• messageContent: The content of the message.
• multimedia: The multimedia content of the message (MMS only).
• direction: Direction of the message (outgoing or incoming).
• retryTimeout: How many minutes you asked the server to keep trying to send the message.
• scheduleSend: The time (in Central Standard Time) the message is scheduled to send.
• deliveryNotification: If set to true, you will receive a notification to the statusCallbackUrl when your SMS or MMS is delivered (paid feature).
• statusCallbackUrl: The URL the API will call when the status of the message changes.
• queuePriority: The priority assigned to the message.
• tags: Any customisable tags assigned to the message.

For example:

import com.telstra.*;
import com.telstra.messaging.MessagesApi;
import java.util.UUID;
import org.junit.Before;
import org.junit.Test;
import java.util.ArrayList;
import java.util.List;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	MessagesApi messagesApi = new MessagesApi(apiClient);
	UUID messageId = UUID.fromString("3f58be60-4c71-11ee-a5b2-b5976390898d");

	MessageGet response = messagesApi.getMessageById(messageId);
	System.out.println(response);
	assertNotNull(response.getMessageId());
	

} catch (ApiException e) {
	System.err.println("Exception when calling MessagesApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}	

Get all Messages

Fetch messages that have been sent from/to your account in the last 30 days. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#Fetchallsent/receivedmessages.

The function messages.getAll can be used to fetch all messages.

It takes an object with following properties as argument:

• limit (optional): Tell us how many results you want us to return, up to a maximum of 50.
• offset (optional): Use the offset to navigate between the response results. An offset of 0 will display the first page of results, and so on.
• filter (optional): Filter your Virtual Numbers by tag or by number.

It returns an object with the following properties:

• messages: List of all messages.
• paging: Paging information.

For example:

import com.telstra.*;
import com.telstra.messaging.MessagesApi;
import java.util.UUID;
import org.junit.Before;
import org.junit.Test;
import java.util.ArrayList;
import java.util.List;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	MessagesApi messagesApi = new MessagesApi(apiClient);
	Integer limit = null;
	Integer offset = null;
	String direction = null;
	String status = null;
	String filter = null;

	GetMessages200Response response = messagesApi.getMessages(limit, offset, direction, status, filter);
	System.out.println(response);
	assertNotNull(response.getMessages());

} catch (ApiException e) {
	System.err.println("Exception when calling MessagesApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}	

Update a Message

Update a message that's scheduled for sending, you can change any of the below parameters, as long as the message hasn't been sent yet. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#Updateamessage.

The function messages.send can be used to send a message.

It takes an object with following properties as argument:

• messageId: Use this UUID with our other endpoints to fetch, update or delete the message.
• to: The destination address, expected to be a phone number of the form +614XXXXXXXX or 04XXXXXXXX.
• from: This will be either one of your Virtual Numbers or your senderName.
• messageContent (Either one of messageContent or multimedia is required): The content of the message.
• multimedia (Either one of messageContent or multimedia is required): MMS multimedia content.
• retryTimeout (optional): How many minutes you asked the server to keep trying to send the message.
• scheduleSend (optional): The time (in Central Standard Time) the message is scheduled to send.
• deliveryNotification (optional): If set to true, you will receive a notification to the statusCallbackUrl when your SMS or MMS is delivered (paid feature).
• statusCallbackUrl (optional): The URL the API will call when the status of the message changes.
• tags (optional): Any customisable tags assigned to the message.

The type TMultimediacan be used to build an mms payload. It has following properties:

• type: The content type of the attachment, for example <TMultimediaContentType.IMAGE_GIF>.
• fileName (optional): Optional field, for example image.png.
• payload: The payload of an mms encoded as base64.

The dataclass telstra.messaging.message.Multimedia can be used to build a mms payload. It takes the following arguments:

• type: The content type of the attachment, for example image/png.
• filename (optional): Optional field, for example image.png.
• payload: The payload of an mms encoded as base64.

It returns an object with the following properties:

• messageId: Use this UUID with our other endpoints to fetch, update or delete the message.
• status: The status will be either queued, sent, delivered or expired.
• to: The recipient's mobile number(s).
• from: This will be either one of your Virtual Numbers or your senderName.
• messageContent: The content of the message.
• multimedia: The multimedia content of the message (MMS only).
• retryTimeout: How many minutes you asked the server to keep trying to send the message.
• scheduleSend: The time (in Central Standard Time) a message is scheduled to send.
• deliveryNotification: If set to true, you will receive a notification to the statusCallbackUrl when your SMS or MMS is delivered (paid feature).
• statusCallbackUrl: The URL the API will call when the status of the message changes.
• tags: Any customisable tags assigned to the message.

For example:

import com.telstra.*;
import com.telstra.messaging.MessagesApi;
import java.util.UUID;
import org.junit.Before;
import org.junit.Test;
import java.util.ArrayList;
import java.util.List;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	MessagesApi messagesApi = new MessagesApi(apiClient);
	UUID messageId = UUID.fromString("8540d774-4863-4d2b-b788-4ecb19412e85");

	String to = "0400000001";
	String from = "0400000001";
	String messageContent = "Ut veniam in ipsum exercitation";

	Multimedia multimedia = new Multimedia();
	String type = "image/jpeg";
	String fileName = "image/jpeg";
	String payload =  "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==";
	multimedia.setType(type);
	multimedia.setFileName(fileName);
	multimedia.setPayload(payload);
	List<Multimedia> multimediaList = new ArrayList<>();
	multimediaList.add(multimedia);
	Integer retryTimeout = 10;
	String scheduleSend = "2023-09-11T03:48:47.096Z";
	Boolean deliveryNotification = false;
	String statusCallbackUrl = "http://www.example.com";
	List<String> tagsList = new ArrayList<>();
	tagsList.add("laborum");
	tagsList.add("esse");
	tagsList.add("irure Lorem");
	tagsList.add("dolore aliqu");
	tagsList.add("pariatur do proident magna ut");
	tagsList.add("id sunt");
	tagsList.add("u");
	tagsList.add("tempor velit minim");
	tagsList.add("sit dolo");
	tagsList.add("laborum qui");

	UpdateMessageByIdRequest updateMessageByIdRequest = new UpdateMessageByIdRequest()
			.to(to)
			.from(from)
			.messageContent(messageContent)
			.multimedia(multimediaList)
			.retryTimeout(retryTimeout)
			.scheduleSend(scheduleSend)
			.deliveryNotification(deliveryNotification)
			.statusCallbackUrl(statusCallbackUrl)
			.tags(tagsList);

	MessageUpdate response = messagesApi.updateMessageById(updateMessageByIdRequest, messageId);
	System.out.println(response);
	assertEquals(messageId, response.getMessageId());

} catch (ApiException e) {
	System.err.println("Exception when calling MessagesApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}	
	

Update Message Tags

Update message tags, you can update them even after your message has been delivered. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#Updatemessagetags.

The function messages.updateTags can be used to update message tags.

It takes the following arguments:

• messageId: Unique identifier for the message.
• tags (optional): Any customisable tags assigned to the message.

It returns nothing.

For example:

import com.telstra.*;
import com.telstra.messaging.MessagesApi;
import java.util.UUID;
import org.junit.Before;
import org.junit.Test;
import java.util.ArrayList;
import java.util.List;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	MessagesApi messagesApi = new MessagesApi(apiClient);
	UUID messageId = UUID.fromString("8540d774-4863-4d2b-b788-4ecb19412e85");
	UpdateMessageTagsRequest updateMessageTagsRequest = new UpdateMessageTagsRequest();
	updateMessageTagsRequest.addTagsItem("marketing");
	updateMessageTagsRequest.addTagsItem("SMS");

	messagesApi.updateMessageTags(updateMessageTagsRequest, messageId);

} catch (ApiException e) {
	System.err.println("Exception when calling MessagesApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}

Delete a Message

Delete a scheduled message, but hasn't yet sent. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#Deleteamessage.

The function messages.delete can be used to delete a message.

It takes the following arguments:

• messageId: Unique identifier for the message.

It returns nothing.

For example:

import com.telstra.*;
import com.telstra.messaging.MessagesApi;
import java.util.UUID;
import org.junit.Before;
import org.junit.Test;
import java.util.ArrayList;
import java.util.List;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	MessagesApi messagesApi = new MessagesApi(apiClient);
	UUID messageId = UUID.fromString("119be970-4c71-11ee-a651-ad71114ff6eb");

	messagesApi.deleteMessageById(messageId);

} catch (ApiException e) {
	System.err.println("Exception when calling MessagesApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}	

Reports

Create and fetch reports. For more information, please see here: https://dev.telstra.com/content/messaging-api-v3#tag/reports.

Request a Messages Report

Request a CSV report of messages (both incoming and outgoing) that have been sent to/from your account within the last three months. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#Submitarequestforamessagesreport.

The function reports.create can be used to create a report.

It takes the following arguments:

• startDate: Set the time period you want to generate a report for by typing the start date (inclusive) here. Note that we only retain data for three months, so please ensure your startDate is not more than three months old. Use ISO format(yyyy-mm-dd), e.g. "2019-08-24".
• endDate: Type the end date (inclusive) of your reporting period here. Your endDate must be a date in the past, and less than three months from your startDate. Use ISO format(yyyy-mm-dd), e.g. "2019-08-24".
• reportCallbackUrl (optional): The callbackUrl where notification is sent when report is ready for download.
• filter (optional): Filter report messages by: tag - use one of the tags assigned to your message(s) number - either the Virtual Number used to send the message, or the Recipient Number the message was sent to.

It returns an object with the following properties:

• reportId: Use this UUID with our other endpoints to fetch the report.
• reportCallbackUrl: If you provided a reportCallbackUrl in your request, it will be returned here.
• reportStatus: The status of the report. It will be either:
  • queued – the report is in the queue for generation.
  • completed – the report is ready for download.
  • failed – the report failed to generate, please try again.

For example:

import com.telstra.*;
import com.telstra.messaging.ReportsApi;
import java.util.UUID;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
	ReportsApi reportsApi = new ReportsApi(apiClient);
	ReportsMessagesBody reportsMessagesBody = new ReportsMessagesBody().startDate(org.threeten.bp.LocalDate.parse("2023-09-01"))
			.endDate(org.threeten.bp.LocalDate.parse("2023-09-06"))
			.reportCallbackUrl("http://www.example.com");

	GetReports201Response response = reportsApi.messagesReport(reportsMessagesBody);
	System.out.println(response);
	assertNotNull(response.getReportId());

} catch (ApiException e) {
	System.err.println("Exception when calling ReportsApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}

Fetch a specific report

Use the report_id to fetch a download link for a report generated. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#FetchaReport.

The function reports.get can be used to retrieve the a report download link. It takes the following arguments:

• reportId: Unique identifier for the report.

It returns an object with the following properties:

• reportId: Use this UUID with our other endpoints to fetch the report.
• reportStatus: The status of the report.
• reportUrl: Download link to download the CSV file.

For example:

import com.telstra.*;
import com.telstra.messaging.ReportsApi;
import java.util.UUID;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	ReportsApi reportsApi = new ReportsApi(apiClient);
	UUID reportId = UUID.fromString("2be7b580-4c34-11ee-a651-ad71114ff6eb");
	GetReportId200Response response = reportsApi.getReport(reportId);
	System.out.println(response);
	assertNotNull(response.getReportId());
	

} catch (ApiException e) {
	System.err.println("Exception when calling ReportsApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}	

Fetch all reports

Fetch details of all reports recently generated for your account. Use it to check the status of a report, plus fetch the report ID, status, report type and expiry date. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#Fetchallreports.

The function reports.getAll can be used to fetch all reports.

It doesn't take any arguments.

It returns a list of objects with the following properties:

• reportId: Use this UUID with our other endpoints to fetch the report.
• reportStatus: The status of the report.
• reportType: The type of report generated.
• reportExpiry: The expiry date of your report. After this date, you will be unable to download your report.

For example:

import com.telstra.*;
import com.telstra.messaging.ReportsApi;
import java.util.UUID;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	ReportsApi reportsApi = new ReportsApi(apiClient);
	GetReports200Response response = reportsApi.getReports();
	System.out.println(response);
	assertNotNull(response.getReports());

} catch (ApiException e) {
	System.err.println("Exception when calling ReportsApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}	

Health Check

Get operational status of the messaging service

Check the operational status of the messaging service. For more information, please see here: https://dev.telstra.com/docs/messaging-api/apiReference/apiReferenceOverviewEndpoints?version=3.x#HealthCheck.

The function healthCheck.get can be used to get the status.

It takes no arguments.

It returns an object with following properties:

• status: Denotes the status of the services Up/Down.

For example:

import com.telstra.*;
import com.telstra.messaging.HealthCheckApi;
import org.junit.Before;
import org.junit.Test;
import static com.telstra.messaging.AuthenticationApi.getAuthToken;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;

try{
	ApiClient defaultClient = new ApiClient();
	ApiClient apiClient = getAuthToken(defaultClient);
    	HealthCheckApi healthCheckApi = new HealthCheckApi(apiClient);
	HealthCheck200Response response = healthCheckApi.healthCheck();
	System.out.println(response);
	assertNotNull(response);
	assertEquals("up", response.getStatus());

} catch (ApiException e) {
	System.err.println("Exception when calling HealthCheckApi");
	System.err.println("Status code: " + e.getCode());
	System.err.println("Reason: " + e.getResponseBody());
	System.err.println("Response headers: " + e.getResponseHeaders());
	e.printStackTrace();
}