Termii Nodejs Client

Nodejs SDK for Termii messaging platform written in typescript

Table of content

• Prerequisites
• Getting started
• Installation
• Usage
• Available Services exposed by the SDK
  • Sender ID API
    • Fetch Sender ID
    • Create Sender ID
  • Messaging API
    • Send Message
    • Send Bulk Message
  • Number API
    • Send Message with Number
  • Templates API
    • Device Template (Send Message with Template)
  • Campaign API
    • Phonebooks
      • Fetch Phonebooks
      • Create Phonebook
      • Update Phonebook
      • Delete Phonebook
    • Contacts
      • Fetch contacts by phonebook ID
      • Add single contact to phonebook
      • Delete contact
    • Campaign
      • Fetch campaigns
      • Fetch campaign history
      • Send a campaign
  • Token API
    • Send Token
    • Voice Token
    • Voice Call
    • Email Token
    • Verify Token
    • In App Token
  • Insights API
    • Balance
    • Search
    • Status
    • History
• License

Prerequisites

Node v16 and higher is required. To make sure you have them available on your machine, try running the following command.

1 node -v

Getting Started

To get started with this SDK, create an account on Termii if you haven't already. You can then retrieve your API keys from your Termii dashboard.

Installation

This SDK can be installed with npm or yarn or pnpm.

1# using npm
2npm install termii-nodejs-client
3# using yarn
4yarn install termii-nodejs-client
5# using pnpm
6pnpm add termii-nodejs-client

Usage

Import and Initialize the library

1// use modules
2import { Termii } from 'termii-nodejs-client';
3// use cjs
4const { Termii } = require('termii-nodejs-client')
5
6const termii = new Termii('YOUR_API_KEY');
7
8// Instantiate the Termii class
9const termii = new Termii('YOUR_API_KEY');

Warning Be sure to keep your API Credentials securely in environment variables.

Available Services exposed by the SDK

Sender ID API

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

Fetch Sender ID

1// import the sender id response interface from the sdk
2import { type ISenderIDResponse } from 'termii-nodejs-client';
3
4// returns the first 15 sender ids
5const senderIds = await termii.message.fetchSenderIDs()
6
7// to get the next page of sender ids 
8const senderIds = await termii.message.fetchSenderIDs(2)
9console.log(senderIds) // ISenderIDResponse

Find more details about the parameters and response for the above method here

Create Sender ID

1// import the request sender id interfaces from the sdk
2import type { IRequestSenderID, IRequestSenderIDResponse } from 'termii-nodejs-client';
3
4const payload: IRequestSenderID = {
5  sender_id: 'acme',
6  usecase: 'Testing! Working!! This is it!!!',
7  company: 'Metalabs',
8}
9
10const response = await termii.message.requestSenderID(payload)
11console.log(response) // IRequestSenderIDResponse

Find more details about the parameters and response for the above method here

Messaging API

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

Send Message

1// import the message interfaces from the sdk
2import type { ISendMessage, ISendMessageResponse } from 'termii-nodejs-client';
3
4const payload: ISendMessage = {
5  to: "23490126727",
6  from: "talert",
7  sms: "Hi there, testing Termii",
8  type: "plain",
9  channel: "generic",
10  api_key: "Your API Key",
11  media: {
12    url: "https://media.example.com/file",
13    caption: "your media file"
14  }    
15}
16
17const response = await termii.message.sendMessage(payload)
18console.log(response) // ISendMessageResponse

Find more details about the parameters and response for the above method here

Send Bulk Message

1// import the message interfaces from the sdk
2import type { ISendBulkMessage, ISendBulkMessageResponse } from 'termii-nodejs-client';
3
4const payload: ISendBulkMessage = {
5  to: ["23490126727", "23490126728","23490126729"],
6  from: "talert",
7  sms: "Hi there, testing Termii",
8  type: "plain",
9  channel: "generic"
10}
11
12const response = await termii.message.sendBulkMessage(payload)
13console.log(response) // ISendBulkMessageResponse

Find more details about the parameters and response for the above method here

Number API

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

Send Message with Number

1// import the number interfaces from the sdk
2import type { ISendMessageWithNumber, ISendMessageWithNumberResponse } from 'termii-nodejs-client';
3
4const payload: ISendMessage = {
5  to: "23490126727",
6  sms: "Hi there, testing Termii"
7}
8
9const response = await termii.message.sendMessageWithNumber(payload)
10console.log(response) // ISendMessageWithNumberResponse

Find more details about the parameters and response for the above method here

Templates API

This helps businesses set a template for the one-time-passwords (pins) sent to their customers via whatsapp or sms.

Device Template (Send Message with Template)

1// import the template interfaces from the sdk
2import type { IDeviceTemplate, IDeviceTemplateResponse } from 'termii-nodejs-client';
3
4const payload: IDeviceTemplate = {
5  phone_number: '23490126727',
6  device_id: 'device123',
7  template_id: 'template456',
8  data: {
9    product_name: 'Dummy Product',
10    otp: 123456,
11    expiry_time: '2023-11-16T12:00:00Z',
12  },
13}
14
15const response = await termii.message.sendMessageWithTemplate(payload)
16console.log(response) // IDeviceTemplateResponse

Find more details about the parameters and response for the above method here

Campaign API

Phonebooks

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.

Fetch Phonebooks

1// import the phonebook interfaces from the sdk
2import type { IFetchPhonebooksResponse } from 'termii-nodejs-client';
3
4const response = await termii.message.fetchPhonebooks()
5
6// to fetch another page - pass the page number to the method
7const response = await termii.message.fetchPhonebooks(2)
8console.log(response) // IFetchPhonebooksResponse

Find more details about the parameters and response for the above method here

Create Phonebook

1// import the phonebook interfaces from the sdk
2import type { IPhonebookResponse, IPhonebook, } from 'termii-nodejs-client';
3
4const payload: IPhonebook = {
5  phonebook_name: 'Test',
6  description: 'Phonebook for test',
7}
8
9const response = await termii.message.createPhonebook(payload)
10console.log(response) // IPhonebookResponse

Find more details about the parameters and response for the above method here

Update Phonebook

1// import the phonebook interfaces from the sdk
2import type { IPhonebookResponse, IPhonebook, } from 'termii-nodejs-client';
3
4const payload: IPhonebook = {
5  phonebook_name: 'Update testTest',
6  description: 'Updated Phonebook for test',
7}
8
9const response = await termii.message.updatePhonebook('phonebook_id', payload)
10console.log(response) // IPhonebookResponse

Find more details about the parameters and response for the above method here

Delete Phonebook

1// import the phonebook interfaces from the sdk
2import type { IPhonebookResponse } from 'termii-nodejs-client';
3
4const response = await termii.message.deletePhonebook('phonebook_id')
5console.log(response) // IPhonebookResponse

Find more details about the parameters and response for the above method here

Contacts

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

Fetch contacts by phonebook ID

1// import the contact interfaces from the sdk
2import type { IFetchContactsResponse } from 'termii-nodejs-client';
3
4const response = await termii.message.fetchContacts('phonebook_id')
5
6// to fetch another page - pass the page number to the method after the phonebook ID
7const response = await termii.message.fetchContacts('phonebook_id', 2)
8console.log(response) // IFetchContactsResponse

Find more details about the parameters and response for the above method here

Add single contact to phonebook

1// import the contact interfaces from the sdk
2import type { ICreateContact, ICreateContactResponse } from 'termii-nodejs-client';
3
4const payload: ICreateContact = {
5  phone_number: '812369234901267276237',
6  email_address: 'test@gmail.com',
7  first_name: 'test',
8  last_name: 'contact',
9  company: 'Termii',
10  country_code: '234',
11}
12
13const response = await termii.message.createContact('phonebook_id', payload)
14console.log(response) // ICreateContactResponse

Find more details about the parameters and response for the above method here

Delete contact

1// import the contact interfaces from the sdk
2import type { IDeleteContactResponse } from 'termii-nodejs-client';
3
4const response = await termii.message.deleteContact('contact_id')
5console.log(response) // IDeleteContactResponse

Find more details about the parameters and response for the above method here

Campaign

Using the campaign APIs, you can view, manage and send a campaign to a phonebook.

Fetch campaigns

1// import the campaign interfaces from the sdk
2import type { IFetchCampaignsResponse } from 'termii-nodejs-client';
3
4const response = await termii.message.fetchCampaigns()
5
6// to fetch another page - pass the page number to the method
7const response = await termii.message.fetchCampaigns(2)
8console.log(response) // IFetchCampaignsResponse

Find more details about the parameters and response for the above method here

Fetch campaign history

1// import the campaign interfaces from the sdk
2import type { fetchCampaignHistoryResponseData } from 'termii-nodejs-client';
3
4const response = await termii.message.fetchCampaigns('campaign_id')
5
6// to fetch another page - pass the page number to the method after campaign ID
7const response = await termii.message.fetchCampaigns('campaign_id', 2)
8console.log(response) // fetchCampaignHistoryResponseData

Find more details about the parameters and response for the above method here

Send a campaign

1// import the campaign interfaces from the sdk
2import type { ISendCampaign, ISendCampaignResponse } from 'termii-nodejs-client';
3
4const payload: ISendCampaign = {
5  api_key: "Your API KEY",
6  country_code: "234",
7  sender_id: "Termii",
8  message: "Welcome to Termii.",
9  channel: "generic",
10  message_type: "Plain",
11  phonebook_id: "2d9f4a02-85b8-45e5-9f5b-30f93ef472e2",
12  delimiter: ",",
13  remove_duplicate: "yes",
14  campaign_type: "personalized",
15  schedule_time: "30-06-2021 6:00",
16  schedule_sms_status: "scheduled"
17}
18
19const response = await termii.message.sendCampaign(payload)
20
21console.log(response) // ISendCampaignResponse

Find more details about the parameters and response for the above method here

Token API

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

Send Token

1// import the token interfaces from the sdk
2import type { ISendToken, ISendTokenResponse } from 'termii-nodejs-client';
3
4const payload: ISendToken = {
5  message_type: 'NUMERIC',
6  to: '23490126727',
7  from: 'Acme',
8  channel: 'generic',
9  pin_attempts: 3,
10  pin_time_to_live: 1,
11  pin_length: 4,
12  pin_placeholder: '< 1234 >',
13  message_text: 'Your verification code is 1234',
14}
15
16const response = await termii.token.sendToken(payload)
17
18console.log(response) // ISendTokenResponse

Find more details about the parameters and response for the above method here

Voice Token

1// import the token interfaces from the sdk
2import type { ISendVoiceToken, ISendVoiceTokenResponse } from 'termii-nodejs-client';
3
4const payload: ISendVoiceToken = {
5  phone_number: '23490126727',
6  pin_attempts: 3,
7  pin_time_to_live: 1,
8  pin_length: 4,
9}
10
11const response = await termii.token.sendVoiceToken(payload)
12
13console.log(response) // ISendVoiceTokenResponse

Find more details about the parameters and response for the above method here

Voice Call

1// import the token interfaces from the sdk
2import type { IMakeVoiceCall, IMakeVoiceCallResponse } from 'termii-nodejs-client';
3
4const payload: IMakeVoiceCall = {
5  phone_number: '23490126727',
6  code: 12345
7}
8
9const response = await termii.token.makeVoiceCall(payload)
10
11console.log(response) // IMakeVoiceCallResponse

Find more details about the parameters and response for the above method here

Email Token

1// import the token interfaces from the sdk
2import type { sendEmailToken, ISendEmailTokenResponse } from 'termii-nodejs-client';
3
4const payload: sendEmailToken = {
5  email_address: 'test@test.com',
6  code: '33443',
7  email_configuration_id: 'fad4f438-655d-399a-a50a-b93e11b41323'
8}
9
10const response = await termii.token.sendEmailToken(payload)
11
12console.log(response) // ISendEmailTokenResponse

Find more details about the parameters and response for the above method here

Verify Token

1// import the token interfaces from the sdk
2import type { IVerifyToken, IVerifyTokenResponse } from 'termii-nodejs-client';
3
4const payload: IVerifyToken = {
5  pin_id: 'c8dcd048-5e7f-4347-8c89-4470c3af0b',
6  pin: '15017',
7}
8
9const response = await termii.token.verifyToken(payload)
10
11console.log(response) // IVerifyTokenResponse

Find more details about the parameters and response for the above method here

In App Token

1// import the token interfaces from the sdk
2import type { IInAppToken, IInAppTokenResponse } from 'termii-nodejs-client';
3
4const payload: IInAppToken = {
5  pin_type: 'NUMERIC',
6  phone_number: '2348109477743',
7  pin_attempts: 3,
8  pin_time_to_live: 0,
9  pin_length: 4,
10}
11
12const response = await termii.token.inAppToken(payload)
13
14console.log(response) // IInAppTokenResponse

Find more details about the parameters and response for the above method here

Insights API

Balance

1// import the insights interfaces from the sdk
2import type { IGetBalanceResponse } from 'termii-nodejs-client';
3
4const response = await termii.insights.getBalance()
5
6console.log(response) // IGetBalanceResponse

Find more details about the parameters and response for the above method here

Search

1// import the insights interfaces from the sdk
2import type { ISearchPayload, ISearchResponse } from 'termii-nodejs-client';
3
4const payload: ISearchPayload = {
5  phone_number: '2348109477743',
6}
7
8const response = await termii.insights.search(payload)
9
10console.log(response) // ISearchResponse

Find more details about the parameters and response for the above method here

Status

1// import the insights interfaces from the sdk
2import type { IStatusPayload, IStatusResponse } from 'termii-nodejs-client';
3
4const payload: IStatusPayload = {
5  phone_number: '2348109477743',
6  country_code: "NG"
7}
8
9const response = await termii.insights.getStatus(payload)
10
11console.log(response) // IStatusResponse

Find more details about the parameters and response for the above method here

History

1// import the insights interfaces from the sdk
2import type { IHistoryPayload, IHistoryResponse } from 'termii-nodejs-client';
3
4// to get the history of the messages
5const response = await termii.insights.getHistory()
6
7// to get the history of a single message
8const payload: IHistoryPayload = {
9  message_id: '5508751839629937023',
10}
11const response = await termii.insights.getHistory(payload)
12
13console.log(response) // IHistoryResponse

Find more details about the parameters and response for the above method here

License

MIT

Back to Top