Loading components
Send SMS and OTP via kwtSMS from Convex with a durable background queue, idempotent sends, rate caps, and test mode on by default.
npm install kwtsms-convexkwtsms-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.
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.
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.
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.
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.
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.
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.
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.
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.