Sendchamp Node.js SDK

The wrapper provides convinient access to the Sendchamp api from applications written in Node.js.

Documentation

Take a look at the API docs here.

Install

You can install the pacakge from npm by running:

$ npm install --save https://github.com/fuadop/sendchamp-sdk.git

# using npm
$ npm install --save sendchamp-sdk

# using yarn
$ yarn add sendchamp-sdk

Usage

The package needs to be configured with your business public key (test/live) and your development mode (test/live).

NB: Using this package with typescript you need to set esModuleInterop to true in your tsconfig.json file. See related issue: fuadop#6

import Sendchamp from 'sendchamp-sdk';

const sendchamp = new Sendchamp({
  mode: 'test', // this is set to live by default
  publicKey: 'sendchamp_test_$2y$10$U2SHG5T2F/cr0jfzNCKgguHv.23plvJP/75EzZjF5MtLXz65SDrQi'
});

// Initialize a service
const sms = sendchamp.SMS;

// Use the service
const options = {
  to: ['2348153207998'],
  message: 'Hello from postman',
  sender_name: 'sendchamp',
  // optional option to set route
  route: 'international' // can be set to non_dnd, dnd or international, default it non_dnd
};

sms.send(options)
  .then(response => {
    console.log(response);
  })
  .catch(error => {
    console.log(error);
  });

Initialization

Initialize the SDK by doing :

  import Sendchamp from 'sendchamp-sdk'; // es6 import
  const Sendchamp = require('sendchamp-sdk'); // commonjs require

  const sendchamp = new Sendchamp(options);
  // options is an object of publicKey and mode
  // See usage

After initialization, you can get instances of offered services as follows:

• SMS Service : sendchamp.SMS
• Whatsapp Service : sendchamp.WHATSAPP
• Voice Service : sendchamp.VOICE
• VERIFICATION Service: sendchamp.VERIFICATION

Services

All methods are asynchronous.
All phone numbers are international format (without the plus symbol). e.g 2348153207998.

SMS Service

    const sms = sendchamp.SMS;

• sms.send({to, message, sender_name, route}): API for sending SMS. Refer to sms test file(tests/sms.spec.ts) to see usage.

  • to : This represents the destination phone number. The phone number(s) must be in the international format (Example: 23490126727). You can also send to multiple numbers. To do that put numbers in an array (Example: [ '234somenumber', '234anothenumber' ]).
    REQUIRED

  • message : Text message being sent.
    STRING REQUIRED

  • sender_name : Represents the sender of the message. This Sender ID must have been requested via the dashboard or use "Sendchamp" as default.
    STRING REQUIRED

  • route : Here you can specify a route you want your SMS to go through. Read this guide for routing options. You should pass either of the following: non_dnd, dnd, or international.
    STRING OPTIONAL

• sms.getStatus(sms_message_id): API to retrieve the status of an already sent SMS.

  • sms_message_id : ID of the SMS that was sent.
    REQUIRED

• sms.registerSender({name, use_case, sample}): API to register Sender ID for sending SMS.

  • name: Represents the sender of the message.
    STRING REQUIRED

  • use_case: You should pass either of the following: Transactional, Marketing, or Transactional & Marketing.
    STRING REQUIRED

  • sample: This should contain your sample message.
    STRING REQUIRED

VOICE Service

    const voice = sendchamp.VOICE;

• voice.send({message, customer_mobile_number, type, repeat}): This method allows you to send a text-to-speech voice call. Refer to the voice test file (tests/voice.spec.ts) to see usage.

  • message: The text message you to send with voice.
    STRING REQUIRED

  • customer_mobile_number: The number represents the destination phone number. The number must be in international format (E.g. 2348012345678)
    string[] REQUIRED

  • type: The voice type, Only one type exists currently which is "outgoing".
    STRING REQUIRED

  • repeat: The amount of times the message should be repeated.
    INTEGER REQUIRED

VERIFICATION Service

    const verification = sendchamp.VERIFICATION;

• verification.sendOTP({channel, sender, token_type, token_length, expiration_time, customer_email_address, customer_mobile_number, meta_data}): This method is used to send Verification OTP (One Time Password) to your customer contact address.

  • channel: VOICE, SMS, WHATSAPP or EMAIL.
    STRING REQUIRED

  • sender: Specify the sender you want to use. This is important when using SMS OR Whatsapp Channel or we will select a default sender from your account. Eg: KUDA OR +234810000000.
    STRING REQUIRED

  • token_type: NUMERIC or ALPHANUMERIC.
    STRING REQUIRED

  • token_length: The length of the token you want to send to your customer. Minimum is 4.
    INTEGER REQUIRED

  • expiration_time: How long you want to the to be active for in minutes. (E.g 10 means 10 minutes ).
    INTEGER REQUIRED

  • customer_email_address: The email address of your customer. It's required if you're using Email Channel.
    STRING REQUIRED

  • customer_mobile_number: The phone number of your customer. It must be in international format (E.g 2348012345678). It is required if you're using the SMS or Voice Channel.
    STRING REQUIRED

  • meta_data: To pass additional information as an object.
    STRING REQUIRED

• verification.verifyOTP({verification_reference, verification_code}): This method is used to confirm the OTP that was sent to your customer.

  • verification_reference: The unique reference that was returned as response when the OTP was created.
    STRING REQUIRED

  • verification_code: The OTP that was sent to the customer.
    STRING REQUIRED

WHATSAPP Service

    const whatsapp = sendchamp.WHATSAPP;

Refer to the whatsapp test file (tests/whatsapp.spec.ts) for usage.

• whatsapp.sendTemplate({sender, recipient, template_code, meta_data}): Send highly structured messages to your customers based on approved template.

  • sender: Your approved Whatsapp number on Sendchamp. You can use our phone number if you have not registered a number 2347067959173.
    STRING REQUIRED

  • recipient: Whatsapp number of the customer you are sending the message to.
    STRING REQUIRED

  • template_code: You can find this on the template page under Whatsapp Channel of your Sendchamp dashboard.
    STRING REQUIRED

  • meta_data: This is the template custom data.
    OBJECT REQUIRED

• whatsapp.sendText({sender, recipient, message}): Utilize this method to send text messages via WhatsApp.

  • sender: This will be the activated Whatsapp phone number E.g 234810000000.
    STRING REQUIRED

  • recipient: This will be the phone number of the customer E.g 234811111111.
    STRING REQUIRED

  • message: message to customer.
    STRING REQUIRED

• whatsapp.sendVideo({sender, recipient, link }): Utilize this method to send videos via WhatsApp.

  • sender: This will be the activated Whatsapp phone number E.g 234810000000.
    STRING REQUIRED

  • recipient: This will be the phone number of the customer E.g 234811111111.
    STRING REQUIRED

  • link: This is the URL to the video resource.
    STRING REQUIRED

• whatsapp.sendAudio({sender, recipient, link, message}): Utilize this method to send audio via WhatsApp.

  • sender: This will be the activated Whatsapp phone number E.g 234810000000.
    STRING REQUIRED

  • recipient: This will be the phone number of the customer E.g 234811111111.
    STRING REQUIRED

  • link: This is the URL to the audio resource.
    STRING REQUIRED

  • message: This is the caption to be displayed under the audio in the chat.
    STRING REQUIRED

• whatsapp.sendLocation({sender, recipient, name, address, latitude, longitude}): Utilize this method to send locations via WhatsApp.

  • sender: This will be the activated Whatsapp phone number E.g 234810000000.
    STRING REQUIRED

  • recipient: This will be the phone number of the customer E.g 234811111111.
    STRING REQUIRED

  • longitude: The longitude of the location E.g -46.662787.
    NUMBER REQUIRED

  • latitude: The latitude of the location E.g -23.55361.
    NUMBER REQUIRED

  • name: The name of the location E.g Robbu Brazil.
    STRING REQUIRED

  • address: The address of the location E.g Av. Angélica, 2530 - Bela Vista, São Paulo - SP, 01228-200.
    STRING REQUIRED

• whatsapp.sendSticker({sender, recipient, link }): Utilize this method to send stickers via WhatsApp.

  • sender: This will be the activated Whatsapp phone number E.g 234810000000.
    STRING REQUIRED

  • recipient: This will be the phone number of the customer E.g 234811111111.
    STRING REQUIRED

  • link: This is the URL to the video resource.
    STRING REQUIRED

Contributing

PRs are greatly appreciated, help us build this hugely needed tool so anyone else can easily integrate sendchamp into their JavaScript based projects and applications.

1. Create a fork
2. Create your feature branch: git checkout -b my-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request 🚀

Issues

If you find a bug, please file an issue on the issue tracker.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Aliyu Abubakar 📝 💼 🖋 💵 🤔 🧑‍🏫 📦 💬 ✅ 📢

Fuad Olatunji 🐛 💻 🚇 🚧 🎨 💡 🛡️ 🔧 📓

This project follows the all-contributors specification. Contributions of any kind welcome!