kwtsms-convex

Send SMS and OTP via kwtSMS from Convex with a durable background queue, idempotent sends, rate caps, and test mode on by default.

Installation

npm install kwtsms-convex

Benefits

Use cases

how to send SMS from a Convex mutation

kwtsms-convex exposes a Kwtsms class you instantiate with your component reference and options. Call kwtsms.sendSms(ctx, { to, text, idempotencyKey }) inside any mutation; it returns the message ID immediately and queues the actual send via a background workpool. Repeated calls with the same idempotencyKey return the existing ID and send nothing new.

how to send OTP verification code via SMS in Convex

kwtsms-convex provides a sendOtp method that accepts a phone number, a 4-8 digit code, a language (en or ar), and an optional app name. It formats the code into a one-part SMS text and queues the send. The code and message body are never stored in the component tables and are never written to logs.

how to add rate limiting to SMS sending in Convex

kwtsms-convex enforces three built-in caps: perNumberPerHour (default 5), globalPerHour (default 100), and dailyPointsCap (default 500). These are counted in the component's own Convex table and throw a ConvexError with a code such as RATE_LIMIT_NUMBER or RATE_LIMIT_GLOBAL before the message is saved, so no credits are consumed.

Convex Auth custom phone SMS provider setup

kwtsms-convex works directly as a Convex Auth phone provider. Import the Phone provider from @convex-dev/auth/providers/Phone, then pass a sendVerificationRequest function that calls kwtsms.sendOtp(ctx, { to: identifier, code: token }). The maxAge and other settings are controlled by your Convex Auth configuration.

Frequently asked questions

Does kwtsms-convex work outside Kuwait?

Yes. kwtsms-convex defaults to allowedCountries: ['965'] to prevent credits from being spent on foreign numbers, but you can pass any array of country calling codes such as ['965', '971']. Phone numbers outside the allowed list throw a ConvexError with code COUNTRY_NOT_ALLOWED before the message is queued.

Will kwtsms-convex send actual SMS messages during development?

No. testMode is true by default. Every send is submitted to kwtSMS with test=1, which means the gateway accepts the message and holds credits but nothing reaches a handset. Set testMode: false on your Kwtsms instance when you are ready for live delivery.

What does the 'sent' status mean in kwtsms-convex?

In kwtsms-convex, the sent status means kwtSMS accepted the message from your deployment. It is not proof of delivery to the handset, which depends on the mobile operator. The failed status includes an errorCode field containing the kwtSMS ERR code such as ERR003.

Can kwtsms-convex charge credits more than once if a send fails?

No. kwtsms-convex retries only when an error occurs before the HTTP request leaves your deployment, up to 3 times. Once kwtSMS has seen the request, whether it returned any response, an ERR code, or timed out after sending, the result is marked final and the message is never retried.

What Convex version does kwtsms-convex require?

kwtsms-convex requires Convex 1.50 or newer. It also requires environment variables KWTSMS_USERNAME, KWTSMS_PASSWORD, and KWTSMS_SENDER_ID, which must be passed through convex/convex.config.ts because the component cannot read process.env directly.

Links

Components

Open-source building blocks for your Convex app

Browse components in this category.

Loading components