[comment]: <> (HEAD)

TextMagic JavaScript SDK

This library provides you with an easy way of sending SMS and receiving replies by integrating the TextMagic SMS Gateway into your JavaScript application.

What Is TextMagic?

TextMagic's application programming interface (API) provides the communication link between your application and TextMagic's SMS Gateway, allowing you to send and receive text messages and to check the delivery status of text messages you've already sent.

[comment]: <> (/HEAD)

Requirements

- Node.js 18.0.0 or later
- npm or yarn for package management

Installation

$3

``bash
npm install textmagic-client --save
`

$3

`bash
yarn add textmagic-client
`

Development

This SDK uses Babel to transpile modern ES6+ code to CommonJS for maximum compatibility.

$3

The SDK source code is written in ES6+ (located in src/) and is automatically transpiled to ES5/CommonJS (in dist/) during installation:

`bash
npm install # Automatically runs: npm run build
`

$3

If you need to rebuild the SDK manually:

`bash
npm run build
`

This will transpile all files from src/ to dist/ using Babel.

Quick Start

$3

`javascript
const TextMagicClient = require('textmagic-client');

// Get your credentials from: https://app.textmagic.com/settings/api
const defaultClient = TextMagicClient.ApiClient.instance;
const BasicAuth = defaultClient.authentications['BasicAuth'];

BasicAuth.username = 'YOUR_USERNAME';
BasicAuth.password = 'YOUR_API_KEY';

const api = new TextMagicClient.TextMagicApi();

// Test connection
api.ping()
.then(data => {
console.log('Ping successful:', data.ping);
})
.catch(error => {
console.error('API Error:', error);
});
`

$3

`javascript
const TextMagicClient = require('textmagic-client');

async function main() {
const defaultClient = TextMagicClient.ApiClient.instance;
const BasicAuth = defaultClient.authentications['BasicAuth'];

BasicAuth.username = 'YOUR_USERNAME';
BasicAuth.password = 'YOUR_API_KEY';

const api = new TextMagicClient.TextMagicApi();

try {
// Test connection
const pingResult = await api.ping();
console.log('Ping successful:', pingResult.ping);
} catch (error) {
console.error('API Error:', error);
}
}

main();
`

$3

`javascript
const TextMagicClient = require('textmagic-client');

async function sendMessage() {
const defaultClient = TextMagicClient.ApiClient.instance;
const BasicAuth = defaultClient.authentications['BasicAuth'];

BasicAuth.username = 'YOUR_USERNAME';
BasicAuth.password = 'YOUR_API_KEY';

const api = new TextMagicClient.TextMagicApi();

const sendMessageRequest = new TextMagicClient.SendMessageRequest();
sendMessageRequest.text = 'Hello from TextMagic Node.js SDK!';
sendMessageRequest.phones = '+19993322111,+19993322110';

try {
const result = await api.sendMessage(sendMessageRequest);
console.log('Message sent! Session ID:', result.id);
} catch (error) {
console.error('Failed to send message:', error);
}
}

sendMessage();
`

$3

`javascript
const TextMagicClient = require('textmagic-client');

async function getMessages() {
const defaultClient = TextMagicClient.ApiClient.instance;
const BasicAuth = defaultClient.authentications['BasicAuth'];

BasicAuth.username = 'YOUR_USERNAME';
BasicAuth.password = 'YOUR_API_KEY';

const api = new TextMagicClient.TextMagicApi();

try {
const result = await api.getAllOutboundMessages(1, 10);

result.resources.forEach(message => {
console.log('Message ID:', message.id);
console.log('Text:', message.text);
console.log('Status:', message.status);
console.log('---');
});
} catch (error) {
console.error('Error:', error);
}
}

getMessages();
`

$3

`javascript
const TextMagicClient = require('textmagic-client');
const fs = require('fs');

async function uploadAvatar() {
const defaultClient = TextMagicClient.ApiClient.instance;
const BasicAuth = defaultClient.authentications['BasicAuth'];

BasicAuth.username = 'YOUR_USERNAME';
BasicAuth.password = 'YOUR_API_KEY';

const api = new TextMagicClient.TextMagicApi();

try {
const fileStream = fs.createReadStream('avatar.jpg');
const result = await api.uploadListAvatar(fileStream, 3223); // 3223 is sample list ID
console.log('Avatar uploaded successfully!');
} catch (error) {
console.error('Upload failed:', error);
}
}

uploadAvatar();
`

Error Handling

The SDK uses Promises and can throw errors that should be properly handled:

`javascript
const TextMagicClient = require('textmagic-client');

async function handleErrors() {
const defaultClient = TextMagicClient.ApiClient.instance;
const BasicAuth = defaultClient.authentications['BasicAuth'];

BasicAuth.username = 'YOUR_USERNAME';
BasicAuth.password = 'YOUR_API_KEY';

const api = new TextMagicClient.TextMagicApi();

try {
const result = await api.sendMessage({
text: 'Test message',
phones: '+1234567890'
});
console.log('Success:', result);
} catch (error) {
// Handle different types of errors
if (error.response) {
// API returned an error response
console.error('API Error:', error.response.status);
console.error('Error details:', error.response.body);
} else if (error.request) {
// Request was made but no response received
console.error('Network Error:', error.message);
} else {
// Something else went wrong
console.error('Error:', error.message);
}
}
}

handleErrors();
`

$3

- 401 Unauthorized - Invalid credentials
- 400 Bad Request - Invalid parameters
- 404 Not Found - Resource not found
- 429 Too Many Requests - Rate limit exceeded
- 500 Internal Server Error - Server error

API Documentation

For complete API documentation, including all available methods, parameters, and response formats, please visit:

- 📖 TextMagic API Documentation
- 🔗 API Reference

$3

The SDK provides access to all TextMagic API endpoints through the TextMagicApi class. Some commonly used methods include:

Messaging:
- sendMessage(request) - Send SMS messages
- getAllOutboundMessages(page, limit) - Get sent messages
- getAllInboundMessages(page, limit) - Get received messages
- deleteMessage(id) - Delete a message

Contacts:
- createContact(request) - Create a new contact
- getContact(id) - Get contact details
- updateContact(id, request) - Update contact information
- deleteContact(id) - Delete a contact
- getAllContacts(page, limit) - Get all contacts

Lists:
- createList(request) - Create a contact list
- getList(id) - Get list details
- getAllLists(page, limit) - Get all lists
- assignContactsToList(request) - Add contacts to a list

Account:
- ping() - Test API connection
- getUser() - Get account information
- getUserBalance() - Get account balance

For a complete list of available methods, please refer to the generated SDK documentation in the docs/ directory.

Migration Guide from v2.x to v3.x

$3

#### Node.js Version Requirement

v2.x:
`json
"node": ">=6.0.0"
`

v3.x:
`json
"node": ">=18.0.0"
`

Action Required: Upgrade your Node.js version to 18.0.0 or later.

`bash


Check your Node.js version

node -v

Should output: v18.x.x or higher

`

#### Dependencies Update

v2.x:
`json
"superagent": "^3.5.2"
`

v3.x:
`json
"superagent": "^10.2.2",
"@babel/cli": "^7.24.0"
`

Note:
- Superagent 10.x includes modern features, better TypeScript support, and security improvements.
- Babel is now used to transpile ES6+ code to CommonJS for maximum compatibility.

$3

✅ Module structure - No changes required:
`javascript
const TextMagicClient = require('textmagic-client');
const api = new TextMagicClient.TextMagicApi();
`

✅ Authentication - Configuration remains the same:
`javascript
const BasicAuth = defaultClient.authentications['BasicAuth'];
BasicAuth.username = 'YOUR_USERNAME';
BasicAuth.password = 'YOUR_API_KEY';
`

✅ API Methods - All methods remain the same:
`javascript
api.sendMessage(request);
api.getAllOutboundMessages(page, limit);
api.getContact(id);
// ... all other methods unchanged
`

$3

1. Upgrade Node.js to 18.0.0+
`bash
# Using nvm (recommended)
nvm install 18
nvm use 18

# Verify
node -v
`

2. Update Package Dependencies
`bash
# Update to latest version
npm install textmagic-client@latest --save

# Or update all dependencies
npm update
`

3. Update Your Code to Use async/await (Recommended)

Before (v2.x):
`javascript
api.ping().then(function(data) {
console.log(data.ping);
}).catch(function(err) {
console.error(err);
});
`

After (v3.x):
`javascript
try {
const data = await api.ping();
console.log(data.ping);
} catch (error) {
console.error(error);
}
`

4. Test Your Application
`bash
# Run your tests
npm test

# Or test manually
node your_script.js
``

$3

| Feature | v2.x | v3.x | Compatible? |
|---------------|------|------|-------------|
| Node.js 6-16 | ✅ | ❌ | ❌ No |
| Node.js 18+ | ✅ | ✅ | ✅ Yes |
| API Methods | Same | Same | ✅ Yes |
| Models | Same | Same | ✅ Yes |
| Authentication| Same | Same | ✅ Yes |
| Promises | ✅ | ✅ | ✅ Yes |
| async/await | ✅ | ✅ | ✅ Yes |

$3

- 📖 Full Documentation
- 💬 Support
- 🐛 Report Issues
[comment]: <> (FOOTER)

License

The library is available as open source under the terms of the MIT License.

[comment]: <> (/FOOTER)