aftalk

This is a Ruby wrapper for Africa's Talking telephony services.

NOTE: Currently the gem supports only the /messaging endpoint, which is for for sending (POST) and fetching (GET) SMS messages. Support for other endpoints is planned for future releases.

Installation

Add

gem "aftalk"

to your Gemfile and run

$ bundle

or install manually by running

gem install aftalk.

Configuration

Africa's Talking needs a username and an API key to authenticate your requests. You can also toggle sandbox mode, which causes the gem to hit AF's sandbox host instead of the live API. (Note: Use of sandbox mode requires that you provide the username sandbox. This is not well documented.)

There are two ways to configure these options.

Set environment variables

The first way to configure aftalk is by setting environment variables. You can do this by creating a file called .env in your project root and adding content like this to it:

AFRICAS_TALKING_API_KEY=abc123
AFRICAS_TALKING_USER_NAME=sandbox
AFRICAS_TALKING_SANDBOX=true

Replace the values with your own data. Sandbox mode will be activated if any value whatsoever is provided for AFRICAS_TALKING_SANDBOX. If you don't want to use sandbox mode, don't set this variable at all.

Use AfTalk::Configuration

You can also configure this data in Ruby code as follows:

AfTalk::Configuration.configure do |config|
  config.api_key = "abc123"
  config.sandbox = true
  config.user_name = "sandbox"
end

Make sure this code runs before you try to use the API.

Usage

Send an SMS message

phone_number = "+15555555555"
message = "Hello, world!"

AfTalk.send_message(
  to: phone_number,
  message: message,
)

The send_message method requires to and message keyword arguments, and also supports all optional parameters supported by the API. For a full list, see the SMS sending API docs.

Fetch SMS messages

AfTalk.fetch_messages(
  last_received_id: 0,
)

The fetch_messages method requires a last_received_id keyword argument and ignores any other parameters you pass to it. See the SMS fetch messages API docs for more details.