Build interactive USSD menus driven by HTTP callbacks. Africa's Talking POSTs session state (sessionId, serviceCode, phoneNumber, text) to your callback URL and your response begins with CON to continue or END to terminate the session.
openapi: 3.0.1
info:
title: Africa's Talking API
description: >-
Unified REST API for Africa's Talking communications products: SMS (single,
bulk, premium, subscriptions), USSD callbacks, Voice (call, transfer, media
upload, queue status), Airtime, Mobile Data, and Payments (mobile C2B
checkout, B2C, B2B). Requests authenticate with an `apiKey` header and a
`username` parameter. Hosts differ per product: messaging, airtime, and
subscriptions live under api.africastalking.com/version1; voice under
voice.africastalking.com; mobile data under bundles.africastalking.com; and
payments under payments.africastalking.com. Sandbox equivalents insert
`.sandbox.` into each host.
termsOfService: https://africastalking.com/terms
contact:
name: Africa's Talking Support
url: https://help.africastalking.com
version: 'version1'
servers:
- url: https://api.africastalking.com/version1
description: Messaging, Airtime and Subscription production host
- url: https://api.sandbox.africastalking.com/version1
description: Messaging, Airtime and Subscription sandbox host
- url: https://voice.africastalking.com
description: Voice production host
- url: https://bundles.africastalking.com
description: Mobile Data production host
- url: https://payments.africastalking.com
description: Payments production host
security:
- apiKey: []
tags:
- name: SMS
description: Send single and bulk SMS and fetch inbox messages.
- name: Premium SMS
description: Premium SMS subscriptions and checkout tokens.
- name: Voice
description: Outbound calls, transfers, queue status, and media upload.
- name: Airtime
description: Distribute mobile airtime to recipients.
- name: Mobile Data
description: Disburse mobile data bundles to recipients.
- name: Payments
description: Mobile C2B checkout, B2C, and B2B mobile money transfers.
paths:
/messaging:
post:
operationId: sendMessage
tags:
- SMS
summary: Send SMS
description: >-
Send a single or bulk SMS to one or more recipients. Set `bulkSMSMode`
to 1 for bulk delivery. Provide a registered `from` short code or sender
ID where available.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SendMessageRequest'
responses:
'201':
description: Message accepted for delivery.
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageResponse'
'400':
description: Bad request.
'401':
description: Unauthorized - missing or invalid apiKey.
get:
operationId: fetchMessages
tags:
- SMS
summary: Fetch inbox messages
description: Retrieve messages sent to your registered short codes or sender IDs.
parameters:
- name: username
in: query
required: true
schema:
type: string
- name: lastReceivedId
in: query
required: false
description: ID of the message last processed; 0 fetches from the start.
schema:
type: string
default: '0'
responses:
'200':
description: Inbox messages.
content:
application/json:
schema:
$ref: '#/components/schemas/FetchMessagesResponse'
/checkout/token/create:
post:
operationId: createCheckoutToken
tags:
- Premium SMS
summary: Create checkout token
description: >-
Generate a checkout token for a phone number, required before creating a
premium SMS subscription.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- phoneNumber
properties:
phoneNumber:
type: string
description: Subscriber phone number in international format.
example: '+254711XXXYYY'
responses:
'201':
description: Checkout token created.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutTokenResponse'
/subscription/create:
post:
operationId: createSubscription
tags:
- Premium SMS
summary: Create premium SMS subscription
description: Subscribe a phone number to a premium SMS product using a checkout token.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SubscriptionRequest'
responses:
'201':
description: Subscription created.
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionResponse'
/subscription/delete:
post:
operationId: deleteSubscription
tags:
- Premium SMS
summary: Delete premium SMS subscription
description: Unsubscribe a phone number from a premium SMS product.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- username
- shortCode
- keyword
- phoneNumber
properties:
username:
type: string
shortCode:
type: string
keyword:
type: string
phoneNumber:
type: string
responses:
'201':
description: Subscription deleted.
/subscription:
get:
operationId: fetchSubscriptions
tags:
- Premium SMS
summary: Fetch premium SMS subscriptions
parameters:
- name: username
in: query
required: true
schema:
type: string
- name: shortCode
in: query
required: true
schema:
type: string
- name: keyword
in: query
required: true
schema:
type: string
- name: lastReceivedId
in: query
required: false
schema:
type: string
default: '0'
responses:
'200':
description: List of subscriptions.
/airtime/send:
post:
operationId: sendAirtime
tags:
- Airtime
summary: Send airtime
description: Distribute airtime to one or more recipients. `recipients` is a JSON-encoded array.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SendAirtimeRequest'
responses:
'201':
description: Airtime request accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/SendAirtimeResponse'
/call:
post:
operationId: makeCall
tags:
- Voice
summary: Make outbound call
description: >-
Initiate an outbound call from a registered Africa's Talking number to
one or more destination numbers. Served from voice.africastalking.com.
servers:
- url: https://voice.africastalking.com
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/MakeCallRequest'
responses:
'200':
description: Call entries queued.
content:
application/json:
schema:
$ref: '#/components/schemas/MakeCallResponse'
/queueStatus:
post:
operationId: queueStatus
tags:
- Voice
summary: Get queued call status
description: Return the number of calls currently queued on registered phone numbers.
servers:
- url: https://voice.africastalking.com
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- username
- phoneNumbers
properties:
username:
type: string
phoneNumbers:
type: string
description: Comma-separated list of registered phone numbers.
responses:
'200':
description: Queue status entries.
/mediaUpload:
post:
operationId: uploadMedia
tags:
- Voice
summary: Upload voice media file
description: Upload a media file to be played on demand by Play, musicOnHold, or ringBackTone.
servers:
- url: https://voice.africastalking.com
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- username
- url
- phoneNumber
properties:
username:
type: string
url:
type: string
description: HTTP(S) URL of the media file to upload.
phoneNumber:
type: string
description: Africa's Talking phone number mapped to your account.
responses:
'200':
description: Media upload accepted.
/mobile/data/request:
post:
operationId: sendMobileData
tags:
- Mobile Data
summary: Send mobile data bundles
description: Disburse mobile data bundles to a list of recipients. Served from bundles.africastalking.com.
servers:
- url: https://bundles.africastalking.com
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MobileDataRequest'
responses:
'201':
description: Mobile data request accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/MobileDataResponse'
/mobile/checkout/request:
post:
operationId: mobileCheckout
tags:
- Payments
summary: Mobile C2B checkout
description: >-
Initiate a mobile money checkout (customer-to-business) prompting the
subscriber to authorize payment. Served from payments.africastalking.com.
servers:
- url: https://payments.africastalking.com
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MobileCheckoutRequest'
responses:
'201':
description: Checkout initiated.
content:
application/json:
schema:
$ref: '#/components/schemas/MobileCheckoutResponse'
/mobile/b2c/request:
post:
operationId: mobileB2C
tags:
- Payments
summary: Mobile B2C payment
description: Send money from your payment wallet to one or more mobile subscribers.
servers:
- url: https://payments.africastalking.com
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MobileB2CRequest'
responses:
'201':
description: B2C request accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/MobileB2CResponse'
/mobile/b2b/request:
post:
operationId: mobileB2B
tags:
- Payments
summary: Mobile B2B payment
description: Send money from your business to another business over mobile money rails.
servers:
- url: https://payments.africastalking.com
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MobileB2BRequest'
responses:
'201':
description: B2B request accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/MobileB2BResponse'
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: apiKey
description: Africa's Talking API key generated from your account dashboard.
schemas:
SendMessageRequest:
type: object
required:
- username
- to
- message
properties:
username:
type: string
description: Your Africa's Talking application username.
to:
type: string
description: Comma-separated recipient phone numbers in international format.
example: '+254711XXXYYY,+254733YYYZZZ'
message:
type: string
description: The message body to send.
from:
type: string
description: Registered short code or alphanumeric sender ID.
bulkSMSMode:
type: integer
description: Set to 1 to enable bulk SMS delivery.
enum: [0, 1]
default: 1
enqueue:
type: integer
description: Set to 1 to enqueue large outbound batches.
enum: [0, 1]
keyword:
type: string
description: Premium SMS keyword (premium SMS only).
linkId:
type: string
description: Link identifier from an onDemand premium SMS subscription.
retryDurationInHours:
type: integer
description: Hours to retry premium SMS delivery before discarding.
SendMessageResponse:
type: object
properties:
SMSMessageData:
type: object
properties:
Message:
type: string
example: 'Sent to 1/1 Total Cost: KES 0.8000'
Recipients:
type: array
items:
$ref: '#/components/schemas/Recipient'
Recipient:
type: object
properties:
statusCode:
type: integer
example: 101
number:
type: string
example: '+254711XXXYYY'
status:
type: string
example: Success
cost:
type: string
example: KES 0.8000
messageId:
type: string
example: ATPid_SampleTxnId123
FetchMessagesResponse:
type: object
properties:
SMSMessageData:
type: object
properties:
Messages:
type: array
items:
type: object
properties:
linkId:
type: string
text:
type: string
to:
type: string
id:
type: integer
date:
type: string
from:
type: string
CheckoutTokenResponse:
type: object
properties:
description:
type: string
example: Success
token:
type: string
example: CkTkn_SampleCkTknId123
SubscriptionRequest:
type: object
required:
- username
- shortCode
- keyword
- phoneNumber
- checkoutToken
properties:
username:
type: string
shortCode:
type: string
description: Premium SMS short code mapped to your account.
keyword:
type: string
description: Premium SMS keyword mapped to your short code.
phoneNumber:
type: string
checkoutToken:
type: string
description: Token returned by /checkout/token/create.
SubscriptionResponse:
type: object
properties:
status:
type: string
example: Success
description:
type: string
example: Waiting for user input
SendAirtimeRequest:
type: object
required:
- username
- recipients
properties:
username:
type: string
recipients:
type: string
description: >-
JSON-encoded array of recipient objects, each with phoneNumber,
currencyCode, amount, and optional maxNumRetry.
example: '[{"phoneNumber":"+254711XXXYYY","currencyCode":"KES","amount":"100"}]'
maxNumRetry:
type: integer
description: Maximum delivery retries in hours on failure.
SendAirtimeResponse:
type: object
properties:
errorMessage:
type: string
example: None
numSent:
type: integer
example: 1
totalAmount:
type: string
example: KES 100.0000
totalDiscount:
type: string
example: KES 3.0000
responses:
type: array
items:
type: object
properties:
phoneNumber:
type: string
amount:
type: string
status:
type: string
requestId:
type: string
discount:
type: string
errorMessage:
type: string
MakeCallRequest:
type: object
required:
- username
- from
- to
properties:
username:
type: string
from:
type: string
description: Registered Africa's Talking phone number to dial out with.
example: '+254711XXXYYY'
to:
type: string
description: Comma-separated destination phone numbers.
example: '+254733YYYZZZ'
clientRequestId:
type: string
description: Variable sent to your Events Callback URL for this call.
MakeCallResponse:
type: object
properties:
entries:
type: array
items:
type: object
properties:
phoneNumber:
type: string
status:
type: string
example: Queued
sessionId:
type: string
errorMessage:
type: string
example: None
MobileDataRequest:
type: object
required:
- username
- productName
- recipients
properties:
username:
type: string
productName:
type: string
description: Registered payment product name.
recipients:
type: array
items:
type: object
required:
- phoneNumber
- quantity
- unit
- validity
properties:
phoneNumber:
type: string
example: '+254711XXXYYY'
quantity:
type: number
example: 50
unit:
type: string
enum: [MB, GB]
validity:
type: string
enum: [Day, Week, Month]
metadata:
type: object
additionalProperties:
type: string
MobileDataResponse:
type: object
properties:
entries:
type: array
items:
type: object
properties:
phoneNumber:
type: string
provider:
type: string
status:
type: string
example: Queued
transactionId:
type: string
value:
type: string
MobileCheckoutRequest:
type: object
required:
- username
- productName
- phoneNumber
- currencyCode
- amount
properties:
username:
type: string
productName:
type: string
phoneNumber:
type: string
example: '+254711XXXYYY'
currencyCode:
type: string
description: 3-letter ISO currency code.
example: KES
amount:
type: number
example: 100.5
providerChannel:
type: string
metadata:
type: object
additionalProperties:
type: string
MobileCheckoutResponse:
type: object
properties:
status:
type: string
example: PendingConfirmation
description:
type: string
example: Waiting for user input
transactionId:
type: string
example: ATPid_SampleTxnId123
MobileB2CRequest:
type: object
required:
- username
- productName
- recipients
properties:
username:
type: string
productName:
type: string
recipients:
type: array
items:
type: object
required:
- phoneNumber
- currencyCode
- amount
properties:
phoneNumber:
type: string
currencyCode:
type: string
example: KES
amount:
type: number
reason:
type: string
description: Purpose of payment, e.g. SalaryPayment, BusinessPayment.
metadata:
type: object
additionalProperties:
type: string
MobileB2CResponse:
type: object
properties:
numQueued:
type: integer
example: 1
totalValue:
type: string
example: KES 100.0000
totalTransactionFee:
type: string
entries:
type: array
items:
type: object
properties:
phoneNumber:
type: string
status:
type: string
example: Queued
provider:
type: string
providerChannel:
type: string
value:
type: string
transactionId:
type: string
transactionFee:
type: string
MobileB2BRequest:
type: object
required:
- username
- productName
- provider
- transferType
- currencyCode
- amount
- destinationChannel
- destinationAccount
properties:
username:
type: string
productName:
type: string
provider:
type: string
description: Mobile money provider, e.g. Mpesa, Athena.
transferType:
type: string
description: e.g. BusinessBuyGoods, BusinessPayBill, DisburseFundsToBusiness, BusinessToBusinessTransfer.
currencyCode:
type: string
example: KES
amount:
type: number
destinationChannel:
type: string
description: Paybill or till channel of the receiving business.
destinationAccount:
type: string
description: Account name of the receiving business.
metadata:
type: object
additionalProperties:
type: string
MobileB2BResponse:
type: object
properties:
status:
type: string
example: Queued
transactionId:
type: string
transactionFee:
type: string
providerChannel:
type: string