Termii NodeJs Library

A Node client library for consuming the Termii API

Prerequisites

This project requires NodeJS (version 14 or later) and Yarn. Node and Yarn are really easy to install. To make sure you have them available on your machine, try running the following command.

$ yarn -v && node -v
1.22.19
v16.19.1

Termii NodeJs Library

Getting Started

You need to create a Termii account 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

To install and set up the library, run:

$ npm install @brvhprince/termii-js

Or if you prefer using Yarn:

$ yarn add @brvhprince/termii-js

Usage

Import and Initialize the library

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

provider.set_sender_id("new_sender_id")

Resources

Resources available on the API

Name	Description
Messaging	Messaging allows you to send messages across SMS and WhatsApp Channels Learn More
Token	Generate, send and verify one-time-passwords Learn More
Insights	Retrieve real-time delivery report of messages sent to customers as well as the status of their contacts Learn More
Middleware	Express Middleware to handle webhook requests

Messaging Documentation

Send messages to any country in the world across SMS and WhatsApp channel

Sender ID Documentation

A Sender ID is the name or number that identifies the sender of an SMS message

List Sender IDs

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

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

This API allows businesses send text messages to their customers across different messaging channels

Send Message

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

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

This API allows businesses send messages to customers using Termii's auto-generated messaging numbers that adapt to customers location.

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

Templates API helps businesses set a template for the one-time-passwords (pins) sent to their customers via whatsapp

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

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

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

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

const payload =  {
  phonebook_name: "Premium" 
}

const response = await provider.messaging.update_phonebook("phonebook_id",payload);

console.log(response.message) // Phonebook updated successfully

Delete Phonebook

const response = await provider.messaging.delete_phonebook("phonebook_id");

console.log(response.message) // Phonebook deleted successfully

Contacts Documentation

Contacts API allows you manage (i.e. edit, update, & delete) contacts in your phonebook.

List Contacts of Phonebook

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

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

const response = await provider.messaging.delete_contact("contact_id");

console.log(response.message) // Contact deleted successfully

Campaigns Documentation

Campaign API allows you to view, manage and send a campaign to a phonebook.

List Campaigns

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

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

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

Token allows businesses generate, send and verify one-time-passwords.

Send Token Documentation

The send token API allows businesses trigger one-time-passwords (OTP) across any available messaging channel on Termii.

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

The email token API enables you to send one-time-passwords to an email address

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

The voice token API enables you to generate and trigger one-time passwords (OTP) through the voice channel to a phone number

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

The voice call API enables you to send messages from your application through our voice channel to a phone number

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

This API returns OTP codes in JSON format which can be used within any web or mobile app.

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

Verify token API, checks tokens sent to customers and returns a response confirming the status of the token.

const payload = {
  pin_id: "pin_id",
  pin: 123456
}

const response = await provider.token.verify_token(payload);

console.log(response.verified) // True

Insights Documentation

Retrieve real-time delivery report of messages sent to customers as well as the status of their contacts

Balance Documentation

The Balance API returns your total balance and balance information from your wallet, such as currency.

    
const balance = await provider.insights.balance();

console.log(balance.balance) // 19.85

Search Documentation

The search API allows businesses verify phone numbers and automatically detect their status as well as current network

const response = await provider.insights.search_phone_number("phone_number");

console.log(response.status) // DND blacklisted

Status Documentation

The status API allows businesses to detect if a number is fake or has ported to a new network.

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

This Inbox API returns reports for messages sent across the sms, voice & whatsapp channels.

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

// 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 ❤️

Built With

TypeScript

Versioning

I use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

Prince Takyi - Initial work - Prince Takyi Akomea

See also the list of contributors who participated in this project.

@brvhprince/termii-js

Termii NodeJs Library

Prerequisites

Table of contents

Getting Started

Installation

Usage

Import and Initialize the library

Set a new Sender Id

Resources

Messaging Documentation

Sender ID Documentation

Messages Documentation

Send Message Without Sender ID Documentation

Send Message With Template Documentation

Phonebooks Documentation

Contacts Documentation

Campaigns Documentation

Token Documentation

Send Token Documentation

Email Token Documentation

Send Voice Token Documentation

Make Voice Call Documentation

Send In App Token Documentation

Verify Token Documentation

Insights Documentation

Balance Documentation

Search Documentation

Status Documentation

History Documentation

Middleware

Contributing

Built With

Versioning

Authors

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads