{"id":5313,"date":"2023-01-30T14:46:31","date_gmt":"2023-01-30T13:46:31","guid":{"rendered":"https:\/\/www.smsapi.com\/blog\/?p=5313"},"modified":"2024-01-29T14:48:06","modified_gmt":"2024-01-29T13:48:06","slug":"java-sms-guide-2023","status":"publish","type":"post","link":"https:\/\/www.smsapi.com\/blog\/java-sms-guide-2023\/","title":{"rendered":"Java SMS message library (2023 guide with code examples)"},"content":{"rendered":"\n<p><strong><strong>Here&#8217;s your go-to guide for Java SMS messaging. Introducing SMS API Java Library, along with code snippets, step-by-step instructions, and an explanation of the most common errors.<\/strong><\/strong><\/p>\n\n\n\n<!--more-->\n\n\n\n<h2 class=\"wp-block-heading\">Sending SMS Messages in Java: Practical Tips and Techniques<\/h2>\n\n\n\n<p>Sending text messages using Java is an essential feature for many applications. And this article provides practical insights and techniques on how to so. Discover the best practices for integrating SMS functionality into your Java applications, including handling message templates, managing recipient lists, and ensuring message delivery. Whether you&#8217;re building a messaging app or enhancing user communication, these tips will help you streamline the process.<\/p>\n\n\n\n<p>For many years, Java has reigned as one of the most common programming languages in the world. SMSAPI meets this trend by providing a ready-made Java library for handling SMS messaging. So if your programs are written in this language, read on!<\/p>\n\n\n\n<p>As with all other <a rel=\"noreferrer noopener\" href=\"https:\/\/www.smsapi.com\/en\/sms-api\" target=\"_blank\">SMS API<\/a> libraries, this one is publicly available on&nbsp;<a rel=\"noreferrer noopener nofollow\" href=\"https:\/\/github.com\/smsapi\/smsapi-java-client\" target=\"_blank\">GitHub<\/a>. View the source code there. This, of course, is the surest source of information on its functions and capabilities. In this guide, however, I\u2019ll discuss the Java library in a much friendlier manner so that creating a Java application is simpler than making yourself a coffee. Let&#8217;s go!<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Installing the library for handling SMS capabilities in Java<\/h2>\n\n\n\n<p>First, attach the Java library files to your project. You can automate this using the Maven tool. All you need to add in the POM configuration file is one element to the repository and dependencies lists.<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>&lt;repositories&gt;\n\t&lt;repository&gt;\n\t\t&lt;releases&gt;\n\t\t\t&lt;enabled&gt;true&lt;\/enabled&gt;\n\t\t\t&lt;updatePolicy&gt;always&lt;\/updatePolicy&gt;\n\t\t\t&lt;checksumPolicy&gt;fail&lt;\/checksumPolicy&gt;\n\t\t&lt;\/releases&gt;\n\t\t&lt;id&gt;smsapi&lt;\/id&gt;\n\t\t&lt;name&gt;smsapi&lt;\/name&gt;\n\t\t&lt;url&gt;https:\/\/labs.smsapi.com\/maven\/&lt;\/url&gt;\n\t\t&lt;layout&gt;default&lt;\/layout&gt;\n\t&lt;\/repository&gt;\n&lt;\/repositories&gt;\n\n&lt;dependencies&gt;\n\t&lt;dependency&gt;\n\t\t&lt;groupId&gt;com.smsapi&lt;\/groupId&gt;\n\t\t&lt;artifactId&gt;smsapi-lib&lt;\/artifactId&gt;\n\t\t&lt;version&gt;2.5&lt;\/version&gt;\n\t&lt;\/dependency&gt;\n&lt;\/dependencies&gt;<\/code><\/pre>\n\n\n\n<p>On the&nbsp;<a rel=\"noreferrer noopener\" href=\"https:\/\/labs.smsapi.com\/maven\/pl\/smsapi\/smsapi-lib\/\" target=\"_blank\">SMSAPI server<\/a>,&nbsp;you\u2019ll find library versions from 1.1 all the way up to 2.5. These contain JAR archives with the source code, compiled byte code, detailed documentation generated by Javadoc, and the POM files.<\/p>\n\n\n\n<p>If you chose the Gradle tool to manage your app\u2019s development, then using the SMSAPI library in Java will be just as easy. Apply the Java plugins and their libraries to the build.gradle file:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>plugins {\n\tid 'java'\n\tid 'java-library'\n}<\/code><\/pre>\n\n\n\n<p>Include the SMSAPI library in the repositories:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>repositories {\n\tmavenCentral()\n\tmaven {\n\t\turl 'https:\/\/labs.smsapi.com\/maven\/'\n\t}\n}<\/code><\/pre>\n\n\n\n<p>The last thing to do is to import Java library in the right version, depending on your project:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>dependencies {\n\tapi 'com.smsapi:smsapi-lib:2.5'\n}<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Send an SMS using Java application: configuration<\/h2>\n\n\n\n<p>Before you begin the coding, there\u2019s one more essential thing you need to do: set up access to SMS API. Create a trial account. It&#8217;s free and comes with a free SMS quota for tests. Or log in to yours.<\/p>\n\n\n\n<div class=\"wp-block-smsapi-blog-2021-infobox infobox infobox--attention post-content--full-width\"><div class=\"infobox__icon\"><img decoding=\"async\" src=\"data:image\/svg+xml;base64,PHN2ZyB3aWR0aD0iMTAwJSIgaGVpZ2h0PSIxMDAlIiB2aWV3Qm94PSIwIDAgMTAgMTYiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgY2xpcC1ydWxlPSJldmVub2RkIiB4bWw6c3BhY2U9InByZXNlcnZlIiB2ZXJzaW9uPSIxLjEiPgogIDxwYXRoIGlkPSJzdmdfMSIgc3R5bGU9ImZpbGw6IHJnYigxNywgMTkyLCAxMjgpOyBmaWxsLXJ1bGU6IG5vbnplcm87IiBkPSJtMi45MTk2NCwwbDQsMGwwLDRsLTEsN2wtMiwwbC0xLC03bDAsLTR6Ii8+CiAgPHBhdGggaWQ9InN2Z18yIiBzdHlsZT0iZmlsbDogcmdiKDE3LCAxOTIsIDEyOCk7IGZpbGwtcnVsZTogbm9uemVybzsiIGQ9Im03LjAwODM3LDE0YzAsMS4xMDUgLTAuODk1LDIgLTIsMmMtMS4xMDUsMCAtMiwtMC44OTUgLTIsLTJjMCwtMS4xMDUgMC44OTUsLTIgMiwtMmMxLjEwNSwwIDIsMC44OTUgMiwyeiIvPgo8L3N2Zz4K\"\/><\/div><div class=\"infobox__title\"><h4>Test SMSAPI<\/h4><\/div><div class=\"infobox__content\">\n<p>Are you looking for a professional SMS gateway for your Java applications? You are in the right place! Test our messaging service, open and well-documented SMS API and start sending SMS messages to many countries.<\/p>\n\n\n\n<div class=\"wp-block-buttons is-content-justification-center is-layout-flex wp-container-core-buttons-is-layout-16018d1d wp-block-buttons-is-layout-flex\">\n<div class=\"wp-block-button is-style-primary\"><a class=\"wp-block-button__link wp-element-button\" href=\"https:\/\/www.smsapi.com\/en\/signup\" target=\"_blank\" rel=\"noreferrer noopener\">Test SMSAPI<\/a><\/div>\n<\/div>\n<\/div><\/div>\n\n\n\n<p>This will allow us to start working together.&nbsp;The <a rel=\"noreferrer noopener\" href=\"https:\/\/ssl.smsapi.com\/\" target=\"_blank\">Customer Portal<\/a>&nbsp;is a&nbsp;graphical interface with which you can manually handle your entire&nbsp;<a rel=\"noreferrer noopener\" href=\"https:\/\/www.smsapi.com\/en\/sms-campaigns\" target=\"_blank\">SMS campaigns<\/a>. Our Portal has tons of productive functions, i.e., sending messages, receiving incoming communication, <a rel=\"noreferrer noopener\" href=\"https:\/\/www.smsapi.com\/blog\/hlr-lookup-check-number\/\" target=\"_blank\">HLR lookup<\/a> and more. You will find there the account settings, MMS messages sending, recipient database and sendername management, as well as other options. Go through the SMSAPI Do It Yourself guide if you&#8217;d like to know the Portal inside out.<\/p>\n\n\n\n<figure class=\"wp-block-embed is-type-wp-embed is-provider-smsapi-blog wp-block-embed-smsapi-blog\"><div class=\"wp-block-embed__wrapper\">\n<blockquote class=\"wp-embedded-content\" data-secret=\"seGyzmu26w\"><a href=\"https:\/\/www.smsapi.com\/blog\/do-it-yourself-customer-portal-walkthrough\/\">Do it yourself #01 &#8211; Customer Portal Walkthrough (video tutorial)<\/a><\/blockquote><iframe loading=\"lazy\" class=\"wp-embedded-content\" sandbox=\"allow-scripts\" security=\"restricted\" style=\"position: absolute; clip: rect(1px, 1px, 1px, 1px);\" title=\"&#8220;Do it yourself #01 &#8211; Customer Portal Walkthrough (video tutorial)&#8221; &#8212; SMSAPI Blog\" src=\"https:\/\/www.smsapi.com\/blog\/do-it-yourself-customer-portal-walkthrough\/embed\/#?secret=kav6hFXbs5#?secret=seGyzmu26w\" data-secret=\"seGyzmu26w\" width=\"600\" height=\"338\" frameborder=\"0\" marginwidth=\"0\" marginheight=\"0\" scrolling=\"no\"><\/iframe>\n<\/div><\/figure>\n\n\n\n<p class=\"language-java\">The <strong>API is a RESTfull gateway<\/strong> that allows you to post messages, find out their state and much more. To communicate with server you will send HTTP requests using HTTP methods: POST, GET, PUT and DELETE. Send HTTP GET reqyest to contacts endpoint to find out what contacts you already have collected, for example. In the library code, they are handled using the <code>Proxy<\/code> package via the <code>Client<\/code> interface. It is the library\u2019s backstage of sorts, you don\u2019t need to learn it in too much detail.<\/p>\n\n\n\n<p>To establish a secure connection with SMS and MMS messages gateway, you need a&nbsp;40-character API <a rel=\"noreferrer noopener\" href=\"https:\/\/ssl.smsapi.com\/react\/oauth\/manage\" target=\"_blank\">OAuth2 token<\/a>. Setting up a client looks something like this:&nbsp;<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>import com.smsapi.OAuthClient;\nimport com.smsapi.proxy.Proxy;\nimport com.smsapi.proxy.ProxyNative;\n\nclass Main{\n\tpublic static void main(String&#91;] args){\n\t\tString token = \"%SMSAPI_ACCESS_TOKEN%\";\n\t\tvar client = new OAuthClient(token);\n\t\tvar proxy = new ProxyNative(\"https:\/\/api.smsapi.pl\/\");\n\t}\n}<\/code><\/pre>\n\n\n\n<p>As you can see, a server connection also requires a proxy object. It routes all requests to https:\/\/api.smsapi.com\/ domain. However, you can skip an overt generation of the proxy. It will then be created by default, connecting to the api.smsapi.pl service.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Time to send SMS, Java-style!<\/h2>\n\n\n\n<p>Time for the real stuff! Our library relies on factories and actions to send text messages. The former corresponds to individual functions, allowing you to set their parameters.<\/p>\n\n\n\n<p class=\"language-java\">Every action should begin with creating the factory and end with calling the&nbsp;<code>execute()<\/code>&nbsp;function from the base Java class. Of course, once a factory is created, you can later use it as often as you want. To expand the previous listing with simple SMS sending (a proxy is created by default):<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>import com.smsapi.OAuthClient;\nimport com.smsapi.api.SmsFactory;\nimport com.smsapi.api.action.sms.SMSSend;\n\nclass Main{\npublic static void main(String&#91;] args){\n\tvar client = new OAuthClient(\"%SMSAPI_ACCESS_TOKEN%\");\n\n\tvar smsFactory = new SmsFactory(client);\n\tvar actionSmsSend = smsFactory.actionSend(\"+32111222333\", \"Hello world!\");\n\tactionSmsSend.execute();\n}\n}<\/code><\/pre>\n\n\n\n<p>It can be useful to chain-link methods from action classes. The fragment below works the same way:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>var smsFactory = new SmsFactory(client);\nsmsFactory.actionSend()\n\t.setTo(\"+32111222333\")\n\t.setText(\"Hello world!\")\n\t.execute();<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">The Java library: bulk sending SMS messages<\/h2>\n\n\n\n<p class=\"language-java\">Performing&nbsp;<a rel=\"noreferrer noopener\" href=\"https:\/\/www.smsapi.com\/en\/bulk-sms\" target=\"_blank\">bulk SMS sending<\/a> wouldn\u2019t be possible without the ability to send messages to multiple recipients at the same time. The <code>SmsFactory<\/code>&nbsp;factory makes it very simple thanks to overloading the&nbsp;<code>actionSend<\/code>&nbsp;and&nbsp;<code>setTo<\/code> methods:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>SendStatusResponse response = smsFactory.actionSend(\n\t\tnew String&#91;]{\"+32111222333\", \"+32444555666\"},\n\t\t\"Hello receivers!\")\n\t\t.execute();\n\nSendStatusResponse response = smsFactory.actionSend()\n\t\t.setTo(new String&#91;]{\"+32111222333\", \"+32444555666\"})\n\t\t.setText(\"Hello again receivers!\")\n\t\t.execute();<\/code><\/pre>\n\n\n\n<p>That&#8217;s not all, though. In the Customer Portal, you\u2019ll notice that recipients can be joined into groups. Sending identical&nbsp;<a rel=\"noreferrer noopener\" href=\"https:\/\/www.smsapi.com\/en\/sms-notifications\" target=\"_blank\">SMS notifications<\/a>&nbsp;to all group members is very simple:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>SendStatusResponse response = smsFactory.actionSend()\n\t\t.setGroup(\"Group_name\")\n\t\t.setText(\"Hello group!\")\n\t\t.execute();<\/code><\/pre>\n\n\n\n<p class=\"language-java\">The above listings retain the object returned by the <code>execute()<\/code> method. In this case, it is the&nbsp;<code>SendStatusResponse<\/code> class. It has the following methods:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li class=\"language-java\"><code>getParts()<\/code>&nbsp;\u2013 returns the number of parts that an SMS has been divided into. Content longer than 160 characters might require splitting into two or three SMS text messages.<\/li>\n\n\n\n<li class=\"language-java\"><code>getCount()<\/code>&nbsp;\u2013 returns the number of messages queued to be sent.<\/li>\n\n\n\n<li class=\"language-java\"><code>getList()<\/code>&nbsp;\u2013 returns a list (ArrayList) of objects of class&nbsp;MessageResponse. Its methods, in turn, return information on individual SMS sent. These are:\n<ul class=\"wp-block-list\">\n<li><code>getId()<\/code>&nbsp;\u2013 a unique text message identifier in the system.<\/li>\n\n\n\n<li><code>getPoints()<\/code>&nbsp;\u2013 message cost expressed in points deducted from your account.<\/li>\n\n\n\n<li><code>getNumber()<\/code>&nbsp;\u2013 recipient&#8217;s mobile phone number.<\/li>\n\n\n\n<li><code>getStatus()<\/code>&nbsp;\u2013 one of the&nbsp;<a href=\"https:\/\/www.smsapi.com\/docs\/#17-delivery-statuses\" target=\"_blank\" rel=\"noreferrer noopener\">delivery statuses<\/a>.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Scheduling SMS in Java project<\/h2>\n\n\n\n<p>There are a few more practical functions of the library that are worth a&nbsp;mention. The first is <strong>scheduling SMS<\/strong> using Java methods. The right date and time when a notification is delivered to your clients are crucial to elicit the right reaction. How? Check out the article below.<\/p>\n\n\n\n<figure class=\"wp-block-embed is-type-wp-embed is-provider-smsapi-blog wp-block-embed-smsapi-blog\"><div class=\"wp-block-embed__wrapper\">\n<blockquote class=\"wp-embedded-content\" data-secret=\"Ycbw08RYRw\"><a href=\"https:\/\/www.smsapi.com\/blog\/how-to-schedule-sms-campaign\/\">How to Schedule an SMS Campaign Online?<\/a><\/blockquote><iframe loading=\"lazy\" class=\"wp-embedded-content\" sandbox=\"allow-scripts\" security=\"restricted\" style=\"position: absolute; clip: rect(1px, 1px, 1px, 1px);\" title=\"&#8220;How to Schedule an SMS Campaign Online?&#8221; &#8212; SMSAPI Blog\" src=\"https:\/\/www.smsapi.com\/blog\/how-to-schedule-sms-campaign\/embed\/#?secret=ZGBlhyLWND#?secret=Ycbw08RYRw\" data-secret=\"Ycbw08RYRw\" width=\"600\" height=\"338\" frameborder=\"0\" marginwidth=\"0\" marginheight=\"0\" scrolling=\"no\"><\/iframe>\n<\/div><\/figure>\n\n\n\n<p class=\"language-java\">You can easily set the time in your code using the setDateSent methods from the&nbsp;<code>SMSSend<\/code> action. They accept either&nbsp;<code>Calendar<\/code> object or a number of seconds from the start of the epoch. This example sets the messages to be sent on 21 January 2023 at 12:00 p.m.<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>import java.util.GregorianCalendar;\n\nvar sendDate = new GregorianCalendar(2023, 0, 1, 12, 0);\nSendStatusResponse response = smsFactory.actionSend()\n\t.setTo(\"+328111222333\")\n\t.setText(\"Hello in the future!\")\n\t.setDateSent(sendDate)\n\t.execute();<\/code><\/pre>\n\n\n\n<p>In the example below, on the other hand, provided phone number will <a href=\"https:\/\/www.smsapi.com\/blog\/receiving-sms-online-developer-guide\/\" target=\"_blank\" rel=\"noreferrer noopener\">receive SMS message<\/a> in an hour:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>import java.util.Date;\n\nvar sendDate = new Date().getTime()\/1000 + 3600;\nSendStatusResponse response = smsFactory.actionSend()\n\t.setTo(\"+32111222333\")\n\t.setText(\"Hello in the future!\")\n\t.setDateSent(sendDate)\n\t.execute();<\/code><\/pre>\n\n\n\n<p class=\"language-java\">Using this method, you can set the date up to 3 months ahead. If you change your plans during this time, remove the SMS from the schedule using the&nbsp;<code>SMSDelete<\/code> action. To do it, you need the previously-mentioned unique ID of a scheduled SMS. This looks, for example, as follows:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>String smsIdToDelete = response.getList().get(0).getId()\nsmsFactory.actionDelete(smsIdToDelete).execute();<\/code><\/pre>\n\n\n\n<p class=\"language-java\">From the object of class&nbsp;<code>SendStatusResponse<\/code>&nbsp;you take the list of SMS sent, and from the list, you get the zero elements, and from that, you get the ID. With a&nbsp;method from the actionDelete&nbsp;the factory, you create an action, provide a&nbsp;parameter for it right away, and execute it.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Java: send SMS messages that make an impact<\/h2>\n\n\n\n<p>Unique, engaging content is paramount. The library provides two simple tools to make your SMS marketing and notifications stand out.<\/p>\n\n\n\n<p>One is the SMS sendername (or SMS branding) &#8211; a basic and free-of-charge function of the <a href=\"https:\/\/www.smsapi.com\/blog\/sms-gateway-starting-guide\/\" target=\"_blank\" rel=\"noreferrer noopener\">SMS gateway<\/a>. It is a short text displayed on the mobile phone screen instead of a phone number. The name should somehow identify your company, brand or product so that a person can tell at a glance who\u2019s texting them. Request yours in the Customer Portal, but remember we do check each one and spam and scam messaging are not allowed.<\/p>\n\n\n\n<figure class=\"wp-block-embed is-type-wp-embed is-provider-smsapi-blog wp-block-embed-smsapi-blog\"><div class=\"wp-block-embed__wrapper\">\n<blockquote class=\"wp-embedded-content\" data-secret=\"DPyfJR8Kk1\"><a href=\"https:\/\/www.smsapi.com\/blog\/sender-id-how-to-send-branded-sms-company-name\/\">Sender ID \u2013 How to Send Branded SMS Messages with the Company Name Instead of a Number?<\/a><\/blockquote><iframe loading=\"lazy\" class=\"wp-embedded-content\" sandbox=\"allow-scripts\" security=\"restricted\" style=\"position: absolute; clip: rect(1px, 1px, 1px, 1px);\" title=\"&#8220;Sender ID \u2013 How to Send Branded SMS Messages with the Company Name Instead of a Number?&#8221; &#8212; SMSAPI Blog\" src=\"https:\/\/www.smsapi.com\/blog\/sender-id-how-to-send-branded-sms-company-name\/embed\/#?secret=0bKYIdWeJM#?secret=DPyfJR8Kk1\" data-secret=\"DPyfJR8Kk1\" width=\"600\" height=\"338\" frameborder=\"0\" marginwidth=\"0\" marginheight=\"0\" scrolling=\"no\"><\/iframe>\n<\/div><\/figure>\n\n\n\n<p class=\"language-java\">This method of drawing the recipient\u2019s attention is simple but useful in&nbsp;<a rel=\"noreferrer noopener\" href=\"https:\/\/www.smsapi.com\/en\/sms-marketing\" target=\"_blank\">SMS marketing<\/a>. SMS sender names can be managed manually using the relevant section of the Customer Portal. In the code, you can use an existing name using a method from the <code>SMSSend<\/code> action to send SMS with unique sender id:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>smsFactory.actionSend()\n\t.setTo(\"+32111222333\")\n\t.setText(\"Hello world!\")\n\t.setSender(\"sender_name\")\n\t.execute();<\/code><\/pre>\n\n\n\n<p>The other method is <strong>message parametrisation<\/strong>. Special character strings in the SMS text allow you to&nbsp;<a href=\"https:\/\/www.smsapi.com\/en\/personalization\" target=\"_blank\" rel=\"noreferrer noopener\">customise bulk-sent messages<\/a>. The SMS system will fill messages with data corresponding to the phone numbers.<\/p>\n\n\n\n<p>This way, they won\u2019t be identical but will address the recipients more individually. You use four custom names and the name values from the contact database. They are described in detail in the&nbsp;<a rel=\"noreferrer noopener\" href=\"https:\/\/www.smsapi.com\/docs\/#3-bulk-sms\" target=\"_blank\">Documentation<\/a>. Let\u2019s take a look at an example:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>smsFactory.actionSend()\n\t.setTo(new String&#91;]{\"+32111222333\", \"+32444555666\"})\n\t.setText(\"Hello &#91;%first_name%], your number is &#91;%1%]!\")\n\t.setParam(0, new String&#91;]{\"11\", \"22\"})\n\t.execute();<\/code><\/pre>\n\n\n\n<p>The texts of all (two) SMS will be modified twice. The [%first_name%] names will be replaced with the corresponding values from the contact database.<\/p>\n\n\n\n<p class=\"language-java\">The&nbsp;<code>setParam<\/code>&nbsp;method provides the replacement for name [%1%]. Its first argument is the parameter index, the second is an array of strings inserted into consecutive messages instead of the special strings. There are four such custom parameters available: [%1%], [%2%], [%3%], and [%4%], corresponding to indexes 0, 1, 2, 3.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Handling SMS sender names in the SMSAPI Java library<\/h3>\n\n\n\n<p class=\"language-java\">As I\u2019ve mentioned above, it\u2019s worth using the SMS sendername feature. On the program side, they are handled by&nbsp;<code>SenderFactory<\/code>&nbsp;and action classes:&nbsp;<code>SenderList<\/code>,&nbsp;<code>SenderAdd<\/code>,&nbsp;<code>SenderDefault<\/code>,&nbsp;<code>SenderDelete<\/code>.<\/p>\n\n\n\n<p>The example below shows how to call a list of existing SMS sendernames, add a new name, set it as default and delete it. I assume that a client object (which the factory needs) has already been set up.<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>var senderNameFactory = new SenderFactory(client);\nSendersResponse response = senderNameFactory.actionList().execute();\nfor (SenderResponse elem: response.getList()){\n\tSystem.out.println(\n\t\t\"Sender name: \"+elem.getName()\n\t\t+\"Sender status: \"+elem.getStatus()\n\t\t+\"is default?: \"+elem.isDefault()\n\t);\n}\nsenderNameFactory.actionAdd(\"NewSenderName\").execute();\nsenderNameFactory.actionSetDefault(\"NewSenderName\").execute();\nsenderNameFactory.actionDelete(\"NewSenderName\").execute();<\/code><\/pre>\n\n\n\n<p>The message SMS sender name ID must meet certain requirements. The most important thing is to remember that for security reasons, each new name must be approved by our employee during SMSAPI business hours. Verify your account first, it&#8217;ll speed up the process!<\/p>\n\n\n\n<div class=\"wp-block-smsapi-blog-2021-infobox infobox infobox--attention post-content--full-width\"><div class=\"infobox__icon\"><img decoding=\"async\" src=\"data:image\/svg+xml;base64,PHN2ZyB3aWR0aD0iMTAwJSIgaGVpZ2h0PSIxMDAlIiB2aWV3Qm94PSIwIDAgMTAgMTYiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgY2xpcC1ydWxlPSJldmVub2RkIiB4bWw6c3BhY2U9InByZXNlcnZlIiB2ZXJzaW9uPSIxLjEiPgogIDxwYXRoIGlkPSJzdmdfMSIgc3R5bGU9ImZpbGw6IHJnYigxNywgMTkyLCAxMjgpOyBmaWxsLXJ1bGU6IG5vbnplcm87IiBkPSJtMi45MTk2NCwwbDQsMGwwLDRsLTEsN2wtMiwwbC0xLC03bDAsLTR6Ii8+CiAgPHBhdGggaWQ9InN2Z18yIiBzdHlsZT0iZmlsbDogcmdiKDE3LCAxOTIsIDEyOCk7IGZpbGwtcnVsZTogbm9uemVybzsiIGQ9Im03LjAwODM3LDE0YzAsMS4xMDUgLTAuODk1LDIgLTIsMmMtMS4xMDUsMCAtMiwtMC44OTUgLTIsLTJjMCwtMS4xMDUgMC44OTUsLTIgMiwtMmMxLjEwNSwwIDIsMC44OTUgMiwyeiIvPgo8L3N2Zz4K\"\/><\/div><div class=\"infobox__title\"><h4>Free tests, no strings attached<\/h4><\/div><div class=\"infobox__content\">\n<p>Create a free trial account, no credit card required. Send test message in minutes and see other advanced features of business SMS gateway.<\/p>\n\n\n\n<div class=\"wp-block-buttons is-content-justification-center is-layout-flex wp-container-core-buttons-is-layout-16018d1d wp-block-buttons-is-layout-flex\">\n<div class=\"wp-block-button is-style-primary\"><a class=\"wp-block-button__link wp-element-button\" href=\"https:\/\/www.smsapi.com\/en\/signup\" target=\"_blank\" rel=\"noreferrer noopener\">Test SMS gateway<\/a><\/div>\n<\/div>\n<\/div><\/div>\n\n\n\n<h2 class=\"wp-block-heading\">Error handling in the SMSAPI Java library<\/h2>\n\n\n\n<p>During automatic SMS handling, errors may occur in many places. This may occur, for example, when connecting to the server, constructing queries, applying various parameters, or processing server responses. The server sends an error code and message instead of the expected response when something goes wrong.<\/p>\n\n\n\n<p>You can find a detailed list of codes in the&nbsp;<a href=\"https:\/\/www.smsapi.com\/docs\/#18-error-codes\" target=\"_blank\" rel=\"noreferrer noopener\">Documentation<\/a>. It\u2019s worth protecting yourself against errors, which is why the library defines multiple exception classes.<\/p>\n\n\n\n<ul class=\"language-java wp-block-list\">\n<li><code>ClientException<\/code>&nbsp;\u2013 these exceptions concern HTTP methods. The error codes used are, for example, 101 (incorrect OAuth2 token) and 103 (insufficient points to send the SMS).<\/li>\n\n\n\n<li><code>HostException<\/code>&nbsp;\u2013 these mean errors on the SMSAPI server\u2019s side. The codes include 8 (call error) and 201 or 999 (internal system error).<\/li>\n\n\n\n<li><code>ActionException<\/code>&nbsp;\u2013 these exceptions result from the incorrect use of one of the actions. Error code 11 is too long or has no message text. 13 is an incorrect recipient number or means a group and individual number are used simultaneously. 14 means an incorrect sender ID; 40 means the specified group does not exist.<\/li>\n\n\n\n<li><code>ProxyException<\/code>&nbsp;\u2013 these occur when a server connection error happens. They have no code from SMSAPI. They are thrown when an exception of the&nbsp;java.io.IOException class occurs.<\/li>\n<\/ul>\n\n\n\n<p class=\"language-java\">Specific error codes are returned by the&nbsp;<code>getCode()<\/code> method. In one case, if a&nbsp;message parameter with an index other than 0, 1, 2 or 3 was attempted to be called, an index out of array exception (<code>ArrayIndexOutOfBoundsException<\/code>) is also thrown.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">The SMSAPI Java library \u2013 more options<\/h2>\n\n\n\n<p>There are also other factories not described above which offer further possibilities for your Java app. One of them is&nbsp;<code>ContactsFactory<\/code>&nbsp;\u2013 as the name suggests, it is used to handle contact databases. It allows you to list, delete or edit individual recipients and their groups. Creating a new entry may look something like this \u2013 assuming there already is an HTTP client object:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>ContactsFactory contactsFactory = new ContactsFactory(client);\ncontactsFactory.actionContactAdd()\n\t.setFirstName(\"Test First Name\")\n\t.setLastName(\"Test Last Name\")\n\t.setPhoneNumber(numberTest)\n\t.setEmail(\"test@example.com\")\n\t.execute();<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Send MMS messages with Java<\/h2>\n\n\n\n<p class=\"language-java\">Another factory, called&nbsp;<code>MMSFactory<\/code>, is used to handle multimedia messages. The key is its actionSend method, which works the same way as for SMS sending, described earlier.<\/p>\n\n\n\n<p class=\"language-java\">Executing it (using the <code>execute()<\/code> method) returns a&nbsp;<code>SendStatusResponse<\/code> object, and with the \u201cset\u201d methods, you can set the message parameters, such as recipients and send date. Instead of a regular text, you must deliver a&nbsp;message in the SMIL format and its subject. The example below assumes that such correct content already exists:<\/p>\n\n\n\n<pre class=\"wp-block-code language-java\"><code>mmsFactory = new MMSFactory(client);\nmmsFactory.actionSend()\n\t.setTo(\"+32111222333\")\n\t.setSubject(\"test_subject\")\n\t.setSmil(smil_content)\n\t.execute();<\/code><\/pre>\n\n\n\n<p>As we&#8217;re nearing the end, I\u2019ll point you to a few places where you can seek answers to any technical questions you may have. The first is the&nbsp;<a rel=\"noreferrer noopener\" href=\"https:\/\/www.smsapi.com\/docs\" target=\"_blank\">API documentation<\/a>, which has already been mentioned several times. There are no references to Java code there, but it contains many detailed explanations. They\u2019ll help you understand what individual parameters, error codes and the ways that different features work are intended to do.<\/p>\n\n\n\n<p>If you find Javadoc documentation convenient to use, download the latest version (2.5) from the&nbsp;<a rel=\"noreferrer noopener\" href=\"https:\/\/labs.smsapi.com\/maven\/pl\/smsapi\/smsapi-lib\/2.5\/smsapi-lib-2.5-javadoc.jar\" target=\"_blank\">SMSAPI server<\/a>. Clearly structured and with lots of comments, it will be much easier to find your way around all the available classes, methods and packages.<\/p>\n\n\n\n<p>Unit tests, written using JUnit, are a good source of information too. You\u2019ll find them on&nbsp;<a rel=\"noreferrer noopener\" href=\"https:\/\/github.com\/smsapi\/smsapi-java-client\" target=\"_blank\">GitHub<\/a>. When the library was created, they were used for quality assurance, and it\u2019ll provide you with examples of using individual interfaces and methods.<\/p>\n\n\n\n<p>If this doesn\u2019t clarify all the points you&#8217;re uncertain about, dive into the most complete knowledge source of all, the library code. And don&#8217;t forget &#8211; our technical support is here to help you. Good luck!<\/p>\n\n\n\n<p>Oh, one more thing: I&#8217;ve covered <a href=\"https:\/\/www.smsapi.com\/blog\/receiving-sms-online-developer-guide\/\" target=\"_blank\" rel=\"noreferrer noopener\">how to receive SMS messages<\/a> in a separate article.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Here&#8217;s your go-to guide for Java SMS messaging. Introducing SMS API Java Library, along with code snippets, step-by-step instructions, and an explanation of the most common errors.<\/p>\n","protected":false},"author":21,"featured_media":5332,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[18],"tags":[20,39],"class_list":["post-5313","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tutorial","tag-english","tag-api"],"_links":{"self":[{"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/posts\/5313","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/comments?post=5313"}],"version-history":[{"count":27,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/posts\/5313\/revisions"}],"predecessor-version":[{"id":5906,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/posts\/5313\/revisions\/5906"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/media\/5332"}],"wp:attachment":[{"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/media?parent=5313"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/categories?post=5313"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/tags?post=5313"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}