@qrvey/sms

@qrvey/sms is a lightweight and reliable library to send manage sms messages. It supports different clients such SNS (AWS), ACS (Azure), Twilio, and Vonage.

Installation

You can install the @qrvey/sms package via npm. Run the following command in your terminal:

npm install @qrvey/sms

Peer Dependencies

This package has the following peer dependencies:

• @aws-sdk/client-sns (v3.x) for interacting with AWS SNS.
• @azure/communication-sms (v1.x) for interacting with Azure Communication Services.
• @vonage/server-sdk (v3.x) and @vonage/auth (v1.x) for interacting with Vonage.
• twilio (v5.x) for interacting with Twilio.

Configuration

To work properly, the package need some env variables. To set the sms provider, you must set the SMS_PROVIDER env variable with one of these values:

• AWS
• AZURE
• TWILIO
• VONAGE

In case the SMS_PROVIDER env variable is set with an unknown value, you will get a UnknownProvider error. Depending on the provider you must set some variables:

AWS

If you set SMS_PROVIDER = AWS, the following env variables are required:

• SMS_PROVIDER_USERNAME which is AWS_ACCESS_KEY_ID in aws context.
• SMS_PROVIDER_PASSWORD which is AWS_SECRET_ACCESS_KEY in aws context.
• SMS_PROVIDER_REGION which is AWS_REGION in aws context.

AZURE

If you set SMS_PROVIDER = AZURE, the following env variables are required:

• SMS_PROVIDER_USERNAME which is resource-name in azure connectionString context.
• SMS_PROVIDER_PASSWORD which is access-key in azure connectionString context.
• SMS_PROVIDER_FROM_NUMBER which is the ACS-registered number in azure context. This must be in E.164 format, example: "+123456789"

Note: The azure connectionString for Azure Communication Services looks like this: endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>.

TWILIO

If you set SMS_PROVIDER = TWILIO, the following env variables are required:

• SMS_PROVIDER_USERNAME which is TWILIO_ACCOUNT_SID in twilio context.
• SMS_PROVIDER_PASSWORD which is TWILIO_AUTH_TOKEN in twilio context.

VONAGE

If you set SMS_PROVIDER = VONAGE, the following env variables are required:

• SMS_PROVIDER_USERNAME which is VONAGE_API_KEY in vonage context.
• SMS_PROVIDER_PASSWORD which is VONAGE_API_SECRET in vonage context.
• SMS_PROVIDER_FROM_NUMBER which can be one of the next:
  • An alphanumeric ID. Example: "MyCompanyBrand"
  • A Vonage-registered number in E.164 format. Example: "+123456789".
  • A local-registered short number. Example: "12345".

API Documentation

Available Methods

send: (phones: string[], message: string) => Promise<SendResult>;

Example Usage

const phones: string[] = [
    "+123456789",
    "+9876543210"
];
const message = "Hello world!";

const smsSenderService = new SMSSenderService();
await smsSenderService.send(phones, message);