africastalking sandbox-node.js
AfricasTalking node.js Sandbox API wrapper
About
This is a wrapper for the Africa's Talking Sandbox API. It tracks the Official Africa's talking API. The documentation provided here is the same.
Install
$ npm install --save atsandbox
Initialization
var options = {
apiKey: 'YOUR_API_KEY',
username: 'YOUR_USERNAME',
format: 'json' // or xml
};
var AfricasTalking = require('africastalking')(options);
// ...
Important
: If you register a callback URL with the API, always remember to acknowledge the receipt of any data it sends by responding with an HTTP 200
; e.g. res.status(200);
for express.
SMS
var sms = AfricasTalking.SMS;
// all methods return a promise
sms.send(opts)
.then(success)
.catch(error);
Sending SMS
-
send(options)
: Send a message.options
contains:-
to
: A single recipient or an array of recipients.REQUIRED
-
from
: Shortcode or alphanumeric ID that is registered with Africa's Talking account. -
message
: SMS content.REQUIRED
-
-
sendBulk(options)
: Send bulk SMS. In addition to paramaters ofsend()
, we would have:-
enqueue
: "[...] would like deliver as many messages to the API before waiting for an Ack from the Telcos."
-
-
sendPremium(options)
: Send premium SMS. In addition to paramaters ofsend()
, we would have:-
keyword
: Value is a premium keywordREQUIRED
-
linkId
: "[...] We forward thelinkId
to your application when the user send a message to your service"REQUIRED
-
retryDurationInHours
: "It specifies the number of hours your subscription message should be retried in case it's not delivered to the subscriber"
-
Retrieving SMS
You can register a callback URL with us and we will forward any messages that are sent to your account the moment they arrive. Read more
-
fetchMessages(options)
: Manually retrieve your messages.-
lastReceivedId
: "This is the id of the message that you last processed". Defaults to0
.REQUIRED
-
Premium Subscriptions
If you have subscription products on your premium SMS short codes, you will need to configure a callback URL that we will invoke to notify you when users subscribe or unsubscribe from your products. Read more
-
createSubscription(options)
:-
shortCode
: "This is a premium short code mapped to your account".REQUIRED
-
keyword
: "Value is a premium keyword under the above short code and mapped to your account".REQUIRED
-
phoneNumber
: "The phoneNumber to be subscribed"REQUIRED
-
-
fetchSubscription(options)
:-
shortCode
: "This is a premium short code mapped to your account".REQUIRED
-
keyword
: "Value is a premium keyword under the above short code and mapped to your account".REQUIRED
-
lastReceivedId
: "ID of the subscription you believe to be your last." Defaults to0
-
USSD
Processing USSD requests using our API is very easy once your account is set up. In particular, you will need to:
- Register a service code with us.
- Register a URL that we can call whenever we get a request from a client coming into our system.
Once you register your callback URL, any requests that we receive belonging to you will trigger a callback that sends the request data to that page using HTTP POST. Read more.
If you are using connect-like frameworks (express), you could use the middleware AfricasTalking.USSD(handler)
:
handler(params, next)
: Process USSD request and call next()
when done.
-
params
: contains the following user data sent by Africa's Talking servers:sessionId
,serviceCode
,phoneNumber
andtext
. -
next(args)
:args
must contain the following:-
response
: Text to display on user's device.REQUIRED
-
endSession
: Boolean to decide whether to END session or to CONtinue it.REQUIRED
-
// example (express)
app.post('/natoil-ussd', new AfricasTalking.USSD((params, next) => {
var endSession = false;
var message = '';
var session = sessions.get(params.sessionId);
var user = db.getUserByPhone(params.phoneNumber);
if (params.text === '') {
message = "Welcome to Nat Oil \n";
message += "1: For account info \n";
message += "2: For lost gas cylinder";
} else if (params.text === '1') {
message = user.getInfo();
endSession = true;
} else if (params.text === '2') {
message = "Enter 1 for recovery \n";
message += "Enter 2 for lost and found";
endSession = true;
} else {
message = "Invalid option";
endSession = true;
}
next({
response: message,
endSession: endSession
});
}));
Voice
var voice = AfricasTalking.VOICE;
- Helpers that will construct proper
xml
to send back to Africa's Taking API when it comesPOST
ing. Read more-
Say
,Play
,GetDigits
,Dial
,Record
,Enqueue
,Dequeue
,Conference
,Redirect
,Reject
-
- Initiate a call
- Fetch call queue
-
Media upload- any url toPlay
will be cached by default. - Remember to send back an HTTP 200.
Initiate a call
voice.call({
callFrom: '+2547XXXXXXXX', // AT virtual number
callTo: from_
})
.then(function(s) {
// persist call Info
console.log(s);
})
.catch(function(error) {
console.log(error);
});
Fetch call queue
voice.getNumQueuedCalls({
phoneNumbers: destinationNumber
})
.then(function(s) {
// call queue
console.log(s);
})
.catch(function(error) {
console.log(error);
});
Handle call **TODO Build helpers
check issue #15
Airtime
var airtime = AfricasTalking.AIRTIME;
-
airtime.send(options)
: Send airtime-
recipients
: An array of the following-
phoneNumber
: Recipient of airtime -
amount
: Amount sent.>= 10 && <= 10K
-
-
airtime.send(options)
.then(success)
.catch(error);
Account
AfricasTalking.fetchAccount()
.then(success)
.catch(error);
-
fetchAccount()
: Fetch account info; i.e. balance
Mobile Money (mpesa) - check out
var payment = AfricasTalking.PAYMENT;
payment.checkOut({
phoneNumber : '+2547XXXXXXXX',
productName : 'your_productName',
currencyCode : 'KES',
metadata : { id: uuid.v4() },
amount : 100
})
.then(function(s) {
// persist payment status
console.log(s);
})
.catch(function(error) {
console.log(error);
});
B2B (mpesa)
???
B2C (mpesa)
???