There are several stages to message sending and the message might fail at any of these.
Stage 1: Running your Send SMS code
This is after you have set up your AT account, acquired a senderId or shortcode and integrated with our API. Once you've run your script. You get a response from our API. e.g:
{'SMSMessageData': {'Message': 'Sent to 1/1 Total Cost: KES 0.8000', 'Recipients': [{'statusCode': 101, 'number': '+254705336634', 'cost': 'KES 0.8000', 'status': 'Success', 'messageId': 'ATXid_03cb5ecf11ce748794c0f9a85c276259'}]}}This is the firsts stage a message might fail. Below are some possible errors you might get and what they mean:
rejected by gateway - this happens when you use a senderId/shortcode that hasn't been mapped to your account.
supplied authentication - here's an article about this
risk hold error -here's an article about this error
Invalid Phone Number- ensure the number has all the necessary digits.
Insufficient balance - here's an article on how to top up your account :)
Stage 2: The sent status
This is after your code has run successfully and you got the initial 'Success status from the API. And the status on your Dashboard(link) is 'sent' This means that your message has been delivered by Africa's Talking to the Telco and we are waiting on the Telco for the final status.
Stage 3: Delivery Report
This is the final stage where we get a response from the Telco on whether the message got to the customers handset.
Below are the final delivery reports: you might receive:
Failed: The message did not reach the recipient’s handset.
Rejected : The message has been rejected by the Telco.
Submitted: The message has been sent to the Mobile Service Provider/Telco
Buffered : The message has been queued by the Telco
Success : The message has successfully reached the recipient’s handset
If the status is Failed/ Rejected it might be for one of the below reasons:
DeliveryFailure: This occurs when message delivery fails for any reason not listed above or where the MSP didn't provide a delivery failure reason. On the sandbox this means that you may not be logged into the simulator, or the simulator is unreachable for some reason.
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 particular 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.
Another reason that messages may fail to be sent is if they have the (%) percentage character in the text.
If none of the above failure reasons match your status, or if you were sending a message to another Telco, kindly send a sample number and time stamp of this to support@africastalking.com and we will look into it.