at-ussd-gofiber

README

at-ussd-gofiber

go get github.com/astianmuchui/at-ussd-gofiber

A lightweight Go SDK for building Africa's Talking USSD (Unstructured Supplementary Service Data) applications with the Fiber web framework (v3).

It provides helpers to:

• Parse incoming USSD request payloads from a Fiber context
• Parse end-of-session notification callbacks from a Fiber context
• Build correctly formatted CON/END USSD responses
• Reference network and status codes as typed constants

Installation

go get github.com/astianmuchui/at-ussd-gofiber

Import the v1 package:

import ussd "github.com/astianmuchui/at-ussd-gofiber/v1"

Usage

Handling a USSD request

app.Post("/ussd", func(c fiber.Ctx) error {
    payload := ussd.ToUSSDPayload(c)

    response := &ussd.USSDResponse{ResponseText: "Welcome to My Service"}

    if payload.Text == "" {
        return c.SendString(response.CON())
    }

    return c.SendString(response.END())
})

• ToUSSDPayload(c) reads sessionId, phoneNumber, networkCode, serviceCode, and text from the incoming form values and returns an *ApiPayload.
• USSDResponse.CON() prefixes the response with CON (continue the session) unless it is already prefixed.
• USSDResponse.END() prefixes the response with END (terminate the session) unless it is already prefixed.
• USSDResponse.Validate(sessionType) returns an error if the response text already contains the given session type prefix.

Handling an end-of-session notification

The USSD API sends a notification at the end of a USSD session. To receive these notifications, set up a callback URL for event notifications in USSD > Service Codes on your dashboard. Notifications are sent as POST requests with Content-Type: application/x-www-form-urlencoded.

app.Post("/ussd/notification", func(c fiber.Ctx) error {
    notification := ussd.ToUSSDNotification(c)

    json, err := notification.ToJSON()
    if err != nil {
        return err
    }

    log.Println(json)
    return c.SendStatus(fiber.StatusOK)
})

ToUSSDNotification(c) parses the callback form values into a *USSDNotification.

API Reference

Types

Type	Description
ApiPayload	Parsed USSD request payload (SessionId, PhoneNumber, Networkcode, ServiceCode, Text)
USSDResponse	Wraps a ResponseText string and provides CON(), END(), and Validate() helpers
USSDNotification	Parsed end-of-session notification payload

Functions

Function	Description
ToUSSDPayload(c fiber.Ctx) *ApiPayload	Builds an ApiPayload from the Fiber request context
ToUSSDNotification(c fiber.Ctx) *USSDNotification	Builds a USSDNotification from the Fiber request context
(*ApiPayload) ToJSON() (string, error)	Serializes the payload to a JSON string
(*USSDNotification) ToJSON() (string, error)	Serializes the notification to a JSON string
(*USSDResponse) CON() string	Returns the response text prefixed with CON
(*USSDResponse) END() string	Returns the response text prefixed with END
(*USSDResponse) Validate(sessionType string) error	Errors if the response already contains the given session type

Session type constants

Constant	Value
SessionCON	"CON"
SessionEND	"END"

USSD status constants

Constant	Value
USSD_STATUS_INCOMPLETE	"Incomplete"
USSD_STATUS_SUCCESS	"Success"
USSD_STATUS_FAILED	"Failed"

End of Interaction Notification Fields

Field	Type	Description
date	String	UTC timestamp when notification was sent. Format: yyyy-MM-dd HH:mm:ss
sessionId	String	Unique session identifier (same as requests during session)
serviceCode	String	USSD code assigned to your application
networkCode	String	Telco identifier (see values below)
phoneNumber	String	Mobile subscriber number
status	String	Session status: Incomplete, Success, or Failed
cost	String	USSD session cost
durationInMillis	String	Session duration in milliseconds
hopsCount	Integer	Number of steps user navigated
input	String	User inputs concatenated with *
lastAppResponse	String	Last callback response before session ended
errorMessage	String	(Optional) Error message for failed sessions

Network Codes

The package exposes each of these as a NETWORK_* constant (e.g. ussd.NETWORK_MTN_GHANA).

Code	Network	Constant
62001	MTN Ghana	NETWORK_MTN_GHANA
62002	Vodafone Ghana	NETWORK_VODAFONE_GHANA
62006	AirtelTigo Ghana	NETWORK_AIRTEL_TIGO_GHANA
62120	Airtel Nigeria	NETWORK_AIRTEL_NIGERIA
62130	MTN Nigeria	NETWORK_MTN_NIGERIA
62150	Glo Nigeria	NETWORK_GLO_NIGERIA
62160	Etisalat Nigeria	NETWORK_ETISALAT_NIGERIA
63510	MTN Rwanda	NETWORK_MTN_RWANDA
63513	Tigo Rwanda	NETWORK_TIGO_RWANDA
63514	Airtel Rwanda	NETWORK_AIRTEL_RWANDA
63601	EthioTelecom Ethiopia	NETWORK_ETHIOTELECOM_ETHIOPIA
63902	Safaricom Kenya	NETWORK_SAFARICOM_KENYA
63903	Airtel Kenya	NETWORK_AIRTEL_KENYA
63907	Orange Kenya	NETWORK_ORANGE_KENYA
63999	Equitel Kenya	NETWORK_EQUITEL_KENYA
64002	Tigo Tanzania	NETWORK_TIGO_TANZANIA
64004	Vodacom Tanzania	NETWORK_VODACOM_TANZANIA
64005	Airtel Tanzania	NETWORK_AIRTEL_TANZANIA
64101	Airtel Uganda	NETWORK_AIRTEL_UGANDA
64110	MTN Uganda	NETWORK_MTN_UGANDA
64114	Africell Uganda	NETWORK_AFRICELL_UGANDA
64501	Airtel Zambia	NETWORK_AIRTEL_ZAMBIA
64502	MTN Zambia	NETWORK_MTN_ZAMBIA
65001	TNM Malawi	NETWORK_TNM_MALAWI
65010	Airtel Malawi	NETWORK_AIRTEL_MALAWI
65501	Vodacom South Africa	NETWORK_VODACOM_SOUTH_AFRICA
65502	Telkom South Africa	NETWORK_TELKOM_SOUTH_AFRICA
65507	CellC South Africa	NETWORK_CELLC_SOUTH_AFRICA
65510	MTN South Africa	NETWORK_MTN_SOUTH_AFRICA
99999	Athena (Sandbox only)	NETWORK_ATHENA