xoxa-msg

A TypeScript-first, multi-platform messaging SDK for SMS, WhatsApp, and Telegram, built with developer speed in mind.

📲 What is xoxa-msg?

xoxa-msg is a class-based, strongly typed messaging library that gives you a single API to send messages across multiple providers. No need to juggle three different APIs — this package serves as a wrapper that unifies them.

✅ SMS via Twilio
✅ WhatsApp via Meta's WhatsApp Cloud API
✅ Telegram via Bot API

Supports:

• Media attachments
• Typed delivery receipts
• Retry with exponential backoff
• Full OOP and TypeScript typing
• Pluggable transports
• Form encoding support for Twilio

---

📦 Installation

npm install xoxa-msg

---

📂 Folder Structure

src/
├── core/            # Core logic (XoxaClient, Events, Errors)
├── types/           # Reusable types (message, config)
├── interfaces/      # Logger + Transport interfaces
├── transports/      # Twilio, WhatsApp, Telegram classes
├── utilities/       # HTTP, form encoding, logger
├── dtos/            # Normalized message/delivery DTOs
└── constants/       # Defaults, channel enums

---

🧑‍💻 Example Usage

SMS (Via Twilio)

// tested on an isolated index.ts file
import { TwilioSmsTransport, XoxaClient } from "xoxa-msg";
import * as dotenv from "dotenv";
dotenv.config();
(async () => {
    const client = new XoxaClient({ appId: "xoxa-app", debug: true });
    client.registerTransport(
        new TwilioSmsTransport({
            accountSid: process.env.TWILIO_SID!,
            authToken: process.env.TWILIO_TOKEN!,
        }),
    );

    await client.connect();

    await client.send({
        channel: "sms",
        to: "+791532459",
        body: "Hello from Durban! 🇿🇦",
        from: "+55545865987",
    });

    await client.disconnect();
})();

Whatsapp (Via Meta)

// tested on an isolated index.ts file
import { WhatsAppTransport, XoxaClient } from "xoxa-msg";
import * as dotenv from "dotenv";
dotenv.config();
(async () => {
    const client = new XoxaClient({ appId: "xoxa-app", debug: true });
    client.registerTransport(
        new WhatsAppTransport({
            accessToken: process.env.WHATSAPP_TOKEN!,
            phoneNumberId: process.env.WHATSAPP_NUMBER_ID!,
        }),
    );

    await client.connect();

    await client.send({
        channel: "whatsapp",
        to: "+7949584265",
        body: "Check this out!",
        media: [
            {
                kind: "image",
                url: "https://example.com/dog.jpg",
                caption: "Here’s my dog 🐶",
            },
        ],
    });

    await client.disconnect();
})();

Telegram (Via Telegram Bot)

// tested on an isolated index.ts file
// tested on an isolated index.ts file
import { TelegramTransport, XoxaClient } from "xoxa-msg";
import * as dotenv from "dotenv";
dotenv.config();
(async () => {
    const client = new XoxaClient({ appId: "xoxa-app", debug: true });
    client.registerTransport(
        new TelegramTransport({
            botToken: process.env.TELEGRAM_BOT_TOKEN!,
        }),
    );

    await client.connect();

    await client.send({
        channel: "telegram",
        to: "8269012244",
        body: "Test",
    });

    await client.disconnect();
})();