Integrate WhatsApp Business API with Spring Boot

Why send WhatsApp from Spring Boot?

Spring Boot powers most modern Java backends — from order management to fintech platforms. Instead of writing raw HTTP client code, the Zaptilo starter gives you a typed, auto-configured service that follows Spring conventions.

• Drop-in Maven or Gradle dependency — no manual bean wiring
• Auto-configured Spring bean built on RestTemplate
• Send text, media (image/video/document), and approved template messages
• Compatible with Spring Boot 2.x and 3.x, Java 17+
• Zero external HTTP libraries — uses what your app already has

Prerequisites

1. Java 17 or higher
2. Spring Boot 2.x or 3.x application
3. A free Zaptilo account with an API token (Dashboard → Developer Tools → Access Tokens)
4. An approved WhatsApp template in your Zaptilo account (for template messages)

Step 1: Add the Maven Dependency

Add the Zaptilo WhatsApp starter to your pom.xml:

<dependency>
    <groupId>ai.zaptilo</groupId>
    <artifactId>zaptilo-whatsapp-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Or with Gradle in build.gradle:

implementation 'ai.zaptilo:zaptilo-whatsapp-spring-boot-starter:1.0.0'

Step 2: Configure Your API Token

Add your Zaptilo API token to application.properties:

zaptilo.api.token=your_token_here
zaptilo.api.base-url=https://web.zaptilo.ai

Or in application.yml:

zaptilo:
  api:
    token: your_token_here
    base-url: https://web.zaptilo.ai

Step 3: Inject and Send Messages

Inject ZaptiloWhatsAppService into any Spring component:

import ai.zaptilo.whatsapp.ZaptiloWhatsAppService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class NotificationService {

    @Autowired
    private ZaptiloWhatsAppService whatsApp;

    public void sendOrderConfirmation(String customerNumber, String orderId) {
        whatsApp.sendTemplate(
            customerNumber,
            "order_confirmation",
            "en",
            List.of("John Doe", orderId),
            null
        );
    }

    public void sendWelcomeText(String number) {
        whatsApp.sendMessage(number, "Welcome to our service!");
    }

    public void sendInvoice(String number, String invoiceUrl) {
        whatsApp.sendMedia(number, invoiceUrl, "document", "Your invoice");
    }
}

Step 4: Send from a REST Controller

Trigger a WhatsApp message from any HTTP endpoint — perfect for webhooks and order events:

@RestController
public class WebhookController {

    @Autowired
    private ZaptiloWhatsAppService whatsApp;

    @PostMapping("/order-placed")
    public ResponseEntity<?> onOrderPlaced(@RequestBody Order order) {
        whatsApp.sendTemplate(
            order.getCustomerPhone(),
            "order_confirmation",
            "en",
            List.of(order.getCustomerName(), order.getId()),
            null
        );
        return ResponseEntity.ok().build();
    }
}

API Reference

Error Handling

Wrap calls in try/catch to handle API failures gracefully:

try {
    whatsApp.sendMessage("919876543210", "Hello!");
} catch (HttpClientErrorException e) {
    log.error("Zaptilo API error: {}", e.getResponseBodyAsString());
}

Common Use Cases

Best Practices

• Store your API token in environment variables or Spring Cloud Config — never commit to source control.
• Use @Async for high-volume sends so message delivery does not block your request thread.
• Wrap WhatsApp calls in a circuit breaker (Resilience4j) for production resilience.
• Log responses to your standard SLF4J logger for observability.
• Use template messages for any message sent outside the 24-hour customer service window.

Frequently asked questions