#Africa's Talking Libraries and SDKs Open Source Contribution Guideline

This is a brief outline on coming up with libraries and SDKs for the Africa's Talking platform, happy coding 👨🏾‍💻

The SDK map to each of API endpoints as outlined in the API reference. The functionality it exposes should be grouped/namespaced per product i.e. SMS, Airtime, Voice, USSD Chat and Insights. Also required of the SDK is a comprehensive README.md file outlining available methods, arguments and other, requirements as well as a usage guide.

The README.md must contain the following sections:

• Install: Show/Describe how one can get the SDK into their project using our package managers.

• Usage: Show simple sample code that demonstrates the SDK usage; showcase only one product say sms.

• Initialization: Describe how to initialize the SDK

• Services/Products: Outline methods, params available for every product/service.

Initialization

The SDK should be initialized from a single entry point, with an app username and API key.

AfricasTalking::initialize(APP_USERNAME, API_KEY)

The SDK will always assume sandbox and therefore use sandbox APIs if it is initialized with an app username sandbox.

Usage

Each product instance should be retrieved thereafter from the entry point as follows:

val sms = AfricasTalking::SMS // or     
val sms = AfricasTalking::getSms() // or   
val sms = AfricasTalking::getSmsService()

Each product function will then be used on the product instance as follows:

val result = sms.send(options)

The result of every function should be an object native to the language instead of the json or xml returned by the target API.

Here is a simple 'send SMS' example:

AfricasTalking::initialize('sandbox', 'ABDJKEY')   
val sms = AfricasTalking::getSms()    
val result = sms.send('Hi There!', ['+254718767881'], 'AwesomeBot')    
print result

Languages

The following languages are officially supported:

• PHP

• Java

• JavaScript (Node.js)

• Python

• C#

• Ruby

• Android (Java), iOS (Swift)* Libraries for other languages should be left to the community to build and maintain.

Distribution

The SDK should be versioned using semantic versioning. Users should be able to access the SDK full source code from GitHub. In addition, users should be able to easily import the SDK in their projects using the official/popular package manager for the language they are using:

Products

For each product, the SDK should provide the functions outlined below. The functions should be asynchronous, depending on the language features.

The function parameters can be collapsed into one object depending on the language
All phone numbers are in the international format. e.g. +2439083747754
All amounts are strings containing the currency code and the actual amount. e.g. USD 14.56

Airtime

• send(phoneNumber: String, amount: String): Send airtime to a phone number.

• send(recipients: List<Map<String,String>>): Send airtime to a bunch of phone numbers. The keys in the recipients map are phone numbers while the values are airtime amounts.

SMS

• send(message: String, recipients: List<String>, senderId: Optional<String>, enqueue: Optional<Boolean>): Send a bulk message to recipients, optionally from senderId (Short Code or Alphanumeric).

• sendPremium(message: String, keyword: String, linkId: String, recipients: List<String>, senderId: Optional<String>, retryDurationInHours: Optional<Integer>): Send a premium SMS

• fetchMessages(lastReceivedId: Optional<Integer>): Fetch your messages

• fetchSubscriptions(shortCode: String, keyword: String, lastReceivedId: Optional<Integer>): Fetch your premium subscription data

• createSubscription(shortCode: String, keyword: String, phoneNumber: String, checkoutToken: String): Create a premium subscription

• deleteSubscription(shortCode: String,keyeord: String, phoneNumber: String): Remove a premium subscription.

Voice

• call(phoneNumber: String): Initiate a phone call

• fetchQueuedCalls(phoneNumber: String): Get queued calls

• uploadMediaFile(phoneNumber: String, url: String): Upload voice media file

• ActionBuilder: Build voice XML when callback URL receives a POST from the voice API

  • say(text: String)

  • play(url: String)

  • getDigits(text: String, url: String, numDigits: Integer, timeout: Integer, finishOnKey: String, callbackUrl: String)

  • dial(phoneNumbers: String, ringbackTone: String, record: Boolean, sequential: Boolean, callerId: String, maxDuration: Integer)

  • conference()

  • record()

    • record(String text, URL url, int maxLength, long timeout, String finishOnKey, boolean trimSilence, boolean playBeep, URL callbackUrl)

  • enqueue()

  • dequeue()

  • reject()

  • redirect()

  • build(): Finally, build the XML

USSD

• CON

• END

Others

Application

fetchApplicationData(): Fetch app info i.e. balance.

Token

generateAuthToken(): Generate an auth token to use for authentication instead of the API key.