@brvhprince/termii-js
Version:
JavaScript SDK for Termii Provider
578 lines (377 loc) • 16.7 kB
Markdown
# Termii NodeJs Library
> A Node client library for consuming the [Termii API](https://www.developers.termii.com/)
## Prerequisites
This project requires NodeJS (version 14 or later) and Yarn.
[Node](http://nodejs.org/) and [Yarn](https://yarnpkg.com/) are really easy to install.
To make sure you have them available on your machine,
try running the following command.
```sh
$ yarn -v && node -v
1.22.19
v16.19.1
```
## Table of contents
- [Termii NodeJs Library](#Termii-NodeJs-Library)
- [Prerequisites](#prerequisites)
- [Table of contents](#table-of-contents)
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Usage](#usage)
- [Import and Initialize](#import-and-initialize-the-library)
- [Set Sender ID](#set-a-new-sender-id)
- [Resources](#resources)
- [Messaging](#messaging)
- [Sender ID](#sender-id-documentation)
- [Messages](#messages-documentation)
- [Send Message Without Sender ID](#send-message-without-sender-id-documentation)
- [Send Message With Template](#send-message-with-template-documentation)
- [Phonebooks](#phonebooks-documentation)
- [Contacts](#contacts-documentation)
- [Campaigns](#campaigns-documentation)
- [Token](#token-documentation)
- [Send Token](#send-token-documentation)
- [Email Token](#email-token-documentation)
- [Send Voice Token](#send-voice-token-documentation)
- [Make Voice Call](#make-voice-call-documentation)
- [Send In App Token](#send-in-app-token-documentation)
- [Verify Token](#verify-token-documentation)
- [Insights](#insights-documentation)
- [Account Balance](#balance-documentation)
- [Phone Number Search](#search-documentation)
- [Phone Number Status](#status-documentation)
- [Inbox History](#history-documentation)
- [Express Middleware](#middleware)
- [Contributing](#contributing)
- [Built With](#built-with)
- [Versioning](#versioning)
- [Authors](#authors)
- [License](#license)
## Getting Started
You need to create a [Termii account](https://accounts.termii.com/#/register) if you don't have one already,
to get your API Key, Sender ID and Secret key.
> Termii-js was made for the browser, but works in any JavaScript runtime.
## Installation
**BEFORE YOU INSTALL:** please read the [prerequisites](#prerequisites)
To install and set up the library, run:
```sh
$ npm install @brvhprince/termii-js
```
Or if you prefer using Yarn:
```sh
$ yarn add @brvhprince/termii-js
```
## Usage
### Import and Initialize the library
```javascript
// using ES6 modules
import { Termii } from '@brvhprince/termii-js'
// using CommonJS modules
const { Termii } = require("@brvhprince/termii-js");
// Initialize
const provider = new Termii("api_key_here", "sender_id");
```
### Set a new Sender Id
```javascript
provider.set_sender_id("new_sender_id")
```
# Resources
Resources available on the API
| Name | Description |
|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Messaging](#messaging-documentation) | Messaging allows you to send messages across SMS and WhatsApp Channels [Learn More](https://www.developers.termii.com/switch) |
| [Token](#token-documentation) | Generate, send and verify one-time-passwords [Learn More](https://www.developers.termii.com/token) |
| [Insights](#insights-documentation) | Retrieve real-time delivery report of messages sent to customers as well as the status of their contacts [Learn More](https://www.developers.termii.com/insights) |
| [Middleware](#middleware) | Express Middleware to handle webhook requests |
## Messaging [Documentation](https://www.developers.termii.com/switch)
Send messages to any country in the world across SMS and WhatsApp channel
### Sender ID [Documentation](https://www.developers.termii.com/sender-id)
A Sender ID is the name or number that identifies the sender of an SMS message
* **List Sender IDs**
```javascript
// returns paginated results of 15 items per page
const senderIds = await provider.messaging.list_sender_ids();
// get page
const nextSenderIds = await provider.messaging.list_sender_ids(2);
```
* **Request a new sender Id**
```javascript
const payload = {
// between 3 and 11 characters
sender_id: "Penny",
usecase: "Send promotional messages",
company: "Pennycodes"
}
const response = await provider.messaging.request_sender_id(payload);
console.log(response.code) // ok
```
### Messages [Documentation](https://www.developers.termii.com/messaging)
This API allows businesses send text messages to their customers across different messaging channels
* **Send Message**
```javascript
const payload = {
to: "233552345567",
sms: "Hello there, welcome to Termii"
}
const response = await provider.messaging.send(payload);
console.log(response.code) // ok
```
* **Send Bulk Message**
```javascript
const payload = {
to: ["23490555546", "23423490126999","23490555546"],
sms: "Hello there, welcome to Termii"
}
const response = await provider.messaging.send_bulk(payload);
console.log(response.code) // ok
```
### Send Message Without Sender ID [Documentation](https://www.developers.termii.com/number)
This API allows businesses send messages to customers using Termii's auto-generated messaging numbers that adapt to customers location.
```javascript
const payload = {
to: "233552345567",
sms: "Hello there, welcome to Termii"
}
const response = await provider.messaging.send_without_sender_id(payload);
console.log(response.code) // ok
```
### Send Message With Template [Documentation](https://www.developers.termii.com/templates)
Templates API helps businesses set a template for the one-time-passwords (pins) sent to their customers via whatsapp
```javascript
const payload = {
phone_number: "233552345567",
device_id: "device_one",
template_id: "template_one",
data: {
product_name: "Termii",
otp : 120435,
expiry_time: "10 minutes"
}
}
const response = await provider.messaging.send_with_template(payload);
console.log(response.code) // ok
```
### Phonebooks [Documentation](https://www.developers.termii.com/phonebook)
Create, view & manage phonebooks using these APIs. Each phonebook can be identified by a unique ID, which makes it easier to edit or delete a phonebook.
* **List Phonebooks**
```javascript
// returns paginated results of 15 items per page
const phonebooks = await provider.messaging.list_phonebooks();
// get page
const nextPhonebooks = await provider.messaging.list_phonebooks(2);
```
* **Create Phonebook**
```javascript
const payload = {
phonebook_name: "Royals",
description: "My royal leads"
}
const response = await provider.messaging.create_phonebook(payload);
console.log(response.message) // Phonebook added successfully
```
* **Update Phonebook**
```javascript
const payload = {
phonebook_name: "Premium"
}
const response = await provider.messaging.update_phonebook("phonebook_id",payload);
console.log(response.message) // Phonebook updated successfully
```
* **Delete Phonebook**
```javascript
const response = await provider.messaging.delete_phonebook("phonebook_id");
console.log(response.message) // Phonebook deleted successfully
```
### Contacts [Documentation](https://www.developers.termii.com/contacts)
Contacts API allows you manage (i.e. edit, update, & delete) contacts in your phonebook.
* **List Contacts of Phonebook**
```javascript
// returns paginated results of 15 items per page
const contacts = await provider.messaging.list_contacts("phonebook_id");
// get page
const nextContacts = await provider.messaging.list_contacts("phonebook_id", 2);
```
* **Create Contact**
```javascript
const payload = {
phone_number: "556789909",
country_code: "233"
}
const response = await provider.messaging.create_contact("phonebook_id",payload);
console.log(response.data.id) // 3647982
```
* **Delete Contact**
```javascript
const response = await provider.messaging.delete_contact("contact_id");
console.log(response.message) // Contact deleted successfully
```
### Campaigns [Documentation](https://www.developers.termii.com/campaign)
Campaign API allows you to view, manage and send a campaign to a phonebook.
* **List Campaigns**
```javascript
// returns paginated results of 15 items per page
const campaigns = await provider.messaging.list_campaigns();
// get page
const nextCampaigns = await provider.messaging.list_campaigns(2);
```
* **Fetch Campaign History**
```javascript
// returns paginated results of 15 items per page
const history = await provider.messaging.get_campaign_history("campaign_id");
// get page
const nextHistory = await provider.messaging.get_campaign_history("campaign_id", 2);
```
* **Send Campaign**
```javascript
const payload = {
phone_number: "556789909",
country_code: "233",
message: "Hello, Welcome to Termii",
phonebook_id: "phonebook_id",
campaign_type: "personalized"
}
const response = await provider.messaging.send_campaign(payload);
console.log(response.message) // Your campaign has been scheduled
```
## Token [Documentation](https://www.developers.termii.com/token)
Token allows businesses generate, send and verify one-time-passwords.
### Send Token [Documentation](https://www.developers.termii.com/send-token)
The send token API allows businesses trigger one-time-passwords (OTP) across any available messaging channel on Termii.
```javascript
const payload = {
to: "23490126727",
pin_length: 6,
message_text: "Your pin is"
}
const response = await provider.token.send_token(payload);
console.log(response.pinId) // 29ae67c2-c8e1-4165-8a51-8d3d7c298081
```
### Email Token [Documentation](https://www.developers.termii.com/email-token)
The email token API enables you to send one-time-passwords to an email address
```javascript
const payload = {
email_address: "test@termii.com",
code: "092471",
email_configuration_id: "email_configuration_id_from_dashboard"
}
const response = await provider.token.email_token(payload);
console.log(response.code) // ok
```
### Send Voice Token [Documentation](https://www.developers.termii.com/voice-token)
The voice token API enables you to generate and trigger one-time passwords (OTP) through the voice channel to a phone number
```javascript
const payload = {
phone_number: "23490126727"
}
const response = await provider.token.send_voice_token(payload);
console.log(response.pinId) // 29ae67c2-c8e1-4165-8a51-8d3d7c298081
```
### Make Voice Call [Documentation](https://www.developers.termii.com/voice-call)
The voice call API enables you to send messages from your application through our voice channel to a phone number
```javascript
const payload = {
phone_number: "23490126727",
code: 1223
}
const response = await provider.token.make_voice_call(payload);
console.log(response.pinId) // 29ae67c2-c8e1-4165-8a51-8d3d7c298081
```
### Send In App Token [Documentation](https://www.developers.termii.com/in-app-token)
This API returns OTP codes in JSON format which can be used within any web or mobile app.
```javascript
const payload = {
phone_number: "23490126727",
pin_length: 6
}
const response = await provider.token.send_in_app_token(payload);
console.log(response.status) // success
console.log(response.data.otp) // 522726
```
### Verify Token [Documentation](https://www.developers.termii.com/verify-token)
Verify token API, checks tokens sent to customers and returns a response confirming the status of the token.
```javascript
const payload = {
pin_id: "pin_id",
pin: 123456
}
const response = await provider.token.verify_token(payload);
console.log(response.verified) // True
```
## Insights [Documentation](https://www.developers.termii.com/insights)
Retrieve real-time delivery report of messages sent to customers as well as the status of their contacts
### Balance [Documentation](https://www.developers.termii.com/balance)
The Balance API returns your total balance and balance information from your wallet, such as currency.
```javascript
const balance = await provider.insights.balance();
console.log(balance.balance) // 19.85
```
### Search [Documentation](https://www.developers.termii.com/search)
The search API allows businesses verify phone numbers and automatically detect their status as well as current network
```javascript
const response = await provider.insights.search_phone_number("phone_number");
console.log(response.status) // DND blacklisted
```
### Status [Documentation](https://www.developers.termii.com/status)
The status API allows businesses to detect if a number is fake or has ported to a new network.
```javascript
const payload = {
phone_number: "523353245594",
country_code: "GH"
}
const response = await provider.insights.status_phone_number(payload);
console.log(response.result) // {@returns typeof array}
```
### History [Documentation](https://www.developers.termii.com/history)
This Inbox API returns reports for messages sent across the sms, voice & whatsapp channels.
```javascript
const inbox = await provider.insights.history();
console.log(inbox) // {@returns typeof array}
```
## Middleware
Express Middleware to handle Webhook Events
Add your webhook url in your [Termii Developer Console](https://accounts.termii.com/#/account/webhook/config)
```javascript
// using ES6 modules
import { Webhook } from '@brvhprince/termii-js'
// using CommonJS modules
const { Webhook } = require("@brvhprince/termii-js");
// Initialize
const provider = new Webhook("secret_key");
//Inbound-Message Received
provider.on("inbound", data => {
// Act
console.log("Here We are!");
});
//Outbound Message (Delivery Report)
provider.on("outbound", data => {
// Act
console.log("Here We are!");
});
//Device offline Notification
provider.on("device_status", data => {
// Act
console.log("Here We are!");
});
// Hooks with Express
app.post("/my/webhook/url", provider.middleware);
```
## Contributing
Please do :heart:
## Built With
* [TypeScript](https://www.typescriptlang.org/)
## Versioning
I use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/brvhprince/termii-js/tags).
## Authors
* **Prince Takyi** - *Initial work* - [Prince Takyi Akomea](https://github.com/brvprince)
See also the list of [contributors](https://github.com/brvhprince/termii-js/contributors) who participated in this project.
## License
[ISC License](LICENSE) © Prince Takyi Akomea