diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a273733..28af5078 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,14 @@ # Change Log -## [5.42.0](https://github.com/plivo/plivo-java/tree/v5.42.0) (2024-05-09) +## [5.43.0](https://github.com/plivo/plivo-java/tree/v5.43.0) (2024-05-31) **Feature - Number Masking Feature Added** - Number Masking APIs added to create, update, delete and list sessions +## [5.42.0](https://github.com/plivo/plivo-java/tree/v5.42.0) (2024-05-20) +**Feature - Adding support for location whatsapp messages** +- Added new param `location` to [send message API](https://www.plivo.com/docs/sms/api/message#send-a-message) to support location `whatsapp` messages +- Added new param `location` in templates to support location based templated messages + ## [5.41.0](https://github.com/plivo/plivo-java/tree/v5.41.0) (2024-05-07) **Feature - Adding support for interactive whatsapp messages** - Added new param `interactive` to [send message API](https://www.plivo.com/docs/sms/api/message#send-a-message) to support interactive `whatsapp` messages diff --git a/README.md b/README.md index c6c7d568..a450d67c 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The Plivo Java SDK makes it simpler to integrate communications into your Java a ### To Install Stable release -You can use this SDK by adding it as a dependency in your dependency management tool. Alternatively, you can use the [JAR file](https://search.maven.org/remotecontent?filepath=com/plivo/plivo-java/5.42.0/plivo-java-5.42.0.jar). +You can use this SDK by adding it as a dependency in your dependency management tool. Alternatively, you can use the [JAR file](https://search.maven.org/remotecontent?filepath=com/plivo/plivo-java/5.43.0/plivo-java-5.43.0.jar). If you are using Maven, use the following XML to include the Plivo SDK as a dependency. @@ -19,13 +19,13 @@ If you are using Maven, use the following XML to include the Plivo SDK as a depe com.plivo plivo-java - 5.42.0 + 5.43.0 ``` If you are using Gradle, use the following line in your dependencies. ``` -compile 'com.plivo:plivo-java:5.42.0' +compile 'com.plivo:plivo-java:5.43.0' ``` ### To Install Beta release @@ -206,6 +206,369 @@ class Example { } ``` +## WhatsApp Messaging +Plivo's WhatsApp API allows you to send different types of messages over WhatsApp, including templated messages, free form messages and interactive messages. Below are some examples on how to use the Plivo Go SDK to send these types of messages. + +### Templated Messages +Templated messages are a crucial to your WhatsApp messaging experience, as businesses can only initiate WhatsApp conversation with their customers using templated messages. + +WhatsApp templates support 4 components: `header` , `body`, `footer` and `button`. At the point of sending messages, the template object you see in the code acts as a way to pass the dynamic values within these components. `header` can accomodate `text` or `media` (images, video, documents) content. `body` can accomodate text content. `button` can support dynamic values in a `url` button or to specify a developer-defined payload which will be returned when the WhatsApp user clicks on the `quick_reply` button. `footer` cannot have any dynamic variables. + +Example 1: +```java +import java.io.IOException; +import java.net.URL; +import java.util.Collections; + +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 com.plivo.api.models.message.MessageType; +import com.fasterxml.jackson.databind.ObjectMapper; + +class Test +{ + public static void main(String [] args) + { + Plivo.init("", ""); + try { + String templateJson = "{\"name\":\"plivo_movieticket_confirmation\",\"language\":\"en_US\",\"components\":[{\"type\":\"header\",\"parameters\":[{\"type\":\"media\",\"media\":\"https://media.geeksforgeeks.org/wp-content/uploads/20190712220639/ybearoutput-300x225.png\"}]},{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"Harry Potter\"},{\"type\":\"text\",\"text\":\"06:00 PM\"},{\"type\":\"text\",\"text\":\"Bengaluru\"},{\"type\":\"text\",\"text\":\"2\"}]}]}"; + + MessageCreateResponse response = Message.creator("+14156667778","+14156667777").type(MessageType.WHATSAPP).template_json_string(templateJson).create(); + ObjectMapper ow = new ObjectMapper(); + String json_output = ow.writeValueAsString(response); + System.out.println(json_output); + } + catch (PlivoRestException | IOException e) { + e.printStackTrace(); + } + } +} +``` + +Example 2: +```java +import java.io.IOException; +import java.net.URL; +import java.util.Collections; + +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 com.plivo.api.models.message.MessageType; +import com.fasterxml.jackson.databind.ObjectMapper; + +class Test +{ + public static void main(String [] args) + { + Plivo.init("", ""); + try { + Template template = new Template(); + template.setName("plivo_movieticket_confirmation"); + template.setLanguage("en_US"); + + List components = new ArrayList<>(); + Component headerComponent = new Component(); + headerComponent.setType("header"); + List headerParameters = new ArrayList<>(); + Parameter headerMediaParameter = new Parameter(); + headerMediaParameter.setType("media"); + headerMediaParameter.setMedia("https://media.geeksforgeeks.org/wp-content/uploads/20190712220639/ybearoutput-300x225.png"); + headerParameters.add(headerMediaParameter); + + headerComponent.setParameters(headerParameters); + components.add(headerComponent); + + Component bodyComponent = new Component(); + bodyComponent.setType("body"); + List bodyParameters = new ArrayList<>(); + Parameter bodyTextParameter1 = new Parameter(); + bodyTextParameter1.setType("text"); + bodyTextParameter1.setText("Harry Potter"); + bodyParameters.add(bodyTextParameter1); + + Parameter bodyTextParameter2 = new Parameter(); + bodyTextParameter2.setType("text"); + bodyTextParameter2.setText("06:00 PM"); + bodyParameters.add(bodyTextParameter2); + + Parameter bodyTextParameter3 = new Parameter(); + bodyTextParameter3.setType("text"); + bodyTextParameter3.setText("Bengaluru"); + bodyParameters.add(bodyTextParameter3); + + Parameter bodyTextParameter4 = new Parameter(); + bodyTextParameter4.setType("text"); + bodyTextParameter4.setText("2"); + bodyParameters.add(bodyTextParameter4); + + bodyComponent.setParameters(bodyParameters); + components.add(bodyComponent); + + template.setComponents(components) + MessageCreateResponse response = Message.creator("+14156667778","+14156667777").type(MessageType.WHATSAPP).template(template).create(); + ObjectMapper ow = new ObjectMapper(); + String json_output = ow.writeValueAsString(response); + System.out.println(json_output); + } + catch (PlivoRestException | IOException e) { + e.printStackTrace(); + } + } +} +``` +> Note: It is also possible to create and manage objects directly within the SDK for whatsapp, providing a structured approach to message creation. + +### Free Form Messages +Non-templated or Free Form WhatsApp messages can be sent as a reply to a user-initiated conversation (Service conversation) or if there is an existing ongoing conversation created previously by sending a templated WhatsApp message. + +#### Free Form Text Message +Example: +```java +import java.io.IOException; +import java.net.URL; +import java.util.Collections; + +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 com.plivo.api.models.message.MessageType; + +class Test +{ + public static void main(String [] args) + { + Plivo.init("", ""); + try { + MessageCreateResponse response = Message.creator("+14156667778","+14156667777","Hey! This is a sample Text.").type(MessageType.WHATSAPP).create(); + System.out.println(response); + } + catch (PlivoRestException | IOException e) { + e.printStackTrace(); + } + } +} + +``` + +#### Free Form Media Message +Example: +```java +import java.io.IOException; +import java.net.URL; +import java.util.Collections; + +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 com.plivo.api.models.message.MessageType; + +class Test +{ + public static void main(String [] args) + { + Plivo.init("", ""); + String[] media = {"https://sample-videos.com/img/Sample-png-image-1mb.png"}; + try { + MessageCreateResponse response = Message.creator("+14156667778","+14156667777","WA -text").log(false).type(MessageType.WHATSAPP).media_urls(media).create() + System.out.println(response); + } + catch (PlivoRestException | IOException e) { + e.printStackTrace(); + } + } +} + +``` + +### Interactive Messages +This guide shows how to send non-templated interactive messages to recipients using Plivo’s APIs. + +#### Quick Reply Buttons +Quick reply buttons allow customers to quickly respond to your message with predefined options. + +Example: +```java +import java.io.IOException; +import java.net.URL; +import java.util.Collections; + +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 com.plivo.api.models.message.MessageType; +import com.fasterxml.jackson.databind.ObjectMapper; + +class Test +{ + public static void main(String [] args) + { + Plivo.init("", ""); + try { + String interactiveJson = "{\"type\":\"button\",\"header\":{\"type\":\"media\",\"media\":\"https://media.geeksforgeeks.org/wp-content/uploads/20190712220639/ybearoutput-300x225.png\"},\"body\":{\"text\":\"Make your selection\"},\"action\":{\"buttons\":[{\"title\":\"Click here\",\"id\":\"bt1j1k2j\"},{\"title\":\"Know More\",\"id\":\"bt1j1k2jkjk\"},{\"title\":\"Request Callback\",\"id\":\"bt1j1kfd2jkjk\"}]}}"; + + MessageCreateResponse response = Message.creator("+14156667778","+14156667777").type(MessageType.WHATSAPP).interactive_json_string(interactiveJson).create(); + ObjectMapper ow = new ObjectMapper(); + String json_output = ow.writeValueAsString(response); + System.out.println(json_output); + } + catch (PlivoRestException | IOException e) { + e.printStackTrace(); + } + } +} +``` + +#### Interactive Lists +Interactive lists allow you to present customers with a list of options. + +Example: +```java +import java.io.IOException; +import java.net.URL; +import java.util.Collections; + +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 com.plivo.api.models.message.MessageType; +import com.fasterxml.jackson.databind.ObjectMapper; + +class Test +{ + public static void main(String [] args) + { + Plivo.init("", ""); + try { + String interactiveJson = "{\"type\":\"list\",\"header\":{\"type\":\"text\",\"text\":\"Welcome to Plivo\"},\"body\":{\"text\":\"You can review the list of rewards we offer\"},\"footer\":{\"text\":\"Yours Truly\"},\"action\":{\"buttons\":[{\"title\":\"Clickhere\"}],\"sections\":[{\"title\":\"SECTION_1_TITLE\",\"rows\":[{\"id\":\"SECTION_1_ROW_1_ID\",\"title\":\"SECTION_1_ROW_1_TITLE\",\"description\":\"SECTION_1_ROW_1_DESCRIPTION\"},{\"id\":\"SECTION_1_ROW_2_ID\",\"title\":\"SECTION_1_ROW_2_TITLE\",\"description\":\"SECTION_1_ROW_2_DESCRIPTION\"}]},{\"title\":\"SECTION_2_TITLE\",\"rows\":[{\"id\":\"SECTION_2_ROW_1_ID\",\"title\":\"SECTION_2_ROW_1_TITLE\",\"description\":\"SECTION_2_ROW_1_DESCRIPTION\"},{\"id\":\"SECTION_2_ROW_2_ID\",\"title\":\"SECTION_2_ROW_2_TITLE\",\"description\":\"SECTION_2_ROW_2_DESCRIPTION\"}]}]}}"; + + MessageCreateResponse response = Message.creator("+14156667778","+14156667777").type(MessageType.WHATSAPP).interactive_json_string(interactiveJson).create(); + ObjectMapper ow = new ObjectMapper(); + String json_output = ow.writeValueAsString(response); + System.out.println(json_output); + } + catch (PlivoRestException | IOException e) { + e.printStackTrace(); + } + } +} +``` + +#### Interactive CTA URLs +CTA URL messages allow you to send links and call-to-action buttons. + +Example: +```java +import java.io.IOException; +import java.net.URL; +import java.util.Collections; + +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 com.plivo.api.models.message.MessageType; +import com.fasterxml.jackson.databind.ObjectMapper; + +class Test +{ + public static void main(String [] args) + { + Plivo.init("", ""); + try { + String interactiveJson = "{\"type\":\"cta_url\",\"header\":{\"type\":\"media\",\"media\":\"https://media.geeksforgeeks.org/wp-content/uploads/20190712220639/ybearoutput-300x225.png\"},\"body\":{\"text\":\"Know More\"},\"footer\":{\"text\":\"Plivo\"},\"action\":{\"buttons\":[{\"title\":\"Click here\",\"cta_url\":\"https:plivo.com\"}]}}"; + + MessageCreateResponse response = Message.creator("+14156667778","+14156667777").type(MessageType.WHATSAPP).interactive_json_string(interactiveJson).create(); + ObjectMapper ow = new ObjectMapper(); + String json_output = ow.writeValueAsString(response); + System.out.println(json_output); + + } + catch (PlivoRestException | IOException e) { + e.printStackTrace(); + } + } +} +``` + +### Location Messages +This guide shows how to send templated and non-templated location messages to recipients using Plivo’s APIs. + +#### Templated Location Messages +Example: +```java +import java.io.IOException; +import java.net.URL; +import java.util.Collections; + +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 com.plivo.api.models.message.MessageType; +import com.fasterxml.jackson.databind.ObjectMapper; + +class Test +{ + public static void main(String [] args) + { + Plivo.init("", ""); + try { + String templateJson = "{\"name\":\"plivo_order_pickup\",\"language\":\"en_US\",\"components\":[{\"type\":\"header\",\"parameters\":[{\"type\":\"location\",\"location\":{\"longitude\":\"122.148981\",\"latitude\":\"37.483307\",\"name\":\"PabloMorales\",\"address\":\"1HackerWay,MenloPark,CA94025\"}}]},{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"Harry\"}]}]}"; + + MessageCreateResponse response = Message.creator("+14156667778","+14156667777").type(MessageType.WHATSAPP).template_json_string(templateJson).create(); + ObjectMapper ow = new ObjectMapper(); + String json_output = ow.writeValueAsString(response); + System.out.println(json_output); + } + catch (PlivoRestException | IOException e) { + e.printStackTrace(); + } + } +} +``` + +#### Non-Templated Location Messages +Example: +```java +import java.io.IOException; +import java.net.URL; +import java.util.Collections; + +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 com.plivo.api.models.message.MessageType; +import com.fasterxml.jackson.databind.ObjectMapper; + +class Test +{ + public static void main(String [] args) + { + Plivo.init("", ""); + try { + String locationJson = "{\"longitude\":\"122.148981\",\"latitude\":\"37.483307\",\"name\":\"PabloMorales\",\"address\":\"1HackerWay,MenloPark,CA94025\"}"; + + MessageCreateResponse response = Message.creator("+14156667778","+14156667777").type(MessageType.WHATSAPP).location_json_string(locationJson).create(); + ObjectMapper ow = new ObjectMapper(); + String json_output = ow.writeValueAsString(response); + System.out.println(json_output); + } + catch (PlivoRestException | IOException e) { + e.printStackTrace(); + } + } +} +``` + ### More examples More examples are available [here](https://github.com/plivo/plivo-examples-java). Also refer to the [guides for configuring the Java Spring to run various scenarios](https://plivo.com/docs/sms/quickstart/java-spring/) & use it to test out your integration in under 5 minutes. diff --git a/pom.properties b/pom.properties index 868c5bbf..7a04779c 100644 --- a/pom.properties +++ b/pom.properties @@ -1,6 +1,6 @@ # Written manually. -version=5.42.0 +version=5.43.0 groupId=com.plivo artifactId=plivo-java diff --git a/pom.xml b/pom.xml index ddffd16f..e8c6dd24 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ 4.0.0 com.plivo plivo-java - 5.42.0 + 5.43.0 plivo-java A Java SDK to make voice calls & send SMS using Plivo and to generate Plivo XML diff --git a/src/main/java/com/plivo/api/models/message/Location.java b/src/main/java/com/plivo/api/models/message/Location.java new file mode 100644 index 00000000..e7635486 --- /dev/null +++ b/src/main/java/com/plivo/api/models/message/Location.java @@ -0,0 +1,43 @@ +package com.plivo.api.models.message; + +public class Location { + private String latitude; + private String longitude; + private String name; + private String address; + + public Location() { + } + + public String getLatitude() { + return latitude; + } + + public void setLatitude(String latitude) { + this.latitude = latitude; + } + + public String getLongitude() { + return longitude; + } + + public void setLongitude(String longitude) { + this.longitude = longitude; + } + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public String getAddress() { + return address; + } + + public void setAddress(String address) { + this.address = address; + } +} diff --git a/src/main/java/com/plivo/api/models/message/MessageCreator.java b/src/main/java/com/plivo/api/models/message/MessageCreator.java index 555e72b6..226d541f 100644 --- a/src/main/java/com/plivo/api/models/message/MessageCreator.java +++ b/src/main/java/com/plivo/api/models/message/MessageCreator.java @@ -39,6 +39,8 @@ public class MessageCreator extends Creator < MessageCreateResponse > { private Template template; @JsonProperty("interactive") private Interactive interactive; + @JsonProperty("location") + private Location location; /** * @param source The phone number that will be shown as the sender ID. @@ -261,12 +263,6 @@ public MessageCreator dlt_template_category(final String dlt_template_category) * @param template_json_string This is the template passed as a json string in the whatsapp message request. */ public MessageCreator template_json_string(final String template_json_string) { - if (this.type == null) { - this.type = MessageType.WHATSAPP; - } else { - if (this.type.equals(MessageType.SMS) || (this.type.equals(MessageType.MMS))) - throw new IllegalArgumentException("type parameter should be whatsapp"); - } if (Utils.allNotNull(this.template)) { throw new IllegalArgumentException("template parameter is already set"); } @@ -291,12 +287,6 @@ public MessageCreator template_json_string(final String template_json_string) { * @param temp This is the template passed as a template object in the whatsapp message request. */ public MessageCreator template(final Template temp) { - if (this.type == null) { - this.type = MessageType.WHATSAPP; - } else { - if (this.type.equals(MessageType.SMS) || (this.type.equals(MessageType.MMS))) - throw new IllegalArgumentException("type parameter should be whatsapp"); - } if (Utils.allNotNull(this.template)) { throw new IllegalArgumentException("template parameter is already set"); } @@ -316,12 +306,6 @@ public MessageCreator template(final Template temp) { * @param intractv This is the interactive messages passed as a interactive object in the whatsapp message request. */ public MessageCreator interactive(final Interactive intractv) { - if (this.type == null) { - this.type = MessageType.WHATSAPP; - } else { - if (type.equals(MessageType.SMS) || (type.equals(MessageType.MMS))) - throw new IllegalArgumentException("type parameter should be whatsapp"); - } if (Utils.allNotNull(this.interactive)) { throw new IllegalArgumentException("interacitve parameter is already set"); } @@ -334,12 +318,6 @@ public MessageCreator interactive(final Interactive intractv) { * @param interactive_json_string This is the interactive message passed as a json string in the whatsapp message request. */ public MessageCreator interactive_json_string(final String interactive_json_string) { - if (this.type == null) { - this.type = MessageType.WHATSAPP; - } else { - if (this.type.equals(MessageType.SMS) || (this.type.equals(MessageType.MMS))) - throw new IllegalArgumentException("type parameter should be whatsapp"); - } if (Utils.allNotNull(this.interactive)) { throw new IllegalArgumentException("interactive parameter is already set"); } @@ -354,6 +332,38 @@ public MessageCreator interactive_json_string(final String interactive_json_stri return this; } + /** + * @param location_json_string This is the location passed as a json string in the whatsapp message request. + */ + public MessageCreator location_json_string(final String location_json_string) { + if (Utils.allNotNull(this.location)) { + throw new IllegalArgumentException("location parameter is already set"); + } + try { + ObjectMapper objectMapper = new ObjectMapper(); + Location loc = objectMapper.readValue(location_json_string, Location.class); + this.location = loc; + } catch (Exception e) { + e.printStackTrace(); + throw new IllegalArgumentException("failed to read location"); + } + return this; + } + + /** + * @param loc This is the location passed as a location object in the whatsapp message request. + */ + public MessageCreator location(final Location loc) { + if (Utils.allNotNull(this.location)) { + throw new IllegalArgumentException("location parameter is already set"); + } + this.location = loc; + + return this; + } + + + @Override protected Call < MessageCreateResponse > obtainCall() { return client().getApiService().messageSend(client().getAuthId(), this); diff --git a/src/main/java/com/plivo/api/models/message/Parameter.java b/src/main/java/com/plivo/api/models/message/Parameter.java index 25704c9f..42a659e3 100644 --- a/src/main/java/com/plivo/api/models/message/Parameter.java +++ b/src/main/java/com/plivo/api/models/message/Parameter.java @@ -10,6 +10,7 @@ public class Parameter { private String payload; private Currency currency; private DateTime date_time; + private Location location; public Parameter() { } @@ -62,4 +63,12 @@ public void setDate_time(DateTime date_time) { this.date_time = date_time; } + public Location getLocation() { + return location; + } + + public void setLocation(Location location) { + this.location = location; + } + } \ No newline at end of file diff --git a/src/main/resources/com/plivo/api/version.txt b/src/main/resources/com/plivo/api/version.txt index 67194d8f..48a2a164 100644 --- a/src/main/resources/com/plivo/api/version.txt +++ b/src/main/resources/com/plivo/api/version.txt @@ -1 +1 @@ -5.41.0 \ No newline at end of file +5.43.0 \ No newline at end of file