Skip to main content

Java SDK

The official ai.afriroute:afriroute library provides a typed Java client for SMS, Voice, WhatsApp, and Email — with automatic retries and Bearer-token authentication built in. Works with Spring Boot and Android.

Installation​

Maven​

<dependency>
    <groupId>ai.afriroute</groupId>
    <artifactId>afriroute</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle​

implementation 'ai.afriroute:afriroute:1.0.0'

Authentication​

Create a client with your API key. It is sent as Authorization: Bearer $AFRIROUTE_API_KEY against https://api.afriroute.ai.

import ai.afriroute.Afriroute;

Afriroute client = new Afriroute("$AFRIROUTE_API_KEY");

Target the sandbox or tune behavior with the full constructor:

Afriroute client = new Afriroute(
    "$AFRIROUTE_API_KEY",
    "https://api.afriroute.ai",
    60,  // timeout in seconds
    5    // max retries
);
tip

Read the key from the environment: new Afriroute(System.getenv("AFRIROUTE_API_KEY")).

Send an SMS​

String response = client.sms().send(
    "+251900000000",
    "Hello from AfriRoute",
    "AfriRoute"
);

System.out.println(response);

Send a WhatsApp Message​

String wa = client.whatsapp().send(
    "+251900000000",
    "Hello via WhatsApp"
);

System.out.println(wa);

Make a Voice Call​

String call = client.voice().call(
    "+251900000000",   // to
    "+1234567890",     // from
    "Welcome to AfriRoute",
    null               // optional answer URL
);

System.out.println(call);

Send an Email​

String email = client.email().send(
    "[email protected]",
    "Welcome",
    "<h1>Hello</h1>"
);

System.out.println(email);

Error Handling​

Failed requests throw AfriRouteException, exposing getCode(), getMessage(), and getStatusCode():

import ai.afriroute.AfriRouteException;

try {
    client.sms().send("+251900000000", "Hello", "AfriRoute");
} catch (AfriRouteException e) {
    switch (e.getCode()) {
        case "INVALID_PHONE_NUMBER":
            System.out.println("Use E.164 format, e.g. +251911234567");
            break;
        case "INSUFFICIENT_BALANCE":
            System.out.println("Top up your account");
            break;
        case "RATE_LIMIT_EXCEEDED":
            System.out.println("Slow down — retried automatically");
            break;
        default:
            System.out.println(e.getCode() + ": " + e.getMessage());
    }
}

Transient failures (429, 5xx) are retried automatically up to the configured max retries with exponential back-off.

Spring Boot Integration​

Expose the client as a bean:

@Bean
public Afriroute afriroute(@Value("${afriroute.api-key}") String apiKey) {
    return new Afriroute(apiKey);
}

Features​

  • Typed client with builder-friendly requests
  • Thread-safe and reusable across requests
  • Automatic retries with exponential back-off
  • Built-in rate-limit (429) handling
  • Compatible with Spring Boot and Android

Last Updated: May 2026 · Need help? Contact Support →