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.

1$ yarn -v && node -v
21.22.19
3v16.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:

1$ npm install @brvhprince/termii-js

Or if you prefer using Yarn:

1$ yarn add @brvhprince/termii-js

Usage

Import and Initialize the library

1// using ES6 modules
2import { Termii } from '@brvhprince/termii-js'
3
4// using CommonJS modules
5const { Termii } = require("@brvhprince/termii-js");
6
7// Initialize
8
9const provider = new Termii("api_key_here", "sender_id");

Set a new Sender Id

1provider.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

  1
  2// returns paginated results of 15 items per page
  3const senderIds = await provider.messaging.list_sender_ids();
  4
  5// get page
  6const nextSenderIds = await provider.messaging.list_sender_ids(2); 

• Request a new sender Id

  1
  2const payload = {
  3  // between 3 and 11 characters
  4  sender_id: "Penny",
  5  usecase: "Send promotional messages",
  6  company: "Pennycodes"
  7}
  8
  9const response = await provider.messaging.request_sender_id(payload);
  10
  11console.log(response.code) // ok 

Messages Documentation

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

• Send Message

  1
  2const payload = {
  3  to: "233552345567",
  4  sms: "Hello there, welcome to Termii"
  5}
  6
  7const response = await provider.messaging.send(payload);
  8
  9console.log(response.code) // ok 

• Send Bulk Message

  1
  2const payload = {
  3  to: ["23490555546", "23423490126999","23490555546"],
  4  sms: "Hello there, welcome to Termii"
  5}
  6
  7const response = await provider.messaging.send_bulk(payload);
  8
  9console.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.

1
2const payload = {
3  to: "233552345567",
4  sms: "Hello there, welcome to Termii"
5}
6
7const response = await provider.messaging.send_without_sender_id(payload);
8
9console.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

1
2const payload = {
3  phone_number: "233552345567",
4  device_id: "device_one",
5  template_id: "template_one",
6  data: {
7    product_name: "Termii",
8    otp : 120435,
9    expiry_time: "10 minutes"
10  }
11}
12
13const response = await provider.messaging.send_with_template(payload);
14
15console.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

  1
  2// returns paginated results of 15 items per page
  3const phonebooks = await provider.messaging.list_phonebooks();
  4
  5 // get page
  6const nextPhonebooks = await provider.messaging.list_phonebooks(2);

• Create Phonebook

  1
  2const payload =  {
  3  phonebook_name: "Royals",
  4  description: "My royal leads"  
  5}
  6
  7const response = await provider.messaging.create_phonebook(payload);
  8
  9console.log(response.message) // Phonebook added successfully

• Update Phonebook

  1
  2const payload =  {
  3  phonebook_name: "Premium" 
  4}
  5
  6const response = await provider.messaging.update_phonebook("phonebook_id",payload);
  7
  8console.log(response.message) // Phonebook updated successfully

• Delete Phonebook

  1
  2const response = await provider.messaging.delete_phonebook("phonebook_id");
  3
  4console.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

  1
  2// returns paginated results of 15 items per page
  3const contacts = await provider.messaging.list_contacts("phonebook_id");
  4
  5 // get page
  6const nextContacts = await provider.messaging.list_contacts("phonebook_id", 2);

• Create Contact

  1
  2const payload =  {
  3  phone_number: "556789909",
  4  country_code: "233"
  5}
  6
  7const response = await provider.messaging.create_contact("phonebook_id",payload);
  8
  9console.log(response.data.id) // 3647982

• Delete Contact

  1
  2const response = await provider.messaging.delete_contact("contact_id");
  3
  4console.log(response.message) // Contact deleted successfully

Campaigns Documentation

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

• List Campaigns

  1
  2// returns paginated results of 15 items per page
  3const campaigns = await provider.messaging.list_campaigns();
  4
  5 // get page
  6const nextCampaigns = await provider.messaging.list_campaigns(2);

• Fetch Campaign History

  1
  2// returns paginated results of 15 items per page
  3const history = await provider.messaging.get_campaign_history("campaign_id");
  4
  5 // get page
  6const nextHistory = await provider.messaging.get_campaign_history("campaign_id", 2);

• Send Campaign

  1
  2const payload =  {
  3  phone_number: "556789909",
  4  country_code: "233",
  5  message: "Hello, Welcome to Termii",
  6  phonebook_id: "phonebook_id",
  7  campaign_type: "personalized"
  8}
  9
  10const response = await provider.messaging.send_campaign(payload);
  11
  12console.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.

1
2const payload = {
3  to: "23490126727",
4  pin_length: 6,
5  message_text: "Your pin is"
6}
7
8const response = await provider.token.send_token(payload);
9
10console.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

1
2const payload = {
3  email_address: "test@termii.com",
4  code: "092471",
5  email_configuration_id: "email_configuration_id_from_dashboard"
6}
7
8const response = await provider.token.email_token(payload);
9
10console.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

1
2const payload = {
3  phone_number: "23490126727"
4}
5
6const response = await provider.token.send_voice_token(payload);
7
8console.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

1
2const payload = {
3  phone_number: "23490126727",
4  code: 1223
5}
6
7const response = await provider.token.make_voice_call(payload);
8
9console.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.

1
2const payload = {
3  phone_number: "23490126727",
4  pin_length: 6
5}
6
7const response = await provider.token.send_in_app_token(payload);
8
9console.log(response.status) // success
10console.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.

1
2const payload = {
3  pin_id: "pin_id",
4  pin: 123456
5}
6
7const response = await provider.token.verify_token(payload);
8
9console.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.

1    
2const balance = await provider.insights.balance();
3
4console.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

1
2const response = await provider.insights.search_phone_number("phone_number");
3
4console.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.

1
2const payload = {
3  phone_number: "523353245594",
4  country_code: "GH"
5}
6const response = await provider.insights.status_phone_number(payload);
7
8console.log(response.result) // {@returns typeof array}

History Documentation

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

1
2const inbox = await provider.insights.history();
3
4console.log(inbox) // {@returns typeof array}

Middleware

Express Middleware to handle Webhook Events

Add your webhook url in your Termii Developer Console

1// using ES6 modules
2import { Webhook } from '@brvhprince/termii-js'
3
4// using CommonJS modules
5const { Webhook } = require("@brvhprince/termii-js");
6
7// Initialize
8
9const provider = new Webhook("secret_key");
10
11//Inbound-Message Received
12
13provider.on("inbound", data => {
14  // Act
15  console.log("Here We are!");
16});
17
18
19//Outbound Message (Delivery Report)
20
21provider.on("outbound", data => {
22  // Act
23  console.log("Here We are!");
24});
25
26
27//Device offline Notification
28
29provider.on("device_status", data => {
30  // Act
31  console.log("Here We are!");
32});
33
34
35// Hooks with Express
36app.post("/my/webhook/url", provider.middleware);
37

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