Skip to main content

JavaScript / Node.js SDK

The official afriroute package gives you a fully-typed, promise-based client for SMS, Voice, WhatsApp, and Email — with automatic retries and Bearer-token authentication built in.

Installation​

npm install afriroute

Or with Yarn / pnpm:

yarn add afriroute
pnpm add afriroute

Authentication​

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

import Afriroute from "afriroute";

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

To target the sandbox or tune behavior, pass options:

const client = new Afriroute("$AFRIROUTE_API_KEY", {
  baseUrl: "https://api.afriroute.ai",
  timeout: 60000,  // 60 seconds
  maxRetries: 5,
});
tip

Load your key from the environment, never hard-code it: new Afriroute(process.env.AFRIROUTE_API_KEY).

Send an SMS​

const sms = await client.sms.send({
  to: "+251900000000",
  message: "Hello from AfriRoute",
  senderId: "AfriRoute",
});

console.log(sms.message_id);

Send a WhatsApp Message​

const wa = await client.whatsapp.send({
  to: "+251900000000",
  message: "Hello via WhatsApp",
});

console.log(wa.message_id);

Make a Voice Call​

const call = await client.voice.call({
  to: "+251900000000",
  from: "+1234567890",
  ttsMessage: "Welcome to AfriRoute",
});

console.log(call.call_id);

Send an Email​

const email = await client.email.send({
  to: "[email protected]",
  subject: "Welcome",
  body: "<h1>Hello</h1>",
});

console.log(email.message_id);

Error Handling​

Failed requests reject with an error carrying a code, message, and status:

try {
  await client.sms.send({
    to: "+251900000000",
    message: "Hello",
    senderId: "AfriRoute",
  });
} catch (error) {
  switch (error.code) {
    case "INVALID_PHONE_NUMBER":
      console.error("Use E.164 format, e.g. +251911234567");
      break;
    case "INSUFFICIENT_BALANCE":
      console.error("Top up your account");
      break;
    case "RATE_LIMIT_EXCEEDED":
      console.error("Slow down — retrying automatically");
      break;
    default:
      console.error(`${error.code}: ${error.message}`);
  }
}

Transient failures (429, 5xx) are retried automatically up to maxRetries with exponential back-off.

TypeScript​

The package ships with bundled type definitions — no @types install required. Request and response shapes are fully typed:

import Afriroute, { SmsResponse } from "afriroute";

const client = new Afriroute(process.env.AFRIROUTE_API_KEY!);
const res: SmsResponse = await client.sms.send({
  to: "+251900000000",
  message: "Hi",
  senderId: "AfriRoute",
});

Features​

  • Promise-based, async/await friendly
  • Bundled TypeScript definitions
  • Automatic retries with exponential back-off
  • Built-in rate-limit (429) handling
  • Configurable base URL and timeout

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