Send messages, check account balance, and manage contacts on WebText.com.
The following will install this package and add it as a dependency to your project:
npm install --save
Require this package after installing with npm:
var WebText = require('webtext-api');
Create a WebText
object with your API User and Password:
var user = 'bw13cexH',
password = '5yw8Vhc3';
var wt = new WebText(user, password);
Now you can call the various API methods.
See the Sending Messages section below for details.
wt.send({
text: 'First message from WebText!',
to: '353861234567'
}, function (err) {
if (!err) console.log('Message sent successfully!');
});
wt.balance(function (err, balance) {
if (!err) console.log('Account has ' + balance + ' credits');
});
wt.contacts.save('353861234567', {
name: 'David Doran'
});
Add the contact to a group:
wt.contacts.save('353861234567', {
group: '888392630'
});
wt.contacts.remove('353861234567');
Just remove the contact from a group:
wt.contacts.remove('353861234567', {
group: '888729566'
});
wt.groups.save('Customers', function (err, group) {
console.log('Group alias: ' + group);
});
wt.groups.remove('888729566');
The following message will be delivered 20 minutes from now, to group 888392630, with sender '*Alerts*', with the id '12345', and receipts will be delivered to 'webtext-receipts@example.com'.
var message = new WebText.Message({
to: '888392630',
from: '*Alerts*',
text: 'This is an example SMS message',
id: 12345,
email: 'webtext-receipts@example.com',
delivery_delta: 20
});
wt.send(message);
Here is the full list of supported properties with examples:
Required: to
is a phone number, array of phone numbers, or an array of group aliases.
{to: ['353863123456', '353863654321', '353861940728']}
Required: text
is the text of the message.
{text: 'Thanks for subscribing to SMS alerts!'}
unicode
is the unicode text of the message (either text
or unicode
must be given).
{unicode: 'Μιλάς Ελληνικά'}
tag
(or from
) is the name that will appear as the message sender.
{tag: 'Alerts System'}
id
is a unique numeric id for the message.
{id: '201300001'}
url
is the URL to which message receipts should be sent.
{url: 'https://example.com/webtext-receipts'}
email
is the email address to which message receipts should be sent.
{email: 'webtext-receipts@example.com'}
delivery_time
is the date when the message should be sent, given by a Date
object.
//Send the message on the 15th of January 2016
{delivery_time: new Date('2016-01-15 18:00:00')}
delivery_delta
is the number of minutes to wait before sending the message.
//Send the message 10 minutes from now
{delivery_delta: 10}
validity
is the number of minutes the SMS is valid for (after which delivery will not be attempted).
//Message is valid for 5 hours
{validity: 300}
There are only two types of errors you need to handle:
The WebText.Message
constructor may throw a validation error, which you can handle like this:
try {
var m = new WebText.Message();
} catch (e) {
console.log('Validation error: ' + e.message);
}
If you use the WebText#send
method directly without a message object then the error above is handled for you.
The various API methods take a callback
parameter, which will be called with a WebTextError
if something goes wrong:
wt.balance(function (err, balance) {
if (err) {
console.log('Error getting balance: ' + err.message);
}
});
wt.https(enabled /*boolean*/) // => boolean
Enable or disable HTTPS. Returns whether HTTPS is currently enabled.
wt.credentials(username /*string*/, password /*string*/) // => {username: ..., password: ...}
Set the API credentials to use. Returns the current credentials.
wt.balance(callback /*optional*/)
Get account balance. callback
is of the form function(err /*WebTextError*/, balance /*number*/)
.
wt.send(message /*object*/, callback /*optional*/)
wt.send(message /*WebText.Message*/, callback /*optional*/)
Send a message. If message
is an object then it will be passed to new WebText.Message
. callback
is function(err /*WebTextError*/)
.
wt.contacts.save(number /*string*/, params /*optional object*/, callback /*optional*/)
Add or update a contact. callback
is function(err /*WebTextError*/)
.
params
may contain the following optional properties:
name
, the name of the contactgroup
, the alias id of a group to add the contact to
wt.contacts.remove(number /*string*/, params /*optional object*/, callback /*optional*/)
Remove a contact. callback
is function(err /*WebTextError*/)
.
params
may contain the following optional properties:
group
, the alias id of a group to remove the contact from
wt.groups.save(name /*string*/, callback /*optional*/)
Add a contact group. callback
is function(err /*WebTextError*/, alias /*number*/)
.
wt.groups.remove(group /*number*/, callback /*optional*/)
Remove a contact group. callback
is function(err /*WebTextError*/)
.
- Using the npm request package for making HTTP requests
- Publishing packages to npm
- Implementing 'optional dependencies' with
try/catch
aroundrequire(...)
- Writing Mocha tests for Node.js
- Setting up Travis CI testing for Node.js projects
This project is released under the MIT License.