Senders and E.164 numbers

Format recipients as E.164 and choose a sender: phone number, short code, alphanumeric sender ID, or messaging service.

Recipients are always E.164 numbers. Senders come in four kinds, and each provider supports a different set.

Recipients are E.164

to must match ^\+[1-9]\d{1,14}$: a +, a country code that does not start with 0, and at most 15 digits in total, with no spaces, dashes, or brackets. +14155550123 is valid. (415) 555-0123 and 0044 20 7946 0000 are not.

The check runs before any request, because the `+${string}` type does not prove a string is a valid number. Use isE164 to narrow user input:

import { isE164 } from "@opencoredev/sms-sdk";
import { sms } from "./sms";

const input: string = "+14155550123"; // for example, from a form field

if (!isE164(input)) {
  throw new Error("Enter the number with its country code, such as +14155550123.");
}

await sms.send({ to: input, body: "Thanks for signing up." });

isE164 checks format only. It cannot tell whether the number exists, is mobile, or can receive SMS. SMS SDK does not convert national formats to E.164. Use a phone number library for that.

Senders

from accepts one of four shapes, written as SmsFrom:

{ messagingService } means a Twilio Messaging Service SID, a Telnyx messaging profile ID (the profile’s number pool), or a Plivo Powerpack UUID.

Set a default on the adapter and override it per message:

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

const sms = createSmsClient({
  adapters: [
    twilio({
      accountSid: process.env.TWILIO_ACCOUNT_SID ?? "",
      authToken: process.env.TWILIO_AUTH_TOKEN ?? "",
      from: { messagingService: process.env.TWILIO_MESSAGING_SERVICE_SID ?? "" },
    }),
  ],
});

// Uses the Messaging Service
await sms.send({ to: "+14155550123", body: "Your code is 123456" });

// Uses an alphanumeric sender ID for this message only
await sms.send({ to: "+447700900123", from: { senderId: "Acme" }, body: "Your parcel is out for delivery." });

Which provider supports which sender

1. Telnyx requires a messaging profile for alphanumeric senders. Pass messagingProfileId to telnyx().

A sender type the primary adapter does not support throws UnsupportedFieldError (field: "from") before any request. With fallback on, SMS SDK skips adapters that cannot use the sender.

The provider decides what is sendable

These are format checks. SMS SDK cannot see whether a number belongs to your account, whether it is registered for 10DLC or verified for toll-free, or whether the destination country allows alphanumeric sender IDs. Many do not, including the United States and Canada.

When the provider refuses the sender, send() throws ProviderRejectedError with category: "sender". See Sender registration and consent.

Next steps

• Validation and encoding
• Sender registration and consent