@d3oxy/msg91

TypeScript SDK for MSG91 APIs - SMS OTP, WhatsApp, and more.

Features

- Full TypeScript support with comprehensive types
- SMS OTP: Send, Verify, and Resend OTPs
- WhatsApp: Send template messages with headers, buttons, carousels
- Fluent builder pattern for complex WhatsApp messages
- Automatic retries with exponential backoff
- Subpath exports for tree-shaking

Installation

``bash


npm

npm install @d3oxy/msg91

yarn

yarn add @d3oxy/msg91

pnpm

pnpm add @d3oxy/msg91

bun

bun add @d3oxy/msg91
`

Quick Start

`typescript
import { createMsg91Client } from '@d3oxy/msg91';

const msg91 = createMsg91Client({
authKey: 'your_auth_key_here',
});
`

SMS OTP

$3

`typescript
const { data, error } = await msg91.smsOtp.send({
templateId: 'your_template_id',
mobile: '919876543210',
otpLength: 6,
otpExpiry: 5, // minutes
});

if (error) {
console.error('Failed to send OTP:', error.message);
} else {
console.log('OTP sent successfully');
}
`

$3

`typescript
const { data, error } = await msg91.smsOtp.verify({
otp: '123456',
mobile: '919876543210',
});

if (error) {
console.error('Verification failed:', error.message);
} else {
console.log('OTP verified successfully');
}
`

$3

`typescript
const { data, error } = await msg91.smsOtp.resend({
mobile: '919876543210',
retryType: 'text', // or 'voice'
});
`

WhatsApp

$3

`typescript
const { data, error } = await msg91.whatsapp.send({
integratedNumber: '919876543210',
templateName: 'order_confirmation',
languageCode: 'en',
recipients: [
{
to: '919876543211',
components: {
body_1: { type: 'text', value: 'John' },
body_2: { type: 'text', value: 'Order #12345' },
},
},
],
});
`

$3

For complex messages with headers, buttons, or carousels, use the fluent builder:

`typescript
const message = msg91.whatsapp.template()
.setIntegratedNumber('919876543210')
.setTemplate('promo_offer', 'en')
.withImageHeader('https://example.com/banner.jpg')
.withBodyVariable(1, 'John')
.withBodyVariable(2, '20% OFF')
.withUrlButton(1, 'shop-now')
.withCopyCodeButton(2, 'SAVE20')
.addRecipient('919876543211')
.addRecipient(['919876543212', '919876543213'])
.build();

const { data, error } = await msg91.whatsapp.sendRaw(message);
`

$3

| Method | Description |
|--------|-------------|
| setIntegratedNumber(number) | Set your integrated WhatsApp number |
| setTemplate(name, lang?) | Set template name and language (default: 'en') |
| addRecipient(to, components?) | Add recipient(s) with optional components |
| withTextHeader(value) | Set text header |
| withImageHeader(url) | Set image header |
| withVideoHeader(url) | Set video header |
| withDocumentHeader(url, filename) | Set document header |
| withLocationHeader(location) | Set location header |
| withBodyVariable(index, value) | Set body variable (1-indexed) |
| withUrlButton(index, urlVar) | Set URL button |
| withCopyCodeButton(index, code) | Set copy code button |
| withCarouselCard(index, type, url) | Set carousel card header |
| build() | Build the final request |

Configuration Options

`typescript
const msg91 = createMsg91Client({
authKey: 'your_auth_key', // Required
baseUrl: '...', // SMS API base URL (optional)
whatsappBaseUrl: '...', // WhatsApp API base URL (optional)
timeout: 30000, // Request timeout in ms (default: 30000)
maxRetries: 2, // Max retry attempts (default: 2)
retryDelay: 1000, // Delay between retries in ms (default: 1000)
});
`

Subpath Imports

For tree-shaking or when you only need types:

`typescript
// SMS OTP types only
import type { SendOtpParams, VerifyOtpParams } from '@d3oxy/msg91/sms-otp';

// WhatsApp types only
import type {
SendWhatsAppMessageParams,
TemplateComponents,
WhatsAppMessageRequest,
} from '@d3oxy/msg91/whatsapp';

// WhatsApp template builder
import { WhatsAppTemplateBuilder } from '@d3oxy/msg91/whatsapp';
`

Error Handling

All methods return { data, error } for predictable error handling:

`typescript
const { data, error } = await msg91.smsOtp.send({ ... });

if (error) {
// error: { name: string, message: string, code?: string, statusCode?: number }
console.error(Error: ${error.message});
return;
}

// data is typed and available
console.log(data.message);
`

$3

`typescript
import {
Msg91Error, // Base error class
Msg91ApiError, // API returned an error
Msg91NetworkError, // Network/connection issues
Msg91RateLimitError, // Rate limited
Msg91ValidationError, // Input validation failed
Msg91ConfigError, // Configuration issues
} from 'msg91-js';
`

API Reference

$3

| Method | Description |
|--------|-------------|
| send(params) | Send OTP to a mobile number |
| verify(params) | Verify OTP entered by user |
| resend(params) | Resend OTP via text or voice |

$3

| Method | Description |
|--------|-------------|
| send(params) | Send WhatsApp template message |
| sendRaw(request) | Send raw WhatsApp request |
| template()` | Create a template builder |

License

MIT