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: "+254722000000", message: "Howdy"})
    {:ok,
    %{
        "SMSMessageData" => %{
        "Message" => "Sent to 1/1 Total Cost: ZAR 0.1124",
        "Recipients" => [
        %{
            "cost" => "KES 0.8000",
            "messageId" => "ATXid_96e52a761a82c1bad58e885109224aad",
            "number" => "+254722000000",
            "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