Africa's Talking

send_bulk_sms

• ⚠No sandbox yet: "Sandbox: https://api.sandbox.africastalking.com/version1/messaging/bulk (coming soon)". Test with send_sms (legacy endpoint, which has a sandbox) and switch to this one in production.
• ⚠Recipients go in phoneNumbers, a list — the docs' JSON sample: "phoneNumbers": ["+254711XXXYYY", "+254711YYYZZZ"]. The legacy send_sms uses a comma separated string named to instead.
• ⚠senderId is required here ("Your registered short code or alphanumeric"); the legacy endpoint's from is optional with a default.
• ⚠Hashed numbers (Safaricom, Kenya): send maskedNumber and telco with phoneNumbers [] — "This value must be a blank list, i.e, []" — and senderId becomes optional.
• ⚠Check SMSMessageData.Recipients[].statusCode for each recipient: 100 Processed, 101 Sent, 102 Queued; the docs list 401–502 as error codes. status "does not indicate the delivery status": the delivery comes later in webhook_delivery_report.
• ⚠Help Center (Why did my messages Fail?): "Another reason that messages may fail to be sent is if they have the (%) percentage character in the text."

send_sms

• ⚠The docs now label this endpoint "Bulk (legacy)". The current one is POST /version1/messaging/bulk (send_bulk_sms, still a draft here; its page says it "also accepts json requests"), whose sandbox is "coming soon"; this endpoint has a sandbox.
• ⚠username is "sandbox" in the sandbox and your application username in production. Docs (Authentication): "For POST requests in which fields are sent as a url encoded form e.g. in sending SMS, the username should be included as one of the fields within the form."
• ⚠Send the body as a form. Docs (Request Headers): Content-Type "The requests content type, application/x-www-form-urlencoded"; Accept (optional) "Can be application/json or application/xml" — send Accept: application/json to get the JSON response described here.
• ⚠Check SMSMessageData.Recipients[].statusCode for each recipient: 100 Processed, 101 Sent, 102 Queued; the docs list 401–502 as error codes (RiskHold, InvalidSenderId…). status "does not indicate the delivery status": the delivery comes later in webhook_delivery_report.
• ⚠Nigeria (SMS Notifications page, DoNotDisturbRejection): "When attempting to send an SMS message with a promotional sender ID outside the allowed time window(8pm-8am), the API will return an HTTP 409 status code". Its example body still carries SMSMessageData, with messageId "None" and cost "0" for the rejected recipient: parse it, and do not store "None" as a message id.
• ⚠Help Center (Why did my messages Fail?): "Another reason that messages may fail to be sent is if they have the (%) percentage character in the text." Strip or replace % in message.
• ⚠Sandbox: a delivery report with failureReason DeliveryFailure "means that you may not be logged into the simulator, or the simulator is unreachable for some reason" (Help Center).
• ⚠Hashed numbers (Safaricom, Kenya) use the same endpoint with maskedNumber and telco and an empty phoneNumbers list: that variant is documented but not modelled in this spec.

webhook_bulk_opt_out

• ⚠Set the URL in the dashboard: SMS -> SMS Callback URLs -> Bulk SMS Opt Out.
• ⚠Docs: "The instructions on how to opt out are automatically appended to the first message you send to the mobile subscriber. From then onwards, any other message will be sent 'as is' to the subscriber."
• ⚠Store the opt-out per (senderId, phoneNumber) and exclude that number from later sends with that sender ID.
• ⚠The body is a form (application/x-www-form-urlencoded), not JSON. Treat it as untrusted: the docs describe no signature.

webhook_delivery_report

• ⚠Set the URL in the dashboard: SMS -> SMS Callback URLs -> Delivery Reports. There is no per-request callback parameter in send_sms.
• ⚠Match a report to its message with id = the messageId of the send_sms response. The docs mark Rejected, Success and Failed as final statuses.
• ⚠The body is a form (application/x-www-form-urlencoded), not JSON: every field arrives as a string, retryCount included.
• ⚠Sandbox: networkCode 99999 is Athena, "a custom networkCode that only applies when working in the sandbox environment".
• ⚠Treat the payload as untrusted: the docs describe no signature. Act only on ids you know (for a delivery report, a messageId returned by send_sms) and keep the callback URL unguessable.

webhook_incoming_sms

• ⚠Set the URL in the dashboard: SMS -> SMS Callback URLs -> Incoming Messages. Only messages sent to your registered shortcodes arrive here.
• ⚠The body is a form (application/x-www-form-urlencoded), not JSON.
• ⚠A reply is a separate send_sms (suggestion: to = from). Replies to premium on-demand requests need linkId and premium SMS, which this registry does not cover.
• ⚠Treat the payload as untrusted: the docs describe no signature. Keep the callback URL unguessable and validate text before acting on it.

webhook_ussd_end_of_session

• ⚠Separate URL: "you need to setup another callback URL for event notification on your USSD code listed in USSD -> Service Codes on the dashboard." It is not the session callback.
• ⚠Join it to the session with sessionId. status Failed means your callback answered with an error: lastAppResponse holds "the exact response from the callback".
• ⚠The body is a form (application/x-www-form-urlencoded): hopsCount and durationInMillis arrive as strings.
• ⚠Sandbox: networkCode 99999 is Athena, which "only applies when working in the sandbox environment".

webhook_ussd_session

• ⚠Prerequisites: "Register a service code with us" and "Register a callback URL that we will call whenever we get a request from a user coming into our system."
• ⚠Answer within 10 seconds: "the expected response time from your application is at most 10 seconds."
• ⚠Route on text, not on a counter: it is "" on the first request, then every answer of the session joined with * ("1", then "1*2"…). Split on * to get the path through your menu; sessionId identifies the session across requests.
• ⚠Every response must begin with CON or END. Anything else, or an HTTP 40X, terminates the session.
• ⚠"Your USSD Menu should not contain special characters as the telcos are unable to render such content".
• ⚠at-ussd-hop-metadata is shown in the dashboard: "take note not to share sensitive details in this header". At most 99 characters, no |.
• ⚠To learn how a session ended (user hung up, error, success), add the end-of-session callback: webhook_ussd_end_of_session.