SMS JavaScript SDK

Send texts, list inbound messages, and verify inbound webhooks from Node and TypeScript with the hepgg package.

SMS SDK#

The hepgg package wraps the SMS gateway in a typed client. It keeps the original one-line send() helper, adds a class for listing inbound messages and reading stats, and ships helpers to verify the inbound webhook so you stop hand-rolling that check.

Install#

npm install hepgg --registry https://npm.hep.gg

echo 'registry=https://npm.hep.gg' >> .npmrc
npm install hepgg

Send A Text#

The simplest path is the functional send(token, recipient, content), identical to the old sms package so a swap is just the import.

import { send } from "hepgg/sms";
 
await send(process.env.SMS_KEY, "+447700900000", "Hello from Hep.gg");

const { send } = require("hepgg/sms");
 
send(process.env.SMS_KEY, "+447700900000", "Hello from Hep.gg");

The Class#

For more than one call, construct an SMS client once and reuse it. It can send, list the last inbound messages, and read public stats.

import { SMS } from "hepgg/sms";
 
const sms = new SMS({ token: process.env.SMS_KEY });
 
await sms.send("+447700900000", "Hello");
const inbox = await sms.list(); // newest first; [] when there are none yet
const stats = await sms.stats(); // public service stats, no auth needed

Inbound Webhooks#

When someone texts your shortcode, Hep.gg POSTs JSON to your webhook. The secret arrives in the body as auth, not a header. Use the helpers to parse and verify it in constant time.

import { parseWebhook, verifyWebhook } from "hepgg/sms";
 
app.post("/sms", express.json(), (req, res) => {
  const msg = parseWebhook(req.body); // typed { sender, auth, shortcode, messageContent }
  if (!verifyWebhook(msg, process.env.WEBHOOK_SECRET)) return res.sendStatus(401);
  console.log(msg.shortcode, msg.messageContent);
  res.sendStatus(200);
});

See Receiving SMS for the full payload and routing rules.

Options And Errors#

A failed send throws a typed HepError (for example insufficient credits is 400). list() returns [] rather than throwing when the inbox is empty.

import { HepError } from "hepgg";
 
try {
  await sms.send("+447700900000", "hi");
} catch (err) {
  if (err instanceof HepError) console.error(err.status, err.message);
}

Full Reference#

Sending, Receiving, and Listing document the underlying API the SDK calls.