Programmatically distribute mobile airtime to one or many recipients across supported African carriers, with per-recipient currency, amount, and retry control.
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