Node.js WebText.com API Client
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 = ;
Create a WebText
object with your API User and Password:
var user = 'bw13cexH' password = '5yw8Vhc3'; var wt = user password;
Now you can call the various API methods.
Send an SMS message
See the Sending Messages section below for details.
wt;
Check account balance
wt;
Add a contact
wtcontacts;
Add the contact to a group:
wtcontacts;
Remove a contact
wtcontacts;
Just remove the contact from a group:
wtcontacts;
Add a contact group
wtgroups;
Remove a contact group
wtgroups;
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 = to: '888392630' from: '*Alerts*' text: 'This is an example SMS message' id: 12345 email: 'webtext-receipts@example.com' delivery_delta: 20; wt;
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 2016delivery_time: '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 nowdelivery_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 hoursvalidity: 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 = ; catch e console;
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;
API Reference
wt // => boolean
Enable or disable HTTPS. Returns whether HTTPS is currently enabled.
wt // => {username: ..., password: ...}
Set the API credentials to use. Returns the current credentials.
wt
Get account balance. callback
is of the form function(err /*WebTextError*/, balance /*number*/)
.
wt
wt
Send a message. If message
is an object then it will be passed to new WebText.Message
. callback
is function(err /*WebTextError*/)
.
wtcontacts
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
wtcontacts
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
wtgroups
Add a contact group. callback
is function(err /*WebTextError*/, alias /*number*/)
.
wtgroups
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
aroundrequire(...)
- Writing Mocha tests for Node.js
- Setting up Travis CI testing for Node.js projects
License
This project is released under the MIT License.