Set Up a Java Dev Environment for Messaging

This guide shows how to set up a development environment in five minutes to trigger API requests related to our Messaging API. It also shows how to send and receive messages using tunneling software to expose the local dev server to the public internet.

Install Java, Spring, and the Plivo Java SDK

To get started, install Java 1.8 or higher and Plivo’s Java SDK. You probably already have Java installed. In macOS, Linux, or Windows you can check the version by running the command java -version in a terminal window. If you need to update it, download and install it. You should also download and install IntelliJ IDEA.

Install Spring and the Plivo Java SDK using IntelliJ Idea

• Use Spring Initializr to create a boilerplate project with Spring Boot framework.

  

• Add the Spring Web dependency. Give the project a friendly name — we called ours “Plivo SMS” — set the Java target as 11, then click Generate to download the boilerplate code and open it in IntelliJ Idea.

  

• Install the Plivo Java package by adding the dependency in pom.xml

    <dependency>
        <groupId>com.plivo</groupId>
        <artifactId>plivo-java</artifactId>
       <version>5.9.3</version>
    </dependency>
  

  

Trigger an API request

Now you can create a file in the project directory and execute code to trigger any Plivo API. Here’s some example code that sends an SMS message. Edit the PlivoSmsApplication.java file in the src/main/java/com.example.demo/ folder and paste into it this code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
package com.example.demo;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.message.Message;
import com.plivo.api.models.message.MessageCreateResponse;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.io.IOException;
import java.util.Collections;

@SpringBootApplication
@RestController
public class PlivoSmsApplication {


    public static void main(String[] args) {
        SpringApplication.run(PlivoSmsApplication.class, args);
    }

    @GetMapping(value = "/outbound", produces = {"application/json"})
    public MessageCreateResponse sendSMS() throws IOException, PlivoRestException {
        Plivo.init("<auth_id>", "<auth_token>");
        MessageCreateResponse response = Message.creator(
           "<sender_id>", 
           "<destination_number>",
           "Hello, from Spring!").create();
        System.out.println(response);
        return response;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
package com.example.demo;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.message.Message;
import com.plivo.api.models.message.MessageCreateResponse;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.io.IOException;
import java.util.Collections;

@SpringBootApplication
@RestController
public class PlivoSmsApplication {

    public static void main(String[] args) {
        SpringApplication.run(PlivoSmsApplication.class, args);
    }

    @GetMapping(value = "/outbound", produces = {"application/json"})
    public MessageCreateResponse sendMMS() throws IOException, PlivoRestException {
        Plivo.init("<auth_id>", "<auth_token>");
        MessageCreateResponse response = Message.creator(
           "<sender_id>", 
           "<destination_number>",
           "Hello, from Spring!")
           .type(MessageType.MMS)
           .media_urls(new String[]{"https://media.giphy.com/media/26gscSULUcfKU7dHq/source.gif"})
           .media_ids(new String[]{"801c2056-33ab-499c-80ef-58b574a462a2"}).create();
        System.out.println(response);
        return response;
    }
}

Save the file and run it.

You can see your server app in action on http://localhost:8080/outbound/.

You can follow the same approach to trigger other API requests. Refer to our detailed API reference to see all the API requests available on the Messaging API platform.

Set up a Spring web application to serve XML and manage callbacks

Now that we’ve sent a message, let’s set up a Spring application to handle incoming messages.

Plivo supports receiving SMS text messages in several countries (see complete SMS API coverage). When someone sends a text message to a Plivo phone number, you can receive it on your server by setting a Message URL in your Plivo application. Plivo sends the message, along with other parameters, to your Message URL.

Edit the PlivoSmsApplication.java file in the src/main/java/com.example.demo/ folder and paste this code into it after the sendSMS function block.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
package com.example.demo;
import com.plivo.api.exceptions.PlivoRestException;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.io.IOException;

@SpringBootApplication
@RestController
public class PlivoSmsApplication {


    public static void main(String[] args) {
        SpringApplication.run(PlivoSmsApplication.class, args);
    }

    @GetMapping(value = "/outbound", produces = {"application/json"})
    public MessageCreateResponse SendSMS() throws IOException, PlivoRestException {
        ........;
        ........;
    }

    @PostMapping("/incoming")
    public String postBody(String From, String To, String Text) {
        System.out.println(From + " " + To + " " + Text);
		return "Message received!";
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
package com.example.demo;
import com.plivo.api.exceptions.PlivoRestException;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.io.IOException;

@SpringBootApplication
@RestController
public class PlivoSmsApplication {


    public static void main(String[] args) {
        SpringApplication.run(PlivoSmsApplication.class, args);
    }

    @GetMapping(value = "/outbound", produces = {"application/json"})
    public MessageCreateResponse SendSMS() throws IOException, PlivoRestException {
        ........;
        ........;
    }

    @PostMapping("/incoming")
    public String postBody(String From, String To, String Text, String Media0) {
        System.out.println(From + " " + To + " " + Text + " " + Media0);
		return "Message received!";
    }

}

Also update the import declaration section.

Run the project and you should see your basic server app in action on http://localhost:8080/incoming/.

Ngrok setup

To serve XML documents, your local server must connect with Plivo API services. For that, we recommend using ngrok, which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server.

Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive messages (80 in this case):

./ngrok http 80

This starts the ngrok server on your local server.

Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. You should be able to see your basic server application in action at https://<nrgok_URL>/inbound/.

Now people can send messages to your Plivo number.

You can follow the same approach to serve other XML documents to manage call flows. Refer to our detailed XML reference to see all the XML elements available on the Messaging API platform.