- \n
- Executive summary<\/a><\/li>\n\n\n\n
- TL;DR<\/a><\/li>\n\n\n\n
- Why Java needs its own guide<\/a><\/li>\n\n\n\n
- Is there an official Java SDK<\/a><\/li>\n\n\n\n
- Choosing the HTTP client<\/a><\/li>\n\n\n\n
- The timeout problem, in full<\/a><\/li>\n\n\n\n
- Connect timeout versus read timeout<\/a><\/li>\n\n\n\n
- Form encoding, and why JSON looks like an auth failure<\/a><\/li>\n\n\n\n
- Jackson at the boundary<\/a><\/li>\n\n\n\n
- The response contract is not consistent, and Java notices first<\/a><\/li>\n\n\n\n
- Configuration and credentials<\/a><\/li>\n\n\n\n
- The send client<\/a><\/li>\n\n\n\n
- Authentication: API key, and now OAuth 2.0 with PKCE<\/a><\/li>\n\n\n\n
- Counting segments correctly in Java<\/a><\/li>\n\n\n\n
- The India DLT layer<\/a><\/li>\n\n\n\n
- The appendReplacement trap<\/a><\/li>\n\n\n\n
- Spring Retry, configured not to retry<\/a><\/li>\n\n\n\n
- Claim before send<\/a><\/li>\n\n\n\n
- Batching and the recipient list<\/a><\/li>\n\n\n\n
- OTP in Spring Boot<\/a><\/li>\n\n\n\n
- WhatsApp from the same codebase<\/a><\/li>\n\n\n\n
- Delivery reports: the webhook receiver<\/a><\/li>\n\n\n\n
- Delivery reports: the poller<\/a><\/li>\n\n\n\n
- Resilience4j: rate limiter, bulkhead and circuit breaker<\/a><\/li>\n\n\n\n
- Micrometer instrumentation<\/a><\/li>\n\n\n\n
- Testing with JUnit 5 and MockWebServer<\/a><\/li>\n\n\n\n
- Security and secret handling<\/a><\/li>\n\n\n\n
- The ten-step build order<\/a><\/li>\n\n\n\n
- Decision matrix<\/a><\/li>\n\n\n\n
- Production checklist<\/a><\/li>\n\n\n\n
- Ten mistakes<\/a><\/li>\n\n\n\n
- What this article deliberately does not claim<\/a><\/li>\n\n\n\n
- FAQ<\/a><\/li>\n<\/ol>\n\n\n\n
\n\n\n\nExecutive summary<\/h2>\n\n\n\n
To send an SMS from Java you POST an
application\/x-www-form-urlencoded<\/code> body tohttps:\/\/unify.smsgateway.center\/SMSApi\/send<\/code> withuserid<\/code>,password<\/code> or anapiKey<\/code> header,sendMethod=quick<\/code>,mobile<\/code>,msg<\/code>,senderid<\/code>,msgType<\/code> andoutput=json<\/code>. That part takes twenty minutes. The remaining ninety percent of a production integration is defending against the defaults in the Java HTTP stack, none of which were designed for an operation that costs money the instant it is accepted.<\/p>\n\n\n\n![\"Geometric](\"https:\/\/www.smsgatewaycenter.com\/blog\/wp-content\/uploads\/2026\/08\/messaging-java-spring-boot-integration-1024x584.webp\")
<\/a><\/figure>\n\n\n\nJava has a specific and unusually dangerous set of defaults here.
WebClient<\/code> on Reactor Netty applies no response timeout unless you configure one.RestTemplate<\/code> with a bareSimpleClientHttpRequestFactory<\/code> applies no timeout either. Spring Retry, added in one annotation, will happily replay a POST that was already accepted upstream and bill you twice. Jackson binds by property name, which means the moment a response field arrives asChannel Name<\/code> with a space in it, or as a quoted string where a sibling endpoint returns an unquoted number, your deserializer throws in production and not in your test.Matcher.appendReplacement<\/code> treats a dollar sign in a replacement string as a group reference, which will silently corrupt a DLT variable substitution when a customer’s name or an order reference contains one.<\/p>\n\n\n\nThis guide walks the full build, in Java 17 and Spring Boot 3, against the real documented endpoints. It is the Java sibling to the PHP<\/a>, Node.js<\/a> and Python<\/a> tutorials, and it does not repeat their material. Where a concept is fully covered elsewhere on this site, this article links there and moves on.<\/p>\n\n\n\n
\n\n\n\nTL;DR<\/h2>\n\n\n\n
- \n
- Use
WebClient<\/code>, and set both a connect timeout and a response timeout explicitly. Neither exists by default.<\/li>\n\n\n\n- Build the body as a
MultiValueMap<String, String><\/code> and send it asAPPLICATION_FORM_URLENCODED<\/code>. Sending JSON to this endpoint does not fail as a 400. It fails as an authentication error, because the parameters simply are not there.<\/li>\n\n\n\n- Configure Jackson to tolerate an inconsistent contract.
statusCode<\/code> arrives quoted fromSMSApi\/send<\/code> and unquoted fromWAApi\/send<\/code>. The by-transaction report endpoint returns field names containing spaces and mixed capitalisation. Both need explicit handling.<\/li>\n\n\n\n- Turn Spring Retry off on the send path. Retry the read endpoints, never the write.<\/li>\n\n\n\n
- Count segments with
codePointCount<\/code>, notlength<\/code>. Java strings are UTF-16 andlength<\/code> counts code units.<\/li>\n\n\n\n- Render DLT variables by positional substitution, not by
String.replaceAll<\/code> and not byMatcher.appendReplacement<\/code> withoutMatcher.quoteReplacement<\/code>.<\/li>\n\n\n\n- Claim the row in the database before the HTTP call, inside a transaction, behind a unique constraint. An ambiguous outcome moves to
UNKNOWN<\/code> and never back toPENDING<\/code>.<\/li>\n\n\n\n- Verify the webhook signature over the raw bytes with
@RequestBody byte[]<\/code> andMessageDigest.isEqual<\/code>, before any parsing.<\/li>\n\n\n\n- Use Resilience4j for the rate limiter and the bulkhead. Do not use a circuit breaker on the send path without understanding what it does to a queue.<\/li>\n\n\n\n
- Test at the transport layer with MockWebServer. A test suite that really sends is a test suite that really bills.<\/li>\n<\/ul>\n\n\n\n
\n\n\n\nWhy Java needs its own guide<\/h2>\n\n\n\n
There is a reasonable objection to a per-language tutorial: HTTP is HTTP, so why not write one article and translate the snippets. The objection is wrong for the same reason it was wrong in Node.js and Python, and it is more wrong in Java. The failure modes in a messaging integration are almost entirely defaults, and defaults are a property of the language and its ecosystem, not of the protocol.<\/p>\n\n\n\n
Five things are specifically Java-shaped here.<\/p>\n\n\n\n
Strings are UTF-16.<\/strong>
\"\ud83d\ude00\".length()<\/code> is 2 in Java. Every naive segment counter written in Java is wrong for exactly the characters that trigger the expensive Unicode encoding, and it is wrong in the direction that undercounts, which means you discover it on the invoice rather than in the test.<\/p>\n\n\n\nJackson binds by name and by type.<\/strong> Loosely typed languages shrug at a field that is sometimes
\"200\"<\/code> and sometimes200<\/code>. Java throwsMismatchedInputException<\/code> at runtime, from a code path that only executes for one of the two channels, which is a beautiful way to ship a bug that passes every test.<\/p>\n\n\n\nSpring makes retry a one-line decision.<\/strong>
@Retryable<\/code> is a single annotation. It does not know that the operation it is wrapping is a billed, non-idempotent write. Every other language in this series requires you to install and wire a retry library; Java hands it to you before you have thought about it.<\/p>\n\n\n\nReactor Netty’s default is no timeout.<\/strong> This is the same trap as
fetch<\/code> in Node, but it is worse in a Spring application, because the hang consumes a slot in a bounded connection pool and a slot in a bounded thread pool. One upstream stall becomes a saturated application rather than one slow request.<\/p>\n\n\n\nRegex replacement strings are interpreted.<\/strong>
$<\/code> and\\<\/code> are metacharacters in a Java replacement string. This is the exact analogue of the JavaScript$&<\/code> hazard documented in the Node.js tutorial<\/a>, and it lands in DLT variable rendering, which is the one place in an Indian SMS integration where a corrupted character does not just look bad, it fails template matching and the message is rejected.<\/p>\n\n\n\n
\n\n\n\nIs there an official Java SDK<\/h2>\n\n\n\n
No. As of the date on this article, the SDK section of the developer documentation<\/a> lists a PHP SDK and a Python SDK, and nothing else. There is a Postman collection<\/a> which is useful as a source of request fixtures, but there is no Maven or Gradle artifact to depend on.<\/p>\n\n\n\n
That is not a problem. The API surface is small, form encoded and stable, and the client you are about to write is about a hundred and fifty lines. A thin hand-written client that you control is a better outcome here than a dependency, because every hard part of this integration is in configuration you would have to override anyway.<\/p>\n\n\n\n
If you want a search across the whole endpoint surface before you start, the SMS messaging API index<\/a> enumerates every endpoint in one page.<\/p>\n\n\n\n
\n\n\n\nChoosing the HTTP client<\/h2>\n\n\n\n
- Build the body as a
- TL;DR<\/a><\/li>\n\n\n\n
![\"Illustration](\"https:\/\/www.smsgatewaycenter.com\/blog\/wp-content\/uploads\/2026\/08\/connect-timeout-versus-read-timeout.webp\")
<\/a><\/figure>\n\n\n\n