Afromessage SMS

The @birrjs/sms-afromessage plugin sends SMS messages to customers when subscription events occur — payment received, payment failed, or subscription expired.

Installation

pnpm add @birrjs/sms-afromessage

Configuration

import { afromessage } from "@birrjs/sms-afromessage";
import { createBirr } from "@birrjs/core";

createBirr({
  // ... other options
  plugins: [
    afromessage({
      apiKey: process.env.AFROMESSAGE_API_KEY!,
      sender: process.env.AFROMESSAGE_SENDER,   // optional (defaults to "AfroMessage")
      from: "your-identifier-id",                  // optional — for multiple short codes
    }),
  ],
});

Environment variables

How it works

The plugin listens to three subscription lifecycle events via the onEvent hook system and sends an SMS to the customer's phone number.

Phone number

The phone number is read from the birrjs_customer.phone column. You need to set it on your customer record before the event fires — typically in a server action after signup:

import { db } from "./db";
import { birrjsCustomer } from "./schema";

export async function setPhone(customerId: string, phone: string) {
  await db.insert(birrjsCustomer)
    .values({ id: customerId, phone })
    .onConflictDoUpdate({ target: birrjsCustomer.id, set: { phone } });
}

If the customer has no phone number when an event fires, the SMS is silently skipped.

Custom messages

Override the default messages with your own templates:

afromessage({
  messages: {
    paymentReceived: "Payment confirmed! Your {planName} plan is active.",
    paymentFailed: "Payment failed for {planName}. Please update your payment method.",
    subscriptionExpired: "Your {planName} subscription has ended. Renew now.",
  },
})

Template variables are enclosed in {curly braces}. Currently supported: none, reserved for future use.

Test account behavior

Afromessage test accounts replace API-delivered message content with <<...>>. The API returns acknowledge: "success" but the actual SMS delivered is a placeholder.

• Dashboard tests — work normally, shows your message with the test account watermark
• API calls — content is replaced with <<...>>

To send real messages, upgrade your Afromessage account and request a verified sender ID from the Afromessage dashboard. Once verified, set AFROMESSAGE_SENDER to your sender name.