Skip to main content

​
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("+14155552671", "Hello from Orbit!", "sms");

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

​
Messaging

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

// Send SMS shorthand
var sms = orbit.messages.sendSms("+14155552671", "Quick SMS hello!");

​
Voice

// Make an outbound call
var call = orbit.voice.createCall("+14155552671", "+18005551234");

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

​
Verify

// Send OTP
var verification = orbit.verify.send("+14155552671", "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("+14155552671", "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");
OptionTypeDefaultDescription
apiKeyString—Your Devotel API key (required)
baseUrlStringhttps://orbit-api.devotel.io/api/v1API base URL

​
Requirements

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