Reach Messaging API - Quickstart - Java

Sending SMS with the Reach Messaging API from TalkyLabs is made possible with just a few lines of Java code.

In what follows, we provide a step-by-step guide to facilitate your debut. In this quickstart, you will learn how to:

Sign-up / Sign-in

You can sign up for an account on the Reach platform here. You will be asked to verify your email address to activate your account.

Create an applet

An applet can be viewed as a subaccount or a development environment within the Reach platform. It allows you to regroup your operations in the Reach platform based on your customer segments, e.g., by country. You can have more than one applet associated with your account.

Creating an applet is just as simple as clicking a button and specifying the applet name as well as the operating country, that is the country where most of the customers targeted by the operations that will be performed under this applet reside.

Retrieve your API credentials

After accessing your applet, you can retrieve your API credentials by visiting Settings -> API from the left side menu.

As you will notice, you will gain access to your API User as well as your Test and Live API Key. Recall that the Test API key is for the sandbox mode where you can emulate sending messages while the Live API key is for sending messages for real.

Finally, note that it is possible to re-generate your API keys as you go.

Verify your phone number

With an applet, you can emulate sending messages in a sandbox mode by using whatever valid phone numbers you want. However, for sending real messages, you can only use phone numbers that you own.

To demonstrate the ownership of a phone number, you need to verify it. Within an applet, visit the section Phone numbers -> Verified numbers from the left side menu to add your number and start a verification process.

Install the client library

You have to make sure you have Java Development Kit (JDK) installed on your computer. This could be checked by running the following command:

javac -version

If it is installed, you would see something like:

javac 11.0.20.1

Our Java client library supports JDK 8+. To manually installed the library, download the source code, unzip it, navigate into the reach-java folder and run

mvn install

This command will generate in the target folder a flat jar whose name looks like reach-1.0.0-jar-with-dependencies.jar. That jar will be used below.

If you prefer, yo can use build tools such as Maven or Gradle. Refer to the client library code source for more details.

Send a message

Now that the Java client library is installed, we can send an SMS using a valid verified number registered in the applet. Create a file name SendMessage.java and paste in it the code sample below.

import com.talkylabs.reach.Reach;
import com.talkylabs.reach.base.ResourceSet;
import com.talkylabs.reach.rest.api.messaging.MessagingItem;

public class SendMessage {

  public static final String API_USER = System.getenv("REACH_TALKYLABS_API_USER");
  public static final String API_KEY = System.getenv("REACH_TALKYLABS_API_KEY");

  public static void main(String[] args) {

    Reach.init(API_USER, API_KEY);

    MessagingItem message = MessagingItem
        .sender(
          "+237671234567", // dest
          "+237691234567", // src 
          "Hello World! This is a sms message."
        )
        .send();

    System.out.println(message.getMessageId());
  }
}

Replace the src phone number with your verified number and the dest phone number with the number you want to send the message to. The phone numbers must be in the E.164 format.

Also, use your API credentials to replace the placeholder values for apiUser and apiKey. Remember to use your Live API key.

Save the file and compile it the following command in your terminal (replace 1.0.0 with the appropriate version number):

javac -cp reach-1.0.0-jar-with-dependencies.jar SendMessage.java

Once the compilation is over, run the resulting class using the command below:

java -cp .:reach-1.0.0-jar-with-dependencies.jar SendMessage

If you are on Windows, use instead this command:

java -cp ".;reach-1.0.0-jar-with-dependencies.jar" SendMessage

That's it! In a few moments, your message will be delivered to the destination phone number.