Elixir client library for Africa's Talking API
A simple, robust Elixir library for integrating with Africa's Talking services. This library provides easy-to-use functions for sending SMS messages and airtime transfers.
- 📱 SMS Messaging - Send SMS to single or multiple recipients
- 💰 Airtime Transfer - Send airtime to multiple recipients with different currencies
- 🔒 Secure - Proper API key handling and validation
- ⚡ Fast - Built with Hackney for efficient HTTP requests
- 🧪 Well Tested - Comprehensive test coverage
- 📖 Well Documented - Complete documentation with examples
Add africastalking_elixir to your list of dependencies in mix.exs:
def deps do
[
{:africastalking_elixir, "~> 0.1.0"}
]
endThen run:
$ mix deps.getConfigure your Africa's Talking credentials in config/config.exs:
config :africastalking_elixir,
username: "your_username",
api_key: "your_api_key",
base_url: "https://api.africastalking.com" # Use sandbox URL for testingFor production environments, you can use environment variables:
config :africastalking_elixir,
username: {:system, "AFRICASTALKING_USERNAME"},
api_key: {:system, "AFRICASTALKING_API_KEY"},
base_url: {:system, "AFRICASTALKING_BASE_URL"}- Sandbox:
https://api.sandbox.africastalking.com(for testing) - Production:
https://api.africastalking.com(for live transactions)
# Send SMS to a single recipient
{:ok, response} = AfricastalkingElixir.send_sms("+254722000000", "Hello World!")
# Send SMS to multiple recipients
{:ok, response} = AfricastalkingElixir.send_sms(
"+254722000000,+254733000000,+254744000000",
"Hello everyone!"
)# Send airtime to single recipient
recipients = [
%{
phone_number: "+254722000000",
amount: 100,
currency_code: "KES"
}
]
{:ok, response} = AfricastalkingElixir.send_airtime(recipients)
# Send airtime to multiple recipients with different amounts
recipients = [
%{phone_number: "+254722000000", amount: 100, currency_code: "KES"},
%{phone_number: "+254733000000", amount: 50, currency_code: "KES"},
%{phone_number: "+234803000000", amount: 200, currency_code: "NGN"}
]
{:ok, response} = AfricastalkingElixir.send_airtime(recipients)# Basic SMS
case AfricastalkingElixir.send_sms("+254722000000", "Hello World") do
{:ok, %{status_code: 201, africastalking_response: response}} ->
IO.puts("SMS sent successfully!")
IO.inspect(response)
{:error, reason} ->
IO.puts("Failed to send SMS: #{reason}")
end
# SMS to multiple recipients
phones = "+254722000000,+254733000000"
message = "Meeting at 3 PM today. Please confirm."
{:ok, response} = AfricastalkingElixir.send_sms(phones, message)# Single airtime transfer
recipients = [
%{
phone_number: "+254722000000",
amount: 100,
currency_code: "KES"
}
]
case AfricastalkingElixir.send_airtime(recipients) do
{:ok, %{status_code: 201, africastalking_response: response}} ->
IO.puts("Airtime sent successfully!")
IO.inspect(response)
{:error, reason} ->
IO.puts("Failed to send airtime: #{reason}")
end
# Bulk airtime transfer
recipients = [
%{phone_number: "+254722000000", amount: 100, currency_code: "KES"},
%{phone_number: "+254733000000", amount: 50, currency_code: "KES"},
%{phone_number: "+234803000000", amount: 200, currency_code: "NGN"},
%{phone_number: "+233240000000", amount: 5, currency_code: "GHS"}
]
{:ok, response} = AfricastalkingElixir.send_airtime(recipients)SMS is supported in all Africa's Talking supported countries.
Common supported currencies include:
- KES - Kenyan Shilling
- UGX - Ugandan Shilling
- TZS - Tanzanian Shilling
- RWF - Rwandan Franc
- ZMW - Zambian Kwacha
- NGN - Nigerian Naira
- GHS - Ghanaian Cedi
- XOF - West African CFA Franc
- XAF - Central African CFA Franc
- ETB - Ethiopian Birr
- MWK - Malawian Kwacha
- USD - US Dollar
{:ok, %{
status_code: 201,
africastalking_response: %{
"SMSMessageData" => %{
"Message" => "Sent to 1/1 Total Cost: KES 0.8000",
"Recipients" => [
%{
"cost" => "KES 0.8000",
"messageId" => "ATXid_sample123",
"number" => "+254722000000",
"status" => "Success",
"statusCode" => 101
}
]
}
}
}}{:ok, %{
status_code: 201,
africastalking_response: %{
"entries" => [
%{
"phoneNumber" => "+254722000000",
"amount" => "KES 100.0000",
"status" => "Sent",
"requestId" => "ATQid_sample123",
"discount" => "KES 2.0000"
}
],
"numQueued" => 1,
"totalAmount" => "KES 100.0000",
"totalDiscount" => "KES 2.0000"
}
}}The library provides detailed error messages for various scenarios:
# Invalid phone number
{:error, "One of the phone numbers is invalid, Please check and try again"}
# Missing recipient
{:error, "Recipient is required. Please provide a string number or a comma separated list of string phone numbers"}
# Invalid currency code
{:error, "One of the currency codes does not conform to the 3-digit ISO standard"}
# Missing required fields for airtime
{:error, "Phone number, currency code and amount must be specified for each recipient"}
# Network or API errors
{:error, "timeout"}
{:error, "connection_failed"}Phone numbers should be in international format:
- ✅
"+254722000000"(with country code) - ✅
"254722000000"(without + sign) - ✅
"0722000000"(local format, will be validated) - ❌
"722000000"(missing country/area code)
Run the test suite:
$ mix testFor testing with the sandbox environment, make sure to use the sandbox URL in your configuration:
config :africastalking_elixir,
username: "sandbox",
api_key: "your_sandbox_api_key",
base_url: "https://api.sandbox.africastalking.com"Full documentation is available on HexDocs.
You can also generate documentation locally:
$ mix docs- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- 📧 Email: support@africastalking.com
- 📖 API Documentation: Africa's Talking Docs
- 🐛 Issues: GitHub Issues
- africastalking-python - Python SDK
- africastalking-node - Node.js SDK
- africastalking-php - PHP SDK