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

Table of contents

• Termii NodeJs Library
  • Prerequisites
  • Table of contents
  • Getting Started
  • Installation
  • Usage
    • Import and Initialize
    • Set Sender ID
  • Resources
    • Messaging
      • Sender ID
      • Messages
      • Send Message Without Sender ID
      • Send Message With Template
      • Phonebooks
      • Contacts
      • Campaigns
    • Token
      • Send Token
      • Email Token
      • Send Voice Token
      • Make Voice Call
      • Send In App Token
      • Verify Token
    • Insights
      • Account Balance
      • Phone Number Search
      • Phone Number Status
      • Inbox History
    • Express Middleware
  • Contributing
  • Built With
  • Versioning
  • Authors
  • License

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: "[email protected]",
  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 :heart:

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.

License

ISC License © Prince Takyi Akomea