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