README
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).
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',
};
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
- Email Service:
sendchamp.EMAIL
- 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.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' ]).
REQUIREDmessage
: Text message being sent.
STRING REQUIREDsender_name
: Represents the sender of the message. This Sender ID must have been requested via the dashboard or use "Sendchamp" as default.
STRING REQUIREDroute
: 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_NG, DND_NG, or PREMIUM_NG.
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({sender_name, use_case, sample})
: API to register Sender ID for sending SMS.sender_name
: Represents the sender of the message.
STRING REQUIREDuse_case
: You should pass either of the following: Transactional, Marketing, or Transactional & Marketing.
STRING REQUIREDsample
: This should contain your sample message.
STRING REQUIRED
VOICE Service
const voice = sendchamp.VOICE;
voice.send({message, customer_mobile_number})
: This method allows you to send a text-to-speech voice call.message
: The text message you to send with voice.
STRING REQUIREDcustomer_mobile_number
: The number represents the destination phone number. The number must be in international format (E.g. 2348012345678)
STRING REQUIRED
VERIFICATION Service
const verification = sendchamp.VERIFICATION;
verification.sendOTP({channel, sender, token_type, token_length, expiration_time, customer_email, 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 REQUIREDsender
: 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 REQUIREDtoken_type
: NUMERIC or ALPHANUMERIC.
STRING REQUIREDtoken_length
: The length of the token you want to send to your customer. Minimum is 4.
INTEGER REQUIREDexpiration_time
: How long you want to the to be active for in minutes. (E.g 10 means 10 minutes ).
INTEGER REQUIREDcustomer_email
: The email address of your customer. It's required if you're using Email Channel.
STRING REQUIREDcustomer_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 REQUIREDmeta_data
: To pass additional information as an object.
STRING REQUIRED
verification.verifyOTP({verification_reference, verification_otp})
: 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 REQUIREDverification_otp
: The OTP that was sent to the customer.
STRING REQUIRED
WHATSAPP Service
const whatsapp = sendchamp.WHATSAPP;
whatsapp.sendTemplate({sender, recipient, template_code, message})
: 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 REQUIREDrecipient
: Whatsapp number of the customer you are sending the message to.
STRING REQUIREDtemplate_code
: You can find this on the template page under Whatsapp Channel of your Sendchamp dashboard.
STRING REQUIREDmessage
: This is the message based on the template approved on Sendchamp Dashboard.
STRING 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 REQUIREDrecipient
: This will be the phone number of the customer E.g 234811111111.
STRING REQUIREDmessage
: message to customer.
STRING REQUIRED
whatsapp.sendImage({from, recipient, link, caption})
: Utilize this method to send images via WhatsApp.from
: This will be the activated Whatsapp phone number E.g 234810000000.
STRING REQUIREDrecipient
: This will be the phone number of the customer E.g 234811111111.
STRING REQUIREDlink
: This is the URL to the image resource.
STRING REQUIREDcaption
: This is the caption to be dispalyed under the image in the chat.
STRING REQUIRED
whatsapp.sendVideo({from, recipient, link, caption})
: Utilize this method to send videos via WhatsApp.from
: This will be the activated Whatsapp phone number E.g 234810000000.
STRING REQUIREDrecipient
: This will be the phone number of the customer E.g 234811111111.
STRING REQUIREDlink
: This is the URL to the video resource.
STRING REQUIREDcaption
: This is the caption to be dispalyed under the video in the chat.
STRING REQUIRED
whatsapp.sendAudio({from, recipient, link})
: Utilize this method to send audio via WhatsApp.from
: This will be the activated Whatsapp phone number E.g 234810000000.
STRING REQUIREDrecipient
: This will be the phone number of the customer E.g 234811111111.
STRING REQUIREDlink
: This is the URL to the audio resource.
STRING REQUIRED
whatsapp.sendDocument({from, recipient, link, caption})
: Utilize this method to send documents via WhatsApp.from
: This will be the activated Whatsapp phone number E.g 234810000000.
STRING REQUIREDrecipient
: This will be the phone number of the customer E.g 234811111111.
STRING REQUIREDlink
: This is the URL to the document resource.
STRING REQUIREDcaption
: This is the caption to be dispalyed under the document in the chat.
STRING REQUIRED
whatsapp.sendLocation({from, recipient, location})
: Utilize this method to send locations via WhatsApp.from
: This will be the activated Whatsapp phone number E.g 234810000000.
STRING REQUIREDrecipient
: This will be the phone number of the customer E.g 234811111111.
STRING REQUIREDlocation
: An object that describes the location:longitude
: The longitude of the location E.g -46.662787.
NUMBER REQUIREDlatitude
: The latitude of the location E.g -23.55361.
NUMBER REQUIREDname
: The name of the location E.g Robbu Brazil.
STRING REQUIREDaddress
: The address of the location E.g Av. Angélica, 2530 - Bela Vista, São Paulo - SP, 01228-200.
STRING REQUIRED
Issues
If you find a bug, please file an issue on the issue tracker.