Java SDK

Official Orbit Java SDK quickstart

Java SDK

The official Orbit Java SDK provides a type-safe client for the Orbit API. Built for Java 17+, it supports all Orbit services with synchronous and asynchronous APIs, automatic retries, and structured error handling.

Installation

Maven

<dependency>
  <groupId>io.devotel</groupId>
  <artifactId>orbit-java</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle

implementation 'io.devotel:orbit-java:1.0.0'

Quick Start

import io.devotel.Orbit;

import java.io.IOException;

public class QuickStart {
    public static void main(String[] args) throws IOException {
        Orbit orbit = new Orbit("dv_live_sk_your_key_here");

        var message = orbit.messages.send("[phone]", "Hello from Orbit!", "sms");

        System.out.println(message.get("data")); // {message_id=msg_abc123, ...}
    }
}

Messaging

// Send WhatsApp message
var waMessage = orbit.messages.send("[phone]", "Hello from Orbit on WhatsApp!", "whatsapp");

// Send SMS shorthand
var sms = orbit.messages.sendSms("[phone]", "Quick SMS hello!");

Voice

// Make an outbound call
var call = orbit.voice.createCall("[phone]", "[phone]");

// Retrieve call details
var callDetails = orbit.voice.getCall(call.get("data").toString());

Verify

// Send OTP
var verification = orbit.verify.send("[phone]", "sms");

// Check OTP
var verificationId = ((java.util.Map<?, ?>) verification.get("data")).get("verification_id").toString();
var result = orbit.verify.check(verificationId, "482901");

System.out.println(result.get("data")); // {status=approved, ...}

Async Support

All methods are synchronous and throw IOException on network or API errors. Wrap calls in your own async executor if needed:

import java.util.concurrent.CompletableFuture;

CompletableFuture.supplyAsync(() -> {
    try {
        return orbit.messages.send("[phone]", "Async hello!", "sms");
    } catch (IOException e) {
        throw new RuntimeException(e);
    }
}).thenAccept(response ->
    System.out.println("Sent: " + response.get("data"))
);

Webhooks

import io.devotel.orbit.webhook.WebhookVerifier;

// Spring Boot controller
@RestController
public class WebhookController {

    private final WebhookVerifier verifier = new WebhookVerifier("whsec_your_secret");

    @PostMapping("/webhooks/orbit")
    public ResponseEntity<Map<String, Boolean>> handleWebhook(
            @RequestBody String payload,
            @RequestHeader("X-Devotel-Signature") String signature) {

        if (!verifier.verify(payload, signature)) {
            return ResponseEntity.status(401).build();
        }

        WebhookEvent event = WebhookEvent.parse(payload);
        switch (event.getType()) {
            case "message.delivered" -> handleDelivery(event);
            case "call.completed" -> handleCallComplete(event);
        }

        return ResponseEntity.ok(Map.of("received", true));
    }
}

Error Handling

import java.io.IOException;

try {
    orbit.messages.send("invalid", "Hi", "sms");
} catch (IOException e) {
    System.err.println(e.getMessage()); // "HTTP 422: {\"error\":{\"code\":\"INVALID_PHONE_NUMBER\",...}}"
}

Configuration

Orbit orbit = new Orbit("dv_live_sk_your_key_here");

// Or with a custom base URL
Orbit orbitCustom = new Orbit("dv_live_sk_your_key_here", "https://orbit-api.devotel.io/api/v1");

Option	Type	Default	Description
apiKey	String	—	Your Devotel API key (required)
baseUrl	String	https://orbit-api.devotel.io/api/v1	API base URL

Requirements

• Java 17 or later
• OkHttp and Jackson (included as dependencies)