@kairosafrika/sms

Kairos Bulk SMS Node

A Observable-based wrapper implementation that exposes all of Kairos' SMS APIs making integration into your backend for sending SMS easier and faster

Table Of Contents

• Features
• Installing
• Request Structure
• Response Structure
• Example
• Kairos SMS API
• Creating an instance
• Instance methods

Features

• Send Quick SMS
• Send Bulk SMS
• Ping the status of an already sent SMS
• Check your account balance
• Provides method chaining under-the-hood
• Supports typescript from the get-go
• Unsubscribed to method calls with the unsubscribe() method from rxjs

Installation

Quickly use the package by running either of the below commands

Using npm:

npm i @kairosafrika/sms

or Using yarn:

yarn add @kairosafrika/sms

Request Structure

Find the request structure when making an API request for Quick SMS.

{
    "to": "xxxxxxxxx",
    "from": "KAIROS",
    "message": "this is a test message"
}

Find the request structure when making an API request for Quick SMS with multiple phone numbers or msisdns.

{
    "to": "233200746423,23094990599",
    "from": "KAIROS",
    "message": "this is a test message"
}

Find the request structure when making an API request for Bulk SMS.

{
  "messages": [
    {
      "to": "233200746417",
      "from": "Kairos Test",
      "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
      "type": "Quick"
    }
  ]
}

Note: type is optional but accepts only two values; Quick & Flash

Response Structure

Find the response structure when a successful or failed response is returned.

200 OK

{
  "statusMessage": "SMS scheduled successfully",
  "statusCode": 200,
  "success": true,
  "data":  true,
  "timestamp": "2022-04-21T06:46:22.983Z"
}

400 Bad Request

{
  "statusMessage": "Invalid path params passed",
  "statusCode": 200,
  "success": true,
  "data":  { 
    "message": "URl accept the id of sent message"
  },
  "timestamp": "2022-04-21T06:46:22.983Z"
}

Example

Note: This package is implemented in typescript hence no need to install typings

// importing the package as a default
import KairosSMS from "@kairosafrika/sms";

or

import { KairosSMS } from "@kairosafrika/sms"

Sending a quick SMS

KairosSMS
    .send({ apiKey: 'xxxxxxxxx', apiSecret: 'xxxxxxx', timeout: 90000}, {to: "xxxxxxxxxxx", from: "kairos", message: "this is a test message"})
    .asQuick()
    .subscribe(response => {
        // handle response 
        console.log(response)
})

Sending a bulk SMS

KairosSMS
    .send({apiKey: 'xxxxxxxx', apiSecret: 'xxxxxxxx', timeout: 90000},{
        "messages": [
            {
                "to": "233200746417",
                "from": "Kairos Test",
                "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
                "type": "Quick"
            }
        ]
    })
    .asBulk()
    .subscribe(response => {
        // handle response
        console.log(response)
    })

NOTE: Kairos SMS package also exposes an independent function that allows you to convert Observables to Promises to use async/await

import { asPromise } from "@kairos/sms";
// always don't forget to append `async` if the function is created as found below
async function sendSMS() {
    const response = await asPromise(
        KairosSMS
        .send({ apiKey: 'xxxxxxxxx', apiSecret: 'xxxxxxx', timeout: 90000}, {to: "xxxxxxxxxxx", from: "kairos", message: "this is a test message"})
        .asQuick()
    )
    console.log(response)
}

Kairos SMS API

Requests can be made by passing the relevant configs to KairosSMS.create()

Creating an instance

You can create an instance of KairosSMS with the relevant configs

KairosSMS.create([config])

const instance = KairosSMS.create({ 
    apiKey: 'xxxxxxxxxxx', 
    apiSecret: 'xxxxxxxxxx', 
    timeout: 800000
})

Instance Methods

There are two main available instance methods that exposes send methods and check balance methods, This includes

Method	description
send(data)	called when you want to send sms or check the current status of an already sent sms
account()	called when you want to check the account balance
contacts()	called when you want to GET,PATCH,DELETE contact details associated with an account

Send(data)

After you've created the instance, you can then call the send(data) method,

const response = instance.send(data)

Which exposes all the necessary methods below

asQuick()

asBulk()

asQuickMultipleMSISDN()

This method allows customer to send same message to multiple msisdns or phone numbers by using a comma separated values for the to property in the request object at Request Structure

  "to":"233200746423,23094990599"

Example

response
    .asQuickMultipleMSISDN()
    .subscribe(data => {
        // handle response here
        console.log(data)
    })

asPing()

This method is a bit different because it accepts the id of the sent sms instead of an object to make the request. Hence, something like so

instance
    .send("2")
    .asPing()
    .subscribe(response => {
        // handle response here
        console.log(response)
    })

Account()

After you've created the instance, you can then call the account() method,

const response = instance.account()

Which exposes the method below

balance()

Get current user balance with this

response
    .balance()
    .subscribe(response => {
        // handle response here
        console.log(response)
})

Contacts()

Contacts method also exposes a handful of functions that to allow you to GET,PATCH, POST contacts to your accounts

HTTP Verb	Methods	Descriptions	Active
GET	setPage(), setSize(), asList()	Get a paginated list of all your contacts	:heavy_check_mark:
POST	create()	Create a new contact by calling the create() method	:heavy_check_mark:
GET	details()	Get the details of a particular contact	:heavy_check_mark:
PUT	update(id)	Update the details of a contact	:heavy_check_mark:
DELETE	delete(id)	Delete a contact details	:heavy_check_mark:

The contacts() method accept an optional options parameter of type IContactsOptions which is of the format

interface IContactsOptions {
    paginate: {
        page: number;
        size: number;
    },
    body: {
        name: string;
        phone: string;
        dateOfBirth?: string
    }
}

List All Contacts

asList()

Get a paginated list of your contacts from the Kairos Afrika Bulk SMS Platform by calling asList()

Example #1

Make a request by passing page and size directly to the contacts() method

instance
     .contacts({
         paginate: {
             page: 1,
             size: 15
         }
     })
     .asList()
     .subscribe(response => {
         //handle repsonse here
        console.log(response)
    })

Example #2

Make a request by performing method chaining

instance
      .contacts()
      .setPage(1)
      .setSize(15)
      .asList().subscribe(response => {
          // handle response here
        console.log(response)
    })

Make a request by passing configs and optional options to the static contacts() method

Options - the current page and the total size to show per page

{
    page: 1, 
    size: 15
}

Example #3

const response = KairosSMS
    .contacts(configs, {
        paginate: {
            page: 1, 
            size: 15
           }
        }
    )
    .asList()
    .subscribe(response => {
    //handle response here
    console.log(response)
})

NB. calling setPage & setSize overrides what's been set as the static contacts method.

Create A Contact

Create a new contact via Kairos SMS API by calling either of these two procedures

Example #1

Create an instance of the Kairos SMS that exposes the contacts() method and then pass the body of the contact to be created directly to that method

const instance = KairosSMS.create([config])
const response$ = instance.contacts({
    body: {
        name: "Jane Doe",
        phone: "0203746417",
        dateOfBirth: null
    }
}).create();
response$.subscribe(data => {
    // handle response here
    console.log(data)
})

Example #2

You can also pass the body of the contact to be created directly to the create method that's exposed by the contacts() method.

const response$ = instance.contacts().create({
    name: "Jane Doe",
    phone: "0203746417",
    dateOfBirth: "2022-01-01"
})
response$.subscribe(data => {
    // handle response here
    console.log(data)
})

Get a Contact Details

Get the details of a particular contact by passing the id as a parameter

Example #1

const response$ = instance.contacts().details(12)
response$.subscribe((data) => {
    // handle response here
    console.log(data)
})

Update a Contact

Update the details of a contact by passing the contact id and the payload as a parameter

Example #1

Pass the payload or the request body as a part of the contacts() method and then the contactId as a parameter to the update(id) chained method.

const response$ = instance.contacts({
    body: {
        name: "Jane Doe",
        phone: "0203746417",
        dateOfBirth: null
    }
}).update(12);
response$.subscribe(data => {
    // handle response here
    console.log(data)
})

Example #2

You can also pass both the request payload and the id as parameters to the update() method

const response$ = instance.contacts().update(12,
    {
        name: "Jane Doe",
        phone: "0203746417",
        dateOfBirth: null
    });
response$.subscribe(data => {
    // handle response here
    console.log(data)
})

Delete A Contact

Remove a specific contact from your contact list by passing the contactId as a parameter to delete(id) exposed by the contacts() method

Example #1

const response$ = instance.contacts().delete(12)
response$.subscribe((data) => {
    // handle response here
    console.log(data)
})

Note that the contact method is also exposed as a static method which can be accessed by doing this

import {KairosSMS} from "@kairosafrika/sms"
KairosSMS
     .contacts({
        apiKey: 'xxxxxxxxxx',
        apiSecret: 'xxxxxxxxxxx'
     }, {
        body: {
          name: "Jane Doe",
          phone: "0203746417",
          dateOfBirth: null
        }
     }).create().subscribe(data => {
        // handle response here
        console.log(data)
     })

NB. Don't forget that the instance you'll create will contain the apiKey & apiSecret with an optional timeout

Credits

Kairos SMS Node is heavily inspired by axios

License

MIT