Skip to content
SMS SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Overview

SMS SDK sends and receives transactional SMS through Twilio, Telnyx, Plivo, Vonage, Bandwidth, or Sinch with one typed TypeScript API.

SMS SDK (@opencoredev/sms-sdk) sends transactional SMS through six providers with one TypeScript API, and turns their delivery and inbound webhooks into one event shape.

What it solves

Every provider has its own request format, error codes, status names, and webhook signatures. Code written for one is hard to move, and the failure cases are easy to get wrong:

  • A timeout does not tell you whether the provider created the message. Retrying it, or trying a second provider, can text the recipient twice.
  • A successful response only means the provider queued the message. Delivery is reported later, by webhook.
  • A provider that cannot schedule or send MMS may ignore the field or fail in its own way.
  • Each provider signs its callbacks differently, and a proxy in front of your app often breaks verification.

With SMS SDK, a send either returns a result or throws an error that says whether sending again is safe. Fields the provider cannot handle throw before any request. Webhooks are verified before any field is read.

import { createSmsClient, HandoffUnknownError } from "@opencoredev/sms-sdk";
import { telnyx } from "@opencoredev/sms-sdk/telnyx";

const sms = createSmsClient({
  adapters: [telnyx({ apiKey: process.env.TELNYX_API_KEY ?? "", from: "+15550100001" })],
});

try {
  const result = await sms.send({
    to: "+14155550123",
    body: "Your order has shipped.",
    idempotencyKey: "order:123:shipped:v1",
  });
  console.log(result.providerId, result.delivery); // the provider's message ID, "queued"
} catch (error) {
  if (error instanceof HandoffUnknownError) {
    // The provider may have sent it. Check before sending again.
  }
  throw error;
}

To change provider, replace telnyx(...) with another adapter. The send() call stays the same. Runnable versions are in the examples.

Providers

  • Twilio: Programmable Messaging. Supported.
  • Telnyx: Messaging API v2. Supported.
  • Plivo: Message API. Partial: Plivo does not document its error body, so most rejections cannot be classified.
  • Vonage: Messages API, SMS channel. Partial: error classification is inferred, and there are no short codes or MMS.
  • Bandwidth: Messaging API v2. Partial: SMS only, and most rejections cannot be classified.
  • Sinch: SMS API. Partial: no MMS, and most rejections cannot be classified.

Choose a provider compares what each one supports.

Scope and limits

SMS SDK is a transport library for your server. It does not include:

  • Conversation threads, an inbox, chatbots, WhatsApp, RCS, or iMessage.
  • An OTP verification service, a hosted API, a dashboard, or number purchasing.
  • 10DLC, toll-free, or sender ID registration. You do that with each provider. See Registration and consent.
  • Exactly-once delivery. No supported provider offers send idempotency, so no SMS library can promise it. SMS SDK tells you when an outcome is unknown instead of guessing. See Prevent duplicate sends.

When to use the provider’s own SDK instead

Use the provider’s SDK when you need more than SMS: voice, verification, number lookup, number purchasing, account management, or Twilio Content Templates. It also types a new API parameter the day it ships, where SMS SDK passes it through providerOptions.<provider>.extra unvalidated until a release adds it. Provider SDKs have years of production use; SMS SDK is at 0.1.0.

Use SMS SDK when you only send and receive SMS, may change or add providers, and want timeouts and duplicate risks handled for you. It has no runtime dependencies.

You can use both: SMS SDK for sending and webhooks, the provider SDK for everything else.

Next steps