@bcm-one/messaging-sdk v1.0.3

BCM One Messaging SDK

• Messaging SDK
• Installation and initialization
• Sending messages
  • Sending SMS
    • SMS Responses
    • Successful Responses
    • Error Responses
• Using TypeScript

Installation and initialization

• In an empty folder initialize npm

npm init

• Install the npm Messaging package

npm i @bcm-one/messaging-sdk

• Create a js file

touch main.js

Now edit your main.js file:

• Import messaging from @bcm-one/messaging-sdk

import { messaging } from '@bcm-one/messaging-sdk';

messaging is an utility function that accepts a username and a password as arguments and return an instance of the Messaging class.

• Initialize the Messaging instance

const myUsername = 'username';
const myPassword = 'password';

const msg = messaging(username, password)

Congratulations! Now you can send messages!

Sending Messages

Currently, messaging package, allows to send SMS. Other functionality are currently in development.

Send SMS

Once the messaging instance is initialized you can simply send SMS in the form of a JavaScript object:

const sms = {
    from: '12345678909',
    to: '12345678908',
    message: 'Hello world!'
}

• from: a string representing a valid and registered DID. This DID must be associated with the username and password provided during the initialization of the messaging instance.

• to: a string representing the DID number of recipient.

• message: a string representing the content of the message.

in order to send the SMS, just call sendSMS method on the messaging instance, passing the sms payload as argument.

msg.sendSMS(sms)

SMS Responses

sendSMS method can return a MessageResponse or an ErrorResponse in the form of a Promise. To resolve the promise you can use the modern JS syntax with async and await, enclosing sendSMS in an asynchronous function.

// In this case, sendSMS is enclosed in a self calling async anonymous function 
;(async () => {
  try {
    const response = await msg.sendSMS(sms)
    console.log(response)
  } catch (error) {
    console.log(error)
  }
})()

Or you can use then and catch syntax

msg
  .sendSMS(sms)
  .then(response => {
    console.log(response)
  })
  .catch(err => {
    console.log(err)
  })

Successful responses

Successful responses have a statusCode of 202 on the resolved response object. They also report the sender (from), the recipient (to), the message sent (message) along with a unique identifier.

This is an example of a successful MessageResponse:

{
  from: '14707343234',
  to: '19171212121',
  message: 'Hello world',
  id: '473ebf4f-0997-430c-92ca-051725bc9c60',
  statusCode: 202
}

Error responses

An error response has a statusCode that is different from 202. Note that all the HTTP errors are returned as a simple response without the need to try and catch them because messaging handles them behind the hood.

An Error response provides more information about how the error generated on the detail key of the ErrorResponse object.

This is an example of an error response:

{
  detail: 'Resource not found\n' +
    '\n' +
    '        You are trying to send a message from a not registered DID\n' +
    'Error: from',
  statusCode: 404
}

Since HTTP errors are returned on the same response you can differentiate them comparing the status code.

;(async () => {
    const response = await msg.sendSMS(sms)
    if (response.statusCode === 202){
        console.log(response)
    } else {
      console.log('In this case an error occurred')
      console.log('On response.detail you can find more details about the error')
      console.log(response.detail)
    }
})()

This provides a much more cleaner way to handle your HTTP response rather than using try and catch.

Using TypeScript

Messaging provides type definitions for developers that want to use TypeScript.

Just make sure to create a custom type guard to define the response datatype. Here an example

import { messaging, SMS, SMSResponse } from '@bcm-one/messaging-sdk';

const myPass = "password"
const myuser = "username"

const msg = messaging(myuser, myPass)

const sms: SMS = {
    from: "12345678901",
    to: "12343212345",
    message: "Hello world!"
}


const isSuccessfulResponse = (response: any): response is SMSResponse =>{
    return response.statusCode === 202;
}

msg.sendSMS(sms).then(response => {
    if(isSuccessfulResponse(response)){
        console.log("Got a successful response!")
        console.log("MESSAGE: ", response.message)
        console.log("FROM: ", response.from)
        console.log("TO: ", response.to)
        console.log("ID: ", response.id)
    } else {
        console.log("Type guard exclude SMS response")
        console.log("Error status code: ", response.statusCode)
        console.log("Error detail: ", response.detail)
    }
})

In this example, isSuccessfulResponse act as a type guard. If the status code is 202 that mean that the response is SMSResponse, while if not is an ErrorResponse.