Too many customer communication channels, too little time? Simplify communication and start sending your customer’s SMS with ClickSend via a convenient web app or API.
Deliver alerts, reminders, marketing campaigns, surveys and account updates to customers — without sacrificing customer experience and engagement. You might attract a few customers along the way too.
In this article, you’ll learn how to:
- Set up your Java Spring Boot Application
- Install and configure the ApiClient
- Add SMS contact lists to your ClickSend account
- Send text messages in Java with the Send SMS Endpoint
- Send bulk messages in Java using the SMS Campaign API Endpoint
Skip ahead: Use ClickSend API’s official Java library.
Tutorial: send SMS with Java using Spring Boot
💡What’s Spring Boot? Java Spring Boot is a tool that speeds up and simplifies developing web applications and microservices with Java Spring Framework.
To send SMS in Java, you will first:
- Set up a Java Spring Boot application
- Install and configure ClickSend SMS
- Create a contact list in the dashboard
Then send SMS in Java using either the ‘Send SMS’ Endpoint or the ‘SMS Campaigns’ Endpoint.
What’s the difference?
The Send SMS Endpoint allows you to send up to 1,000 messages with each API call, to a mix of individual contacts and/or contact lists. It also returns a detailed response message.
Using the SMS Campaigns Endpoint, you can send SMS to up to 20,000 contacts on a single contact list with each API call, and the response message is less detailed.
Send SMS in Java – a few prerequisites
To follow along with this tutorial, you’ll need to have the following:
- A ClickSend account, which you can create for free.
- A local Java development environment setup.
- Postman, which you’ll use to test the features.
Set up your Java Spring Boot application
To set up a Spring Boot application, you can use the Spring Initializr here, which has a Spring Boot demo project metadata, Spring Web dependency, and uses the Maven build tool. Click “Generate”, then import the project into an IDE.
After importing the project into your IDE, open ‘pom.xml’ to add the ClickSend Java API Java library Maven dependency.
Update the ‘pom.xml’ file with the dependency below:
<dependency>
<groupId>com.github.clicksend</groupId>
<artifactId>clicksend-java-client</artifactId>
<version>1.0.0</version>
<scope>compile</scope>
</dependency>
Next, you’ll configure the ClickSend ApiClient, which is the Java native client for ClickSend, to enable the use of ClickSend throughout your application.
Install and configure the ApiClient
To configure the ClickSend ApiClient, you’ll need ClickSend API Credentials. To get the API Credentials, log into your ClickSend dashboard, and click the key symbol in the top right corner.
After clicking the key symbol, you will see a pop-up with your account’s username and API key.
To safely store the API Credentials, create two environment variables in the ‘application.properties’ file of the Spring Boot application:
clickSend-username=<Your_ClickSend_Username>
clickSend-apiKey=<Your_ClickSend_ApiKey>To use these environment variables to configure ClickSend, in ‘BroadcastSmsApiWithClicksendApplication.java`, the main application class of the application, create two ‘private’ variables that will inject the values of the environment variables with the ‘@Value’ annotation:
@Value("${clickSend-username}")
private String clickSendUsername;
@Value("${clickSend-apiKey}")
private String clickSendApiKey;To configure ClickSend, create a bean method with ‘@bean’ annotation, then make the bean single scope by adding the ‘@Scope’ annotation. ‘@Scope’ Creates a single instance of the bean configuration and caches it, so all requests for the bean will return the same object.
@Bean
@Scope(value = ConfigurableBeanFactory.SCOPE_SINGLETON)
public ApiClient clickSendConfig() {
ApiClient clickSendApiClient = new ApiClient();
clickSendApiClient.setUsername(clickSendUsername);
clickSendApiClient.setPassword(clickSendApiKey);
return clickSendApiClient;
}
The above method configures the API credentials and then returns the instantiation of the ClickSend API Client.
Now, you can use the ClickSend API Client anywhere in the Spring Boot application, and you’re ready to send text messages with Java.
Add SMS contacts to your ClickSend account
There are two ways you can add contacts to ClickSend—through the ClickSend Dashboard or programmatically via the Contact and Contact List endpoints.
Add contacts in the Dashboard
To add numbers via the ClickSend dashboard, click on contacts in the left-hand sidebar, as highlighted in the image below.
You’ll be taken to the contacts screen, shown in the previous image. Click the plus sign next to “Lists”, create a name for your contact list, then click Add to create the contact list.
You’ll then be taken to the contacts page. To start adding contacts, click on the image of the person with the label “Click here to start adding your contacts”.
After you click to start adding contacts, ClickSend will present you with options to add, import, or sync your contacts, as shown in the GIF below.
To add contacts, you’ll manually fill in the respective fields; the import option allows you to import an Excel or CSV file. The sync option enables syncing from tools such as Google Contacts, Salesforce, or Zoho.
For this tutorial, you will import from a CSV file. Here is a sample CSV file you can use. After downloading the sample CSV file, upload it, and click IMPORT.
Please note that because this file is for demo purposes, the sample CSV file contains only two contacts.
After importing the CSV file, ClickSend will ask you to select the columns you want to add to your contact list. For this tutorial, you’ll just need to select phone, first_name, and last_name.
Scroll down, and click on CONFIRM to complete the import.
Take note of the digits at the end of the URL, highlighted in the image above. Those numbers are the ‘list_id’ that you will use to tell the Java application the particular list to send messages. If you create a contact list programmatically, you will get a response with the ‘list_id’.
With your contacts imported, you can now use ClickSend’s Send SMS Endpoint to implement an endpoint that can send messages to up to a thousand numbers at once.
Send text messages in Java with the Send SMS Endpoint
The Send SMS endpoint allows you to contact up to 1,000 numbers at once. After sending the message, you will get a detailed response containing information about if the message was delivered, as well as information about the user, and status or error codes that resulted from the delivery.
To start, in the Spring Boot application, create two packages:
- ‘model’: This package will hold the model of message details for the POST request body.
- ‘api’: This package will contain the REST endpoints that will implement the sending of messages.
In the ‘model’ package, create a class ‘MessageDetails’ to model the SMS:
package com.example.broadcastSMSapiwithclicksend.model;
/**
* `messageBody` stores the SMS message,
* `listId` stores the contact `list_id`,
* `sendingSource` indicates the method of sending the message, and
* `smsCampaignName` is used when sending a large volume of messages.
*/
public class MessageDetails {
private String messageBody;
private int listId;
private String sendingSource;
private String smsCampaignName;
public MessageDetails() {
}
public String getMessageBody() {
return messageBody;
}
public void setMessageBody(String messageBody) {
this.messageBody = messageBody;
}
public int getListId() {
return listId;
}
public void setListId(int listId) {
this.listId = listId;
}
public String getSendingSource() {
return sendingSource;
}
public void setSendingSource(String sendingSource) {
this.sendingSource = sendingSource;
}
public String getSmsCampaignName() {
return smsCampaignName;
}
public void setSmsCampaignName(String smsCampaignName) {
this.smsCampaignName = smsCampaignName;
}
}
In the ‘api’ package, create a new class ‘BroadcastSMSRestController’ and in the file called ‘BroadcastSMSRestController.java’, create an ‘ApiClient’ variable that instantiates your ClickSend configuration from the @bean method you created earlier.
@RestController
public class BroadcastSMSRestController {
@Autowired
private ApiClient clickSendConfig;
}
In the above code snippet:
- The class annotates ‘@RestController’ to tell Spring that the class is to build a REST API.
- The ‘ApiClient’ variable has an ‘@Autowired’ annotation to allow Spring to resolve and inject the ‘@bean’ method in the Spring bean.
To start sending messages through the Send SMS endpoint, add the following method to the ‘BroadcastSMSRestController’ class:
@PostMapping("/api/sms1000")
public ResponseEntity<String> sendSMStoUpto1000Numbers(@RequestBody MessageDetails messageDetails) {
SmsApi smsApi = new SmsApi(clickSendConfig);
SmsMessage smsMessage = new SmsMessage();
smsMessage.body(messageDetails.getMessageBody());
smsMessage.listId(messageDetails.getListId());
smsMessage.source(messageDetails.getSendingSource());
List<SmsMessage> smsMessageList = List.of(smsMessage);
// SmsMessageCollection | SmsMessageCollection model
SmsMessageCollection smsMessages = new SmsMessageCollection();
smsMessages.messages(smsMessageList);
try {
String result = smsApi.smsSendPost(smsMessages);
return new ResponseEntity<>(result, HttpStatus.OK);
} catch (ApiException e) {
e.printStackTrace();
}
return new ResponseEntity<>("Exception when calling SmsApi#smsSendPost", HttpStatus.BAD_REQUEST);
}
The above code:
- Has a POST endpoint of ‘/api/sms1000’, to which you will send requests.
- Takes a JSON request body of the ‘MessageDetails’.
- Creates an instance of ClickSend ‘SmsApi’ with the ‘clickSendConfig’.
- The instance ‘SmsMessage’ builds the message with the data from the ‘MessageDetails’ JSON request body.
- Then adds each message for each number in the contact list to a collection.
- In the ‘try-catch’ block, it sends the message with the instance of the ‘SmsApi’ and returns the response, also catching any error that might occur.
Testing the Send SMS Endpoint
To test the endpoint, open Postman and make a POST request to ‘http://localhost:8080/api/sms1000’ endpoint with this JSON body:
{
"messageBody": "Hey (First Name) This is a test message",
"listId": "<your_list_id>",
"sendingSource": "Java Application"
}
The above JSON request body has a placeholder of ‘First Name’, which will include the first name of the contact you imported. See the test screenshot below.
Our Java SMS API has more functionality, and the ‘SmsMessage’ can take more properties, such as ‘schedule’, which allows you to schedule a message for a specific time. To learn about them, check out our Send SMS in Java documentation.
Send bulk messages in Java using the SMS Campaign API Endpoint
The ClickSend Send SMS Endpoint allows you to send messages to up to a thousand contacts at once.
To message more contacts, you’ll need to use the ClickSend SMS Campaign Endpoint provided in the Java API SMS library. The SMS Campaign Endpoint allows you to send messages to up to 20,000 numbers at once. Note, the response from the SMS Campaign Endpoint is less detailed than what you receive from the Send SMS Endpoint.
For the code, you will still use the ‘MessageDetails’ you created earlier and write a REST endpoint in the ‘BroadcastSMSRestController’ class.
In the ‘BroadcastSMSRestController’ class, below the ‘sendSMStoUpto1000Numbers’ method, add the following method:
@PostMapping("/api/sms20000")
public ResponseEntity<String> sendSMSupTo20000Numbers(@RequestBody MessageDetails messageDetails) {
SmsCampaignApi smsCampaignApi = new SmsCampaignApi(clickSendConfig);
SmsCampaign campaign = new SmsCampaign(); // SmsCampaign | SmsCampaign model
campaign.listId(messageDetails.getListId());
campaign.name(messageDetails.getSmsCampaignName());
campaign.body(messageDetails.getMessageBody());
try {
String response = smsCampaignApi.smsCampaignsSendPost(campaign);
return new ResponseEntity<>(response, HttpStatus.OK);
} catch (ApiException e) {
e.printStackTrace();
}
return new ResponseEntity<>("Exception when calling SmsCampaignApi#smsCampaignsSendPost", HttpStatus.BAD_REQUEST);
}
The above code does almost the same thing as the code used for the ‘sendSMStoUpto1000Numbers’ method. The only significant change is that it uses the ‘SmsCampaignApi’ to send the SMS, and ‘SmsCampaign’ to build the details of the SMS.
Testing the SMS Campaign Endpoint
To test the endpoint, open Postman and make a POST request to ‘http://localhost:8080/api/sms20000’ with this JSON body:
{
"messageBody": "Hey, This is a Marketing test message",
"listId": "<your_list_id>",
"sendingSource": "Java Application",
"smsCampaignName": "Marketing message"
}
To learn more about the ‘SmsCampaignApi’, check out our Java API documentation.
You’re ready to send text messages in Java
If you followed each step, congratulations — you just learnt to send SMS from your Java Spring Boot Application.
For a better look at the complete code of each endpoint, you can fork and clone the repo on GitHub. Or, click straight through to our Java API SMS documentation.
