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

:speech_balloon: 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 :beer: by expl0it - @expl0it Credits to bootbot for letting me to copy this README.

License

MIT