africastalking

README

Africastalking Golang SMS library

This is a Golang library for sending SMS messages using the Africa's Talking API. It provides a simple interface to send messages, check message status, and manage contacts.

Installation

To install the library, use the following command:

go get github.com/tech-kenya/africastalkingsms@latest

To get started locally

1. Clone the repository:

git clone https://github.com/tech-kenya/africastalkingsms.git

1. cd into the project directory

cd africastalkingsms/demo

1. Copy the .env.example file to .env and fill in your Africa's Talking credentials:

cp .env.example .env
cp .env.example .envrc

Ensure you have Golang 1,18+ installed on your machine and you have an API key from Africa's Talking.

• Shortcode or Sender ID: https://account.africastalking.com/apps/sandbox/sms/shortcodes/create

note that after generating a new API key, it might take upto 15 mins for it to become active

• API Key: https://account.africastalking.com/apps/sandbox/settings/key

1. Install the dependencies:

go mod tidy

1. Run the example:

direnv allow # if you are using direnv
# or
export $(cat .env | xargs) # if you are not using direnv
#then
go run .

Usage

see demo/api for a simple API example

go mod tidy #download dependencies

go run . #start the api server

POST Request

curl -X POST http://localhost:8080/send-sms \
     -H "Content-Type: application/json" \
     -d '{
           "recipient": "+254712345678",
           "message": "Hello from Gin API"
         }'

Response

{"Message":"Sent to 1/1 Total Cost: KES 0.8000 Message parts: 1","Recipients":[{"number":"+254....","cost":"KES 0.8000","status":"Success","statusCode":101,"messageId":"ATXid_ad8a62b0680a41351b1ea383b9b66fd1"}]}

Known bugs

2025/03/24 11:35:51 Failed to send SMS:failed to parse API response: invalid character 'T' looking for beginning of value

Documentation

Overview

Package africastalking provides a simple wrapper for sending SMS via Africa's Talking API.

Example usage:

import (
	"log"
	"github.com/tech-kenya/africastalkingsms"
)

func main() {
	apiKey = os.Getenv("atApiKey")
	username = os.Getenv("atUserName")
	atShortCode = os.Getenv("atShortCode")
	sandbox = os.Getenv("sandboxEnv")
	client := africastalking.NewSMSClient(apiKey, username, atShortCode, sandbox)
	if err != nil {
		log.Fatal(err)
	}
	resp, err := client.SendSMS("+254712345678", "Hello from Africa's Talking!")
	if err != nil{
		log.Fatal(err)
	}

	log.Println(resp)
}

Index

• type HTTPClient
• type SMSClient
  • func NewSMSClient(apiKey, username, atShortCode, sandbox string) (*SMSClient, error)
  • func (c *SMSClient) SendSMS(recipient, message string) (*SMSResponse, error)
• type SMSRequest
• type SMSResponse

Types

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

type SMSClient

type SMSClient struct {
	APIKey    string
	Username  string
	ShortCode string

	HTTPClient HTTPClient
	// contains filtered or unexported fields
}

SMSClient holds API credentials

func NewSMSClient

func NewSMSClient(apiKey, username, atShortCode, sandbox string) (*SMSClient, error)

NewSMSClient initializes a new Africa's Talking SMS client. ensure .env has the below variables

func (*SMSClient) SendSMS

func (c *SMSClient) SendSMS(recipient, message string) (*SMSResponse, error)

SendSMS sends an SMS message to the specified recipient.

Example:

err := client.SendSMS("+254712345678", "Hello!")
if err != nil {
	log.Fatal(err)
}

Parameters: - recipient: Phone number of the recipient in international format (e.g., +254712345678) - message: The text message content

type SMSRequest

type SMSRequest struct {
	Recipient string `json:"recipient"`
	Message   string `json:"message"`
}

Request payload struct

type SMSResponse

type SMSResponse struct {
	SMSMessageData struct {
		Message    string `json:"message"`
		Recipients []struct {
			Number     string `json:"number"`
			Cost       string `json:"cost"`
			Status     string `json:"status"`
			StatusCode int    `json:"statusCode"`
			MessageID  string `json:"messageId"`
		} `json:"recipients"`
	} `json:"SMSMessageData"`
}

Response struct for JSON parsing