node package manager


Node.js API Client Build Status

Send messages, check account balance, and manage contacts on


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.

Send an SMS message

See the Sending Messages section below for details.

    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'353861234567', {
    name: 'David Doran'

Add the contact to a group:'353861234567', {
    group: '888392630'

Remove a contact


Just remove the contact from a group:

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

Add a contact group'Customers', function (err, group) {
    console.log('Group alias: ' + group);

Remove a contact group


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 ''.

var message = new WebText.Message({
    to: '888392630',
    from: '*Alerts*',
    text: 'This is an example SMS message',
    id: 12345,
    email: '',
    delivery_delta: 20

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: ''}

email is the email address to which message receipts should be sent.

{email: ''}

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*/). /*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 /*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 around require(...)
  • Writing Mocha tests for Node.js
  • Setting up Travis CI testing for Node.js projects


This project is released under the MIT License.