beamkenya / africastalking-elixir

An API Wrapper for the Africas Talking APl

   

AtEx

An API Wrapper for the Africas Talking API https://africastalking.com/

Table of contents

• Features
• Installation
• Configuration
• Documentation
• Contribution
• Licence

Features

We hope to cover all the endpoints of Africas Talking to help elixir developers integrate its services in their applications. Here are the main modules we hope to develop in the process.

• SMS
• Voice
• USSD
• Airtime
• Payments
• IoT
• Application

Installation

Available in Hex, the package can be installed by adding at_ex to your list of dependencies in mix.exs:

def deps do
  [
    {:at_ex, "~> 0.20.22"},
    
    # Optional, but recommended for prod
    {:hackney, "~> 1.17", only: :prod}
  ]
end

Configuration

• Create a dev.exs file under the config folder in the root of the project if you do not have it. like touch config/dev.exs to setup configs for development environment i.e, sandbox credentials check sample configuration below.
• Create a prod.exs file under the config folder in the root of the project if you dont have it. like touch config/prod.exs to setup at_ex configs for production environment i.e, live credentials. It is recommended that you also add tesla configuration, at least for your live environment. check sample configuration below.
• Copy the contents of dev.sample.exs into the dev.exs created above.
• Go to Africas Talking to register for an account.
• On signing up go to the https://account.africastalking.com/apps/sandbox to get an api key
• Add the api key in the api_key:value in the config/dev.exs created above.
• For sandbox, set the sandbox key to true

Example Configuration setup

Below is an example configuration for dev.exs this is suitable for testing with the sandbox:

config :at_ex,
  api_key: "===INSERT AFRICAS_TALKING_API_KEY HERE ===",
  # When changed to "false" one will use the live endpoint url
  sandbox: true,
  username: "sandbox",
  stk_product_name: "AtEx",
  b2c_product_name: "AtEx",
  b2b_product_name: "AtEx",
  bank_checkout_product_name: "AtEx",
  bank_transfer_product_name: "AtEx",
  card_checkout_product_name: "AtEx"

Below is an example configuration for prod.exs this is when you go live:

config :at_ex,
  api_key: "===INSERT AFRICAS_TALKING_LIVE_API_KEY HERE ===",
  username: "LIVE_USERNAME",
  # When changed to "false" one will use the live endpoint url
  sandbox: false,
  stk_product_name: "AtEx", #Add your specific product name.
  b2c_product_name: "AtEx",
  b2b_product_name: "AtEx",
  bank_checkout_product_name: "AtEx",
  bank_transfer_product_name: "AtEx",
  card_checkout_product_name: "AtEx"

config :tesla, adapter: Tesla.Adapter.Hackney

Documentation

The docs can be found at https://hexdocs.pm/at_ex.

Quick examples

Sending SMS

    iex> AtEx.Sms.send_sms(%{to: "[phone]", message: "Howdy"})
    {:ok,
    %{
        "SMSMessageData" => %{
        "Message" => "Sent to 1/1 Total Cost: ZAR 0.1124",
        "Recipients" => [
        %{
            "cost" => "KES 0.8000",
            "messageId" => "ATXid_96e52a761a82c1bad58e885109224aad",
            "number" => "[phone]",
            "status" => "Success",
            "statusCode" => 101
        }
        ]
    }
    }}

Payment Mobile checkout

    iex>AtEx.Payment.mobile_checkout(%{phoneNumber: "254724540000", amount: 10, currencyCode: "KES"})
    %{
        "description" => "Waiting for user input",
        "providerChannel" => "525900",
        "status" => "PendingConfirmation",
        "transactionId" => "ATPid_bbd0bcd713e27d9201807076c6db0ed5"
    }

Contribution

If you'd like to contribute, start by searching through the issues and pull requests to see whether someone else has raised a similar idea or question. If you don't see your idea listed, Open an issue.

Check the Contribution guide on how to contribute.

Maintainers

The current maintainers of the project are:

1. Tracey Onim
2. Manuel Magak
3. Paul Oguda
4. Sigu Magwa

Past Maintainers

1. Zacck Osiemo Thanks for kicking off the project 😉.

Licence

AtEx is released under MIT License

africastalking-elixir's Issues

Feature Request: Payment/Card Validate

Card checkout validation APIs allow your application to validate card checkout charge requests.
https://build.at-labs.io/docs/payments%2Fcard%2Fvalidate

Feature Request: Payment/Mobile B2B

Mobile Business To Business (B2B) APIs allow you to send payments to businesses e.g banks from your Payment Wallet.
https://build.at-labs.io/docs/payments%2Fmobile%2Fb2b

Feature Request: Call Transfer

Is your feature request related to a problem? Please describe.
Make it possible to transfer your call to another number by making a HTTP POST request to one of the following endpoints:
Endpoints
Live: https://voice.africastalking.com/callTransfer
Sandbox: https://voice.sandbox.africastalking.com/callTransfer

Describe the solution you'd like
A clear and concise description of what you want to happen.

Work Involved
create a call_transfermethod in the AtEx.Gateway.Voicemodule that fullfills the makes a post request to the above endpoints. The method takes the request parameters listed in the Request Parameters Section

Definition of Done
Generate an xml response like below

<callTransferResponse>
    <status>Success</status>
    <errorMessage>None</errorMessage>
</callTransferResponse>

Additional context
Check out the documentation on Call Transfer for all the details.

Feature Request: SMS Functionality

Is your feature request related to a problem? Please describe.
To send and fetch SMS(es) from Africas Talking, we need to wrap API calls for sending and fetching of messages from AT

Ideally, we provide a function to send an SMS to a number and we provide another function to fetch SMS(es) from your application inbox.

Describe the solution you'd like

1. Provide an SMS send function that accepts SMS sending parameters according to https://build.at-labs.io/docs/sms%2Fsending.

2. Provide a function to fetch SMS(es) that accepts SMS fetching parameters according to https://build.at-labs.io/docs/sms%2Ffetch_messages

Work Involved

1. Send SMS

• Build SMS send function

2. Fetch Messages

• Build an sms fetch function

3. Premium Subscription

• Generate a checkout token.
• Subscribe a phone number.
• Fetch Subscriptions.
• Delete Subscription.

Definition of Done

• A developer using the library should be able to send SMS by providing a map of parameters to a single function.

• A developer using the library should be able to fetch SMS(es) by providing a map of parameters to a single function.

Additional context*
We need to provide configuration options to allow a developer to set AT standard headers https://build.at-labs.io/docs/getting_started/request_headers

Feature Request: Voice/Call Transfer

You can transfer your call to another number by making a HTTP POST request to one of the following endpoints:
https://build.at-labs.io/docs/voice%2Fcall_transfer

Feature Request: Delete Subscription

Is your feature request related to a problem? Please describe.
Add the ability to delete a premium sms subscription by making a HTTP POST request to the following endpoints:
Live: https://api.africastalking.com/subscription/delete
Sandbox: https://api.sandbox.africastalking.com/subscription/delete

Describe the solution you'd like
A clear and concise description of what you want to happen.

Work Involved
What would would need to be done to deliver this?

Definition of Done
After making a request you should be able to get a response of this nature
{
"status": "Success",
"description": "Succeeded"
}

Feature Request: Handling a call

Is your feature request related to a problem? Please describe.
Handling calls made to your Africa’s Talking phone number is as easy as implementing a script on your web server that handles HTTP POST requests.

Describe the solution you'd like
A clear and concise description of what you want to happen.

Work Involved
Here is how it all comes together…

• AfricasTalking receives a call to your phone number on their voice gateways, or you successfully initiate a call using their calling API
• Their API sends a POST request to the notification callback URL that you have set for that phone number in your Voice Dashboard.
• Your application responds with XML that tells their API how to handle the call. This XML will typically contain a list of actions that their API will execute in sequence.
• Their API translates those actions into events or messages relayed back to the caller.

Additional context
For more context you can look into this handle call documentation

Feature Request: Setting up Environment Variables

Elixir wrapper should:-

• Enable developers to provide their own api_key, content_type they prefer, and also username (generally the request headers) that are required by Africastalking API
• Ensure that the developer can configure the application to work in production, development, and test environment effectively.

Need to create asynchronous requests to AT

Is your feature request related to a problem? Please describe.
There already exists synchronous requests, so there's need to come up with asynchronous requests too.
This is an added option which AT allows when sending SMS

Feature Request: Voice Calls

Is your feature request related to a problem? Please describe.
There is need to create a wrapper that will be used to communicate with Africastalking Voice APIs which is cloud based. This will help businesses to reduce their business costs while increasing the efficiency of how reach out to their users. Voice Overview

Describe the solution you'd like
1.Making a Call
Provide ability to make an outbound call through Africastalking Voice API by sending a HTTP POST request to Africastalking api one of the following africastalking endpoints:
Endpoints
Live: https://voice.africastalking.com/call
Sandbox:https://voice.sandbox.africastalking.com/call
Work Involved

Build a Making call function in the Voice Module.
def making_call(params) do; end
Definition of Done

A developer using the library should be able to Make a call the making_call function and receive the following response:
{ "entries": [ { "phoneNumber": "+234XXXYYYZZZZ", "status": "Queued", "sessionId": "ATVId_abcdef" } ], "errorMessage": "None" }

2. Handling a Call
   Provide ability to handle calls made to your Africa’s Talking phone number by implementing a script on your web server that handles HTTP POST requests.

Work Involved

Definition of Done

A developer using the library should be able to Handle calls made to their phone number through africastalking api.

ToDO

• Build making call function.
• Build ability to handle calls made to your phone number.

Feature Request: Payment Wallet Transfer

Wallet transfer APIs allow you to transfer money from one Payment Product to another Payment Product hosted on Africa’s Talking.
https://build.at-labs.io/docs/payments%2Fwallet_transfer

Getting 401 on every requests on sandbox

Describe the bug
Hi guys, i'm using the https://github.com/beamkenya/africastalking-elixir library. I would like to send sms, my configuration is as follows:

config :at_ex,
  api_key: "cabd08628c5283ee652b76256d6cfd79bfb0ca847f594bdb04453eb0493b2e6d",
  # change to live username if you want to use the live endpoint while in development
  username: "sandbox",
  # When changed to "YES" one will use the live endpoint url when in development
  force_live_url: "NO"

but i'm getting the following error

AtEx.Sms.send_sms(%{to: "[phone]", message: "Howdy"})
{:error, %{message: "The supplied authentication is invalid", status: 401}}

I have tested the same apikey on curl and i get a positive response but it fails when i use the beam kenya library. Any ideas why i'm getting the 401. Also how do we configure the shortcode

Expected behavior
The API should be working well for 'env` sandbox

@community User - Quoted

Feature Request: Making HTTP requests

Is your feature request related to a problem? Please describe.
One should be able to make an HTTP POST to publish messages to your remote devices. to the following endpoints :
Endpoints
Live: https://iot.africastalking.com/data/publish
Sandbox: Coming Soon

Request Parameters

Parameter	Description
username String Required	Africa’s Talking application username
deviceGroup String Required	The device group to which the message is to be sent
topic String Required	The messaging channel to which the message is to be sent. In the form <username>/<device-group>/<the-topic>
payload String Required	The message packet to be sent to the subscribed devices

API Response
The API responds with a JSON payload with the following fields:

Parameter	Description
status String	This is the response status of the API request. The values can either be true : The request went through successfully. false: The request failed.
description String	This is a verbose response message detailing the status of the HTTP response. The expected contents are as follows: Message processed successfully: Message was successfully published. Publishing not allowed: The device group access level does not allow publishing. The group is a Sub group The provided topic does not belong to the user: The topic to which the message was published to is not part of the target device group.

Feature Request: Payment/Bank Validation

Bank checkout validation APIs allow your application to validate bank checkout charge requests.
https://build.at-labs.io/docs/payments%2Fbank%2Fvalidate

Feature Request: Voice Upload media file

https://build.at-labs.io/docs/voice%2Fupload_media_file

Update doc for b2c/mobile checkout / refactor at_ex.ex

Need to add detail for user to include keys for the product names, in the config files
validation format

Feature Request: Sending SMS

The implementation involves creating a module that will allow devs using the Elixir wrapper to send SMS

Feature Request: Payment/Query Find Transaction

Find a particular payment transaction by sending a HTTP GET request to the following endpoint:
https://build.at-labs.io/docs/payments%2Fquery%2Ffind_transaction

Enable using API endpoints for different ENVs

Describe the bug
Currently all the API requests hit the sandbox apis, this is not the expected behavior

Expected behavior
In dev and 'testenv, the API need to hit thesandboxAPI andproductionAPI inprod` env

Remove the endpoint in the configs

Feature Request: Mobile Checkout

Is your feature request related to a problem? Please describe.
Mobile Checkout APIs should a user to initiate Customer to Business (C2B) payments on a mobile subscriber’s device.

Work Involved
The work involved in delivering this entails Initiating a mobile checkout request by sending a HTTP POST request to the following endpoint:
Endpoints
Live: https://payments.africastalking.com/mobile/checkout/request
Sandbox: https://payments.sandbox.africastalking.com/mobile/checkout/request

Parameter	Description
username String Required	Your Africa’s Talking application username.
productNameStringRequired	Your Africa’s Talking Payment product to initiate this transaction.
providerChannel String Optional	The provider channel the payment will be initiated from e.g a paybill number. The provider channel must be mapped to your Africa’s Talking payment product.
phoneNumber String Required	Phone number - in international format - of the client that will complete this transaction.
currencyCode String Required	3-digit ISO format currency code for the value of this transaction (e.g KES, UGX, USD)
amountDecimalRequired	Amount - in the provided currency - that the client is expected to confirm.
metadata Map<Str,Str> Optional	A map of any metadata that you would like us to associate with the request. Use this field to send data that will map notifications to mobile checkout requests. It will be included in the notification we send once the client completes the mobile checkout request.

Definition of Done
A client should have a smoother checkout experience, since the client will no longer need to remember the amount or an account number to complete the transaction.

API response

Parameter	Description
status String	The status of the request. Possible values are:PendingConfirmation: The request has been accepted and we are waiting for the subscriber to confirm the payment.InvalidRequest: The request could not be accepted as one of the fields was invalid. The description field will contain more information.NotSupported: Checkout to the provided phone number is not supported.Failed: The request failed for some other reason. The description filed will contain more information.
description String	A detailed description of the request status.
transactionId String Optional	A unique id that our API generates for successful requests. This transactionId will be sent along with the payment notification.
providerChannel String Optional	The provider channel that was used to initiate this transaction.

Sample response:

{
    "status": "PendingConfirmation",
    "description": "Waiting for user inout",
    "transactionId": "ATPid_SampleTxnId123",
    "providerChannel": "345678",
}

Additional context
More information can be found in the AfricasTalking Mobile Checkout documentation ----Here---

Feature Request: Payment Top Up Stash

Topup stash APIs allow you to move money from a Payment Product to an Africa’s Talking application stash. An application stash is the wallet that funds your service usage expences.
https://build.at-labs.io/docs/payments%2Ftopup_stash

Feature Request: Payment/Query Fetch Wallet Transactions

Fetch your wallet transactions by sending a HTTP GET request to the following endpoint:
https://build.at-labs.io/docs/payments%2Fquery%2Ffetch_wallet_transactions

Feature Request: Voice/Queue Calls

Queuing is a feature mainly used when you have more calls than you can handle at one time. Incoming calls will be put in a queue and handled one by one until all of them are out of the queue (dequeued).
https://build.at-labs.io/docs/voice%2Fqueue_status

Feature Request: Fetch Subscriptions

Is your feature request related to a problem? Please describe.
This functionality allows one to incrementally fetch their premium sms subscriptions. To do so, you make a HTTP GET request to the following endpoints:
Endpoints
Live: https://api.africastalking.com/version1/subscription
Sandbox: https://api.sandbox.africastalking.com/subscription

Describe the solution you'd like
The details of the implementation are as shown on this page Fetch Subscriptions

Definition of Done
Ability to get a response as the following upon a successful request:

{
"responses": [{
"id": 100,
"phoneNumber": "+254711XXXYYY",
"date": "Timestamp"
}, {
"id": 200,
"phoneNumber": "+254733YYYZZZ",
"date": "Timestamp"
}]
}

Feature Request: Send Airtime

Is your feature request related to a problem? Please describe.
Distribute virtual, pinless airtime to your users instantly.

Describe the solution you'd like
Provide an airtime send function accepting parameters as shown in Sending Airtime
Work Involved

• Build Airtime send function

Definition of Done

• A developer using the library should be able to send Airtime to list with maps of recipients.[{"phoneNumber":"+254711XXXYYY","amount":"KES X"}]

Feature Request: Subscribe a phone number

Is your feature request related to a problem? Please describe.
Subscribe a phone number by making a HTTP POST request to the following endpoints:
Live: https://api.africastalking.com/version1/subscription/create
Sandbox: https://api.sandbox.africastalking.com/version1/subscription/create

Work Involved
Check out the Subscribe a phone number section in Africastalking API.

Definition of Done
Be able to generate a response as a JSON object containing the following fields:

{ "status": "Success", "description": "Waiting for user input" }

Feature Request: Implement Doctest

Is your feature request related to a problem? Please describe.
Presently we are not doing most of the doctest, and yet we have a number of them in the application.

Describe the solution you'd like
There is need to integrate the doctests into our tests, this will involve ensuring that each doctest is passing, tried a few and they were not passing.

Work Involved
Adding doctest to the tests, and ensuring that they are passing.

Definition of Done
Have all the doctests, in the page passing and added to their respective tests.

Additional context
Add any other context or screenshots about the feature request here.

Feature Request: Payment

Is your feature request related to a problem? Please describe.
Africas Talking Payments APIs that lets you quickly integrate and manage payments in your application. Payments APIs can be used to for users in Kenya, Nigeria and Uganda.

Describe the solution you'd like
There is need to implement the payment api that is fully working in elixir.

Work Involved
There will be issues surrounding the implementation of the payment api.

Definition of Done
Once all the key functionalities have been implemented.

Additional context
For more information about the Pyaments Api of AfricasTalking checkout -----THIS----

Feature Request: Payment/Query Fetch Wallet Balance

Fetch your wallet balance by sending a HTTP GET request to the following endpoint:
https://build.at-labs.io/docs/payments%2Fquery%2Fwallet_balance

Feature Request: Payment/Bank Transfer

Bank Tranfer APIs allow you to move money from your Payment Wallet to bank accounts.
https://build.at-labs.io/docs/payments%2Fbank%2Ftransfer

Feature Request: Payment/Bank Checkout

Bank checkout APIs allow your application to collect money into your payment wallet by initiating transactions that deduct money from a customers bank account.
https://build.at-labs.io/docs/payments%2Fbank%2Fcheckout

Fix failling CI pipeline

Describe the bug
A clear and concise description of what the bug is.

CI pipeline fails #91

To Reproduce
Steps to reproduce the behavior:
https://github.com/beamkenya/africastalking-elixir/runs/3597704301

Expected behavior
Should pass

Additional context
Add any other context about the problem here.

Feature Request: Create Subscription for Premium SMS

Is your feature request related to a problem? Please describe.
Need for an application to complete complete a premium sms create subscription request
Describe the solution you'd like
Implement the functionality through this instruction on Africastalking site.

Work Involved

• Generate a checkout token.
• Subscribe a phone number.
• Fetch Subscriptions.
• Delete Subscription.

Definition of Done
A clear and concise description of what done would look like for this issue

Additional context
Add any other context or screenshots about the feature request here.

Feature Request: Payment/Query Fetch Product Transactions

Fetch transactions of a particular payment product by sending a HTTP GET request to the following endpoint:
https://build.at-labs.io/docs/payments%2Fquery%2Ffetch_product_transactions

Feature Request: IoT Notifications

Is your feature request related to a problem? Please describe.
The IoT API sends a notification when a device publish event occurs. To receive these notifications you need to setup a callback URL depending on the type of notification.

Feature Request: Make a Call

Is your feature request related to a problem? Please describe.
This should allow one to make an outbound call through our Voice API by sending a HTTP POST request to one of the following endpoints:
Endpoints

• Live: https://voice.africastalking.com/call
• Sandbox: https://voice.sandbox.africastalking.com/call

Describe the solution you'd like
In addition to the standard request headers, the request should contain the following fields:

Parameter	Location	Description
Content-Type Required	Header	The requests content type. Can be application/x-www-form-urlencoded or multipart/form-data
username String Required	Body	Your Africa’s Talking application username
from String Required	Body	Your Africa’s Talking phone number (in international format i.e. +XXXYYYYYY)
to String Required	Body	A comma separated string of recipients’ phone numbers.
clientRequestId String Optional	Body	Variable sent to your Events Callback URL that can be used to tag the call

Work Involved
What would need to be done to deliver this?

Definition of Done
One should be able to get a body of the response that is an a XML object containing the following fields:

Parameter	Description
entries List	A list with multiple Entry each corresponding to an individual phone number and their status. Entry is a Map with details of queued numbers.phoneNumber: String The phone number queued. status: String The status of the request associated to this phone number. Possible values are: Queued: The call request has been accepted and queued InvalidPhoneNumber: Recipient number is in an incorrect format DestinationNotSupported: Recipient number is outside the supported zone InsufficientCredit: Your AfricasTalking account has insufficient balance. sessionId: String A unique id for the request associated to this phone number. Defaults to None if an error occured.
errorMessage String Optional	Error message if the ENTIRE request was rejected by the API.

Work will be considered done if you get a response as below:
{ "entries": [ { "phoneNumber": "+234XXXYYYZZZZ", "status": "Queued", "sessionId": "ATVId_abcdef" } ], "errorMessage": "None" }

Additional context
For detailed instruction checkout the Making a call api documentation

Feature Request: Handling Error while sending SMS

This implementation captures how best we can handle errors received from AT API. How best can they be displayed to users implementing send SMS functionality?

Request Validation

Check for required param to and from if present and not empty

Feature Request: Payment/Card Checkout

Card Checkout APIs allow your application to collect money into your Payment Wallet by initiating transactions that deduct money from a customers Debit or Credit Card.
https://build.at-labs.io/docs/payments%2Fcard%2Fcheckout

Feature Request: Add a contribution guide

Feature Request.
There is no guide for rules that should be followed when contributing to the project . for example how to create branches and PR's

Describe the solution you'd like
There should be a uniform format for creating branches and PR's

Work Involved
Discuss and agree on rules to be followed when contributing. Then write it down for other developers who would like to make contributions to the project.

Definition of Done
A clear and concise description of what done would look like for this issue

Additional context
Add any other context or screenshots about the feature request here.

Feature Request: Generate a checkout token

Is your feature request related to a problem? Please describe.
Two endpoints are required in order for your application to complete a premium sms create subscription request.
These are:

1. Checkout Token request: The checkoutToken is used to authorize a premium sms subscription. It is required in order to subscribe a phone number.
2. Subscription request: Once a checkoutToken is received it should be sent along with the rest of the parameters to initiate the actual subscription request.

Describe the solution you'd like
Generate a checkoutToken by making a HTTP POST request to the following endpoints:
Endpoints
Live: https://api.africastalking.com/checkout/token/create
Sandbox: https://api.sandbox.africastalking.com/checkout/token/create

Work Involved
Detailed explanation in the Generate a checkout token section.

Definition of Done
Below is a sample generate checkout token response for a successful request that is expected:
{ "description": "Success", "token": "CkTkn_SampleCkTknId123" }
Additional context
Add any other context or screenshots about the feature request here.