https://github.com/android-sms-gateway/client-ts
A JS/TS client library for sending and managing SMS messages via the SMS Gateway for Android™ API.
https://github.com/android-sms-gateway/client-ts
api-client javascript message-sending nodejs sms sms-api sms-client sms-gateway sms-integration
Last synced: 3 months ago
JSON representation
A JS/TS client library for sending and managing SMS messages via the SMS Gateway for Android™ API.
- Host: GitHub
- URL: https://github.com/android-sms-gateway/client-ts
- Owner: android-sms-gateway
- License: apache-2.0
- Created: 2023-12-09T16:38:18.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-04-07T22:46:35.000Z (3 months ago)
- Last Synced: 2025-04-10T04:15:01.948Z (3 months ago)
- Topics: api-client, javascript, message-sending, nodejs, sms, sms-api, sms-client, sms-gateway, sms-integration
- Language: TypeScript
- Homepage:
- Size: 125 KB
- Stars: 12
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📱 SMS Gateway for Android™ JS/TS API Client
[](https://www.npmjs.com/package/android-sms-gateway)
[](https://github.com/android-sms-gateway/client-ts/blob/master/LICENSE)
[](https://www.npmjs.com/package/android-sms-gateway)
[](https://github.com/android-sms-gateway/client-ts/issues)
[](https://github.com/android-sms-gateway/client-ts/stargazers)
[](https://www.typescriptlang.org/)
A TypeScript-first client for seamless integration with the [SMS Gateway for Android](https://sms-gate.app) API. Programmatically send SMS messages through your Android devices with strict typing and modern JavaScript features.
**Note**: The API doesn't provide CORS headers, so the library cannot be used in a browser environment directly.
## 📖 Table of Contents
- [📱 SMS Gateway for Android™ JS/TS API Client](#-sms-gateway-for-android-jsts-api-client)
- [📖 Table of Contents](#-table-of-contents)
- [✨ Features](#-features)
- [⚙️ Requirements](#️-requirements)
- [📦 Installation](#-installation)
- [🚀 Quickstart](#-quickstart)
- [Basic Usage](#basic-usage)
- [Webhook Management](#webhook-management)
- [🤖 Client Guide](#-client-guide)
- [Client Configuration](#client-configuration)
- [Core Methods](#core-methods)
- [Type Definitions](#type-definitions)
- [🌐 HTTP Clients](#-http-clients)
- [🔒 Security Notes](#-security-notes)
- [📚 API Reference](#-api-reference)
- [👥 Contributing](#-contributing)
- [Development Setup](#development-setup)
- [📄 License](#-license)
## ✨ Features
- **TypeScript Ready**: Full type definitions out of the box
- **Flexible HTTP Clients**: Works with any HTTP library (fetch, axios, node-fetch, etc.)
- **Promise-based API**: Async/await ready
- **Webhook Management**: Create, read, and delete webhooks
- **Customizable Base URL**: Point to different API endpoints
- **Server-Side Focus**: Designed for Node.js environments
## ⚙️ Requirements
- Node.js v18+
- npm/yarn/bun package manager
## 📦 Installation
```bash
npm install android-sms-gateway
# or
yarn add android-sms-gateway
# or
bun add android-sms-gateway
```
## 🚀 Quickstart
### Basic Usage
```typescript
import Client from 'android-sms-gateway';
// Create a fetch-based HTTP client
const httpFetchClient = {
get: async (url, headers) => {
const response = await fetch(url, {
method: "GET",
headers
});
return response.json();
},
post: async (url, body, headers) => {
const response = await fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body)
});
return response.json();
},
delete: async (url, headers) => {
const response = await fetch(url, {
method: "DELETE",
headers
});
return response.json();
}
};
// Initialize client
const api = new Client(
process.env.ANDROID_SMS_GATEWAY_LOGIN!,
process.env.ANDROID_SMS_GATEWAY_PASSWORD!,
httpFetchClient
);
// Send message
const message = {
phoneNumbers: ['+1234567890'],
message: 'Secure OTP: 123456 🔐'
};
async function sendSMS() {
try {
const state = await api.send(message);
console.log('Message ID:', state.id);
// Check status after 5 seconds
setTimeout(async () => {
const updatedState = await api.getState(state.id);
console.log('Message status:', updatedState.status);
}, 5000);
} catch (error) {
console.error('Sending failed:', error);
}
}
sendSMS();
```
### Webhook Management
```typescript
// Create webhook
const webhook = {
url: 'https://your-api.com/sms-callback',
event: WebHookEventType.SmsReceived,
};
api.registerWebhook(webhook)
.then(created => console.log('Webhook created:', created.id))
.catch(console.error);
// List webhooks
api.getWebhooks()
.then(webhooks => console.log('Active webhooks:', webhooks.length));
```
## 🤖 Client Guide
### Client Configuration
The `Client` class accepts the following constructor arguments:
| Argument | Description | Default |
| ------------ | -------------------------- | ---------------------------------------- |
| `login` | Username | **Required** |
| `password` | Password | **Required** |
| `httpClient` | HTTP client implementation | **Required** |
| `baseUrl` | API base URL | `"https://api.sms-gate.app/3rdparty/v1"` |
### Core Methods
| Method | Description | Returns |
| -------------------------------------------------- | ------------------------ | ----------------------- |
| `send(message: Message)` | Send SMS message | `Promise` |
| `getState(messageId: string)` | Check message status | `Promise` |
| `getWebhooks()` | List registered webhooks | `Promise` |
| `registerWebhook(request: RegisterWebHookRequest)` | Register new webhook | `Promise` |
| `deleteWebhook(webhookId: string)` | Remove webhook | `Promise` |
### Type Definitions
```typescript
interface Message {
id?: string | null;
message: string;
ttl?: number | null;
phoneNumbers: string[];
simNumber?: number | null;
withDeliveryReport?: boolean | null;
}
interface MessageState {
id: string;
state: ProcessState;
recipients: RecipientState[];
}
interface WebHook {
id: string;
event: WebHookEventType;
url: string;
}
```
For more details, see the [`domain.ts`](./src/domain.ts).
## 🌐 HTTP Clients
The library doesn't come with built-in HTTP clients. Instead, you should provide your own implementation of the `HttpClient` interface:
```typescript
interface HttpClient {
get(url: string, headers?: Record): Promise;
post(url: string, body: any, headers?: Record): Promise;
delete(url: string, headers?: Record): Promise;
}
```
## 🔒 Security Notes
⚠️ **Important Security Practices**
- Always store credentials in environment variables
- Never expose credentials in client-side code
- Use HTTPS for all production communications
## 📚 API Reference
For complete API documentation including all available methods, request/response schemas, and error codes, visit:
[📘 Official API Documentation](https://docs.sms-gate.app/integration/api/)
## 👥 Contributing
We welcome contributions! Please follow these steps:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
### Development Setup
```bash
git clone https://github.com/android-sms-gateway/client-ts.git
cd client-ts
bun install
bun run build
bun test
```
## 📄 License
Distributed under the Apache 2.0 License. See [LICENSE](LICENSE) for more information.
---
**Note**: Android is a trademark of Google LLC. This project is not affiliated with or endorsed by Google.