Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fuadop/sendchamp-sdk
API wrapper for sendchamp.com
https://github.com/fuadop/sendchamp-sdk
email otp phone phone-number sdk sendchamp sms ussd verification voice whatsapp
Last synced: about 1 month ago
JSON representation
API wrapper for sendchamp.com
- Host: GitHub
- URL: https://github.com/fuadop/sendchamp-sdk
- Owner: fuadop
- License: mit
- Created: 2021-07-14T08:34:31.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-03-02T20:38:26.000Z (9 months ago)
- Last Synced: 2024-09-28T16:05:17.508Z (about 2 months ago)
- Topics: email, otp, phone, phone-number, sdk, sendchamp, sms, ussd, verification, voice, whatsapp
- Language: TypeScript
- Homepage: https://npmjs.com/package/sendchamp-sdk
- Size: 257 KB
- Stars: 6
- Watchers: 0
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Sendchamp Node.js SDK
[](#contributors-)
The wrapper provides convinient access to the Sendchamp api from applications written in Node.js.
[](https://npmjs.com/package/sendchamp-sdk/)
## Documentation
Take a look at the [API docs here](https://developers.sendchamp.com).
## Install
You can install the pacakge from [npm](https://npmjs.org) by running:
```shell
$ 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](https://github.com/fuadop/sendchamp-sdk/issues/6): https://github.com/fuadop/sendchamp-sdk/issues/6
```javascript
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: ["234812345678"],
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 :
```javascript
import Sendchamp from "sendchamp-sdk"; // es6 import
const Sendchamp = require("sendchamp-sdk").default; // 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`
- CALL Service: `sendchamp.CALL`
- EMAIL Service: `sendchamp.EMAIL`
- 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 2348123456789.
### SMS Service
```javascript
const sms = sendchamp.SMS;
```
- `sms.send({to, message, sender_name, route})`: API for sending SMS. Refer to sms test file([**tests**/sms.spec.ts](__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](https://support.sendchamp.com/article/14-sms-delivery-routing-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
```javascript
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](__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
```javascript
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
```javascript
const whatsapp = sendchamp.WHATSAPP;
```
Refer to the whatsapp test file ([**tests**/whatsapp.spec.ts](__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](https://github.com/fuadop/sendchamp-sdk/issues).
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Aliyu Abubakar
📝 💼 🖋 💵 🤔 🧑🏫 📦 💬 ✅ 📢
Fuad Olatunji
🐛 💻 🚇 🚧 🎨 💡 🛡️ 🔧 📓
The L D O
💻 🔧 📖