Bandwidth

Send SMS through the Bandwidth Messaging API v2 with the SMS SDK bandwidth() adapter, and receive delivery and inbound callbacks behind Basic authentication.

The bandwidth() adapter sends SMS through the Bandwidth Messaging API v2 and parses Bandwidth’s delivery and inbound callbacks. To compare it with other providers, see Choose a provider.

Support status

Partial. The adapter passes the shared contract tests, with these limits:

• SMS only. mediaUrls, sendAt, validityPeriodSec, and a per-message webhookUrl throw UnsupportedFieldError before any request.
• Bandwidth does not sign callbacks. The webhook parser requires the Basic credentials you set on your Bandwidth application instead.
• Rejections are classified by HTTP status, and a 429 counts as a rate limit only when Bandwidth wrote the body; any other 429 is an unknown outcome. Bandwidth’s full error code list is not mapped, so most rejections are request and do not fall back. See Error codes.

The same notes are in adapter.support.notes at runtime.

Setup

npm install @opencoredev/sms-sdk

pnpm add @opencoredev/sms-sdk

yarn add @opencoredev/sms-sdk

bun add @opencoredev/sms-sdk

nub add @opencoredev/sms-sdk

aube add @opencoredev/sms-sdk

The adapter reads no environment variables itself. The examples and the doctor CLI use these names.

import { createSmsClient } from "@opencoredev/sms-sdk";
import { bandwidth } from "@opencoredev/sms-sdk/bandwidth";

const sms = createSmsClient({
  adapters: [
    bandwidth({
      userId: process.env.BANDWIDTH_USER_ID ?? "",
      apiToken: process.env.BANDWIDTH_API_TOKEN ?? "",
      apiSecret: process.env.BANDWIDTH_API_SECRET ?? "",
      applicationId: process.env.BANDWIDTH_APPLICATION_ID ?? "",
      from: "+15550100001",
    }),
  ],
});

const result = await sms.send({ to: "+14155550123", body: "Your order has shipped." });
console.log(result.providerId); // the Bandwidth message ID

bandwidth() throws ConfigurationError when any of the four credentials is empty. baseUrl (default https://messaging.bandwidth.com) and fetch are optional.

Senders

Bandwidth sends from a long code, a toll-free number, or a short code. Alphanumeric sender IDs and { messagingService } fail validation before any request. US long codes, toll-free numbers, and short codes need registration with carriers; see Registration and consent.

Features

Provider options

Pass Bandwidth-only fields under providerOptions.bandwidth:

// Loading the adapter module adds the typed providerOptions.bandwidth entry.
import "@opencoredev/sms-sdk/bandwidth";
import { sms } from "./sms";

await sms.send({
  to: "+14155550123",
  body: "Your code is 123456",
  providerOptions: { bandwidth: { tag: "otp", priority: "high" } },
});

Webhooks

Bandwidth posts delivery and inbound events to the callback URL on your messaging application. Set callback credentials on that application, then pass the same values to the parser. The credentials are required.

import { parseSmsWebhook, WebhookSignatureError } from "@opencoredev/sms-sdk/webhooks";
import { db } from "./db";

export async function POST(request: Request): Promise<Response> {
  try {
    const event = await parseSmsWebhook({
      provider: "bandwidth",
      request,
      credentials: {
        username: process.env.BANDWIDTH_CALLBACK_USERNAME ?? "",
        password: process.env.BANDWIDTH_CALLBACK_PASSWORD ?? "",
      },
    });
    if (await db.webhookEvents.insertIfNew(event.dedupeKey)) {
      console.log(event.type);
    }
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookSignatureError) return new Response(null, { status: 401 });
    throw error;
  }
}

A request without a matching Authorization header throws WebhookSignatureError. The comparison runs in constant time. Bandwidth sends no signature and no timestamp, so there is no replay window: store event.dedupeKey and skip repeats.

dedupeKey is bandwidth:{messageId}:{type}.

Limitations

• No MMS. Use Twilio, Telnyx, or Plivo.
• No scheduling or validity period. Use Telnyx or Sinch for scheduling, and Twilio, Plivo, Vonage, or Sinch for a validity period.
• No alphanumeric sender IDs.
• Callbacks carry no signature, so the Basic credentials and HTTPS are the only proof a request came from Bandwidth.

Error codes

error.provider.requestId holds the X-Request-Id or X-Correlation-Id header. See Fallback and retries for what each category does.

Official documentation

• Messaging API
• Messaging callbacks

Next steps

• Receive status and inbound webhooks
• Webhook security
• Choose a provider