proovl

The unofficial library for Proovl SMS service which supports all API functionalities including HTTP hooks.

Features	Usage	Video Example	Getting Started	Documentation	Examples	Credits	License

💬 Questions / Comments? Join our Discord server!

Features

• Easy and fast SMS sending via Proovl
• SMS statuses checking
• Balance checking
• HTTP hooks via Express
• Easy configuration.
• And everything what Proovl's API offers!

Usage

$ npm i proovl --save

const Proovl = require('proovl')
 
const proovl = new Proovl('ACC_ID', 'ACC_TOKEN')
 
proovl.balance().then(balance => {
  console.log('Account balance: ' + balance)
}).catch(error => {
  console.error(error)
})

Video Example

Soon

Getting Started

• Install Proovl via NPM, create a new index.js, require Proovl and create a new instance using your Proovl Account'suser and token:

Note: If you don't know how to get these, just click here.

const Proovl = require('proovl')
 
const proovl = new Proovl('ACC_ID', 'ACC_TOKEN')
 
proovl.balance().then(balance => {
  console.log('Account balance: ' + balance)
}).catch(error => {
  console.error(error)
})

• Subscribe to incoming SMS:

const Proovl = require('proovl')
 
const proovl = new Proovl('ACC_ID', 'ACC_TOKEN')
 
proovl.start()
 
proovl.on('error', error => {
  console.error(error)
})
 
proovl.on('receive sms', data => {
  console.log(`
 
    New SMS!
 
    From: ${data.from}
    To: ${data.to}
    Text: ${data.text}
    ID: ${data.id}
 
  `)
})

• Set up webhooks and start the express server:

proovl.start()

• Start up your bot by running node:

$ node index.js
> Node-Proovl running on port 3000
> Proovl Webhook running on localhost:3000/webhook

• If you want to test your bot locally, install a localhost tunnel like ngrok and run it on your bot's port:

$ ngrok http 3000

Then use the provided HTTPS URL to config your webhook on Proovl's Dashboard. For example if the URL provided by ngrok is https://99b8d4c2.ngrok.io, use https://99b8d4c2.ngrok.io/webhook.

Documentation

Proovl Class

new Proovl(userId, authToken, options)

• accountId - the user ID
• accountToken - the authentication token
• options - Optional. An object containing zero or more of the following properties:
  • request - An instance of request which will be used by proovl for its HTTP requests. proovl will create its own if omitted.
  • timeout - The time in milliseconds that proovl will wait for HTTP requests to complete. Defaults to 50000 (50 seconds). Overrides any timeout option that was set on the passed-in request object.
  • userAgent - The user-agent value that proovl will use for its HTTP requests. Defaults to Mac OS X's user-agent. Overrides any headers['User-Agent'] option that was set on the passed-in request object.
  • localAddress - The local IP address that proovl will use for its HTTP requests. Overrides an localAddress option that was set on the passed-in request object.
  • webhook - Webhook URL path. Defaults to /webhook

Creates a new Proovl instance. Instantiates the new express app and all required webhooks.

If you want to specify a custom endpoint name for your webhook, you can do it with the webhook option.

.start([ port ])

Param	Type	Default	Required
port	number	3000	N

Starts the express server on the specified port. Defaults port to 3000.

.close()

Closes the express server (calls .close() on the server instance).

.balance() [Promise]

Param	Type	Default	Required

Returns account balance.

.sendSms(options) [Promise]

Parameters need to be object properties, not arguments

Param	Type	Default	Required
route	number	1	N
from	string		Y
to	string		Y
text	string		Y

Sends an SMS. Route should be a value beetwen 1 and 2. You can use static enum directly from Proovl class too: Proovl.ERoutes.Standard, Proovl.ERoutes.Economy From: The number you are sending SMS from. Without +, with country code, without any spaces. To: The number you are sending SMS to. Without +, with country code, without any spaces.

.checkSms(options) [Promise]

Parameters need to be object properties, not arguments

Param	Type	Default	Required
id	string		Y
phone	string		Y

Returns object with id, status, price properties. Example:

{ id: '123', status: 'Sent', price: '-0.0123' }

handleReports(data) and handleSms(data)

These functions are just emitting events.

---

Receive API

Use these methods to subscribe your bot to SMS's and SMS's delivery statuses.

.on(event, callback)

Param	Type	Default	Required
event	string		Y
callback	function		Y

Subscribe to an event emitted by the proovl module, and execute a callback when those events are emitted. Available events are:

Event	Description
error	Emitted when there is an error while parsing HTTP hook request
delivery reports	SMS status changed
receive sms	You got a new SMS

When these events ocurr, the specified callback will be invoked with 1 param: data (except for error: it will callback error param)

Param	Description
data	In receive sms: object containing from, to, text, id, token properties. In delivery reports: object containing token, id, status properties.
error	Error Object

.on() examples:

proovl.on('error', error => {
  console.error(error)
})
 
proovl.on('delivery reports', data => {
  console.log(`
 
    SMS Status Changed:
 
    New Status: ${data.status}
    ID: ${data.id}
 
  `)
})
 
proovl.on('receive sms', data => {
  console.log(`
 
    New SMS!
 
    From: ${data.from}
    To: ${data.to}
    Text: ${data.text}
    ID: ${data.id}
 
  `)
})

---

Bypassing Express

You may only want to use proovl for the Proovl related config and the simple to use API features but handle routing from somewhere else.

Or maybe you don't want to use express but a different HTTP server.

Just do not start the express server and handle routing somehow.

Examples

Check the examples directory to see more demos of:

• A balance checker
• SMS sender, SMS status checker
• How to use events

To run the examples, make sure to complete the ACC_ID and ACC_TOKEN fields, and then cd into the examples folder and run the desired example with node. For example:

$ cd examples
$ node balance.js

Credits

Made with 🍺 by expl0it - @expl0it Credits to bootbot for letting me to copy this README.

License

MIT