Delivery reports

We have delivery reports available for all messages being sent to phone numbers in most African countries. We also display the delivery status in your bulk sms outbox or in your premium outbox.

To receive delivery reports directly to your application, you can register a callback url in your Dashboard. We then update the delivery status information using POST requests made to the callback URL you set.

Here is how it works:

  • When you send us a message, we usually send you back a messageId field which uniquely identifies every message that was sent out.
  • When we subsequently receive a delivery report for that message, we can call the URL that you specify above with the id, status, phoneNumber, networkCode and failureReason values for that message.
  • failureReason is only provided where status is Rejected or Failed. Please note: not all telcos support this feature.

The possible values for status are:

Status Description
Sent The message has successfully been sent by our network.
Submitted The message has successfully been submitted to the MSP (Mobile Service Provider).
Buffered The message has been queued by the MSP.
Rejected The message has been rejected by the MSP. This is a final status.
Success The message has successfully been delivered to the receiver's handset. This is a final status.
Failed The message could not be delivered to the receiver's handset. This is a final status.

The possible values for failureReason are:

failureReason Description
InsufficientCredit This occurs when the subscriber don't have enough airtime for a premium subscription service/message
InvalidLinkId This occurs when a message is sent with an invalid linkId for an onDemand service
UserIsInactive This occurs when the subscriber is inactive or the account deactivated by the MSP (Mobile Service Provider).
UserInBlackList This would occur if the user has been blacklisted not to receive messages from a paricular service (shortcode or keyword)
UserAccountSuspended This would occur when the mobile subscriber has been suspended by the MSP.
NotNetworkSubcriber This occurs when the message is passed to an MSP where the subscriber doesn't belong.
UserNotSubscribedToProduct This is for a subscription product which the subscriber has not subscribed to.
UserDoesNotExist This occurs when the message is sent to a non-existent mobile number.
DeliveryFailure This occurs when message delivery fails for any reason not listed above or where the MSP didn't provide a delivery failure reason.

The networkCode is a unique identifer for the telco that handled the message. Possible values for the networkCode are:

networkCode Telco
62120 Airtel Nigeria
62130 MTN Nigeria
62150 Glo Nigeria
62160 Etisalat Nigeria
63510 MTN Rwanda
63513 Tigo Rwanda
63514 Airtel Rwanda
63902 Safaricom
63903 Airtel Kenya
63907 Orange Kenya
63999 Equitel Kenya
64002 Tigo Tanzania
64003 Zantel Tanzania
64004 Vodacom Tanzania
64005 Airtel Tanzania
64007 TTCL Tanzania
64009 Halotel Tanzania
64101 Airtel Uganda
64110 MTN Uganda
64111 UTL Uganda
64114 Africell Uganda
65001 TNM Malawi
65010 Airtel Malawi
99999 Athena
Please note: This is a custom networkCode that only applies when working in the sandbox environment.
PHP sample code
<?php
 $status      = $_POST['status']; //This contains the status as described above
 $phoneNumber = $_POST['phoneNumber']; //This is the phoneNumber that the message was sent to
 $networkCode = $_POST['networkCode']; //This is the networkCode of the telco that handled the message
 $messageId   = $_POST['id']; //This is the messageId received when the message was sent
 
 //This parameter is passed when status is Rejected or Failed.
 if($status == "Failed" || $status == "Rejected")
   $failureReason = $_POST['failureReason']; 

 //Update your records
 ?>