webtext-api

Send messages, check account balance, and manage contacts on WebText.com.

npm install webtext-api
6 downloads in the last week
12 downloads in the last month

Node.js WebText.com API Client Build Status

Send messages, check account balance, and manage contacts on WebText.com.

Installation

The following will install this package and add it as a dependency to your project:

npm install --save

Usage

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.

Send an SMS message

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!');
});

Check account balance

wt.balance(function (err, balance) {
    if (!err) console.log('Account has ' + balance + ' credits');
});

Add a contact

wt.contacts.save('353861234567', {
    name: 'David Doran'
});

Add the contact to a group:

wt.contacts.save('353861234567', {
    group: '888392630'
});

Remove a contact

wt.contacts.remove('353861234567');

Just remove the contact from a group:

wt.contacts.remove('353861234567', {
    group: '888729566'
});

Add a contact group

wt.groups.save('Customers', function (err, group) {
    console.log('Group alias: ' + group);
});

Remove a contact group

wt.groups.remove('888729566');

Sending Messages

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}

Error Handling

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);
    }
});

API Reference

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 contact
  • group, 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*/).

Learnings

  • Using the npm request package for making HTTP requests
  • Publishing packages to npm
  • Implementing 'optional dependencies' with try/catch around require(...)
  • Writing Mocha tests for Node.js
  • Setting up Travis CI testing for Node.js projects

License

This project is released under the MIT License.

npm loves you