Use your `X-Public-Key` and bearer secret key to authenticate with Messaging.ng. These credentials are for customers consuming Messaging.ng messaging services from their own applications.
https://messaging.ng/api/v1SMS, USSD, VAS, WhatsApp, Voicetest, liveX-Public-Key + Bearer Secret KeyGET /account
Returns your workspace profile, account readiness, and wallet balance.
Use cases: show wallet balance inside your app, confirm account readiness before sending, and sync active workspace details into an internal dashboard.
POST /messages/send
{
"recipients": ["2348012345678", "2348098765432"],
"body": "Hello from Messaging.ng",
"sender_id": "MyBrand",
"channel": "sms",
"route": "transactional",
"callback_url": "https://your-app.example.com/webhooks/messaging",
"scheduled_for": "2026-03-28T09:30:00+01:00"
}
Use this endpoint to submit outbound traffic through Messaging.ng. The response returns accepted messages, failures, references and wallet impact, while non-approved sender IDs are rejected.
API traffic is limited per credential rather than per shared IP address. A `429` response includes `error.code`, `limit_per_minute`, and `retry_after_seconds`; wait for that delay before retrying. For high-volume traffic, send multiple numbers in `recipients` so Messaging.ng can queue and process them safely in batches.
Available Routes
`transactional`
Use for OTPs, one-time alerts, account activity notices, payment updates, delivery notifications, and customer service communications.
`promotional`
Use for marketing campaigns, product announcements, seasonal offers, engagement pushes, and audience reactivation traffic.
Typical Use Cases
GET /messages
Returns the latest message log for the current workspace credential.
Use cases: build delivery dashboards, reconcile message submissions, retrieve message references, and inspect scheduling or status history.
GET /sender-ids
Returns sender ID applications, approvals and pending reviews for the active workspace.
Use cases: verify which sender IDs are approved before sending, show approval state inside an internal admin panel, and monitor pending applications from your own system.
Integration Scope
These docs are for Messaging.ng customers integrating Messaging.ng services. Your application works directly with Messaging.ng endpoints, credentials, sender ID approvals, and reporting flows.
Save a default delivery callback under Developer Access, or include callback_url in an individual send request. Messaging.ng posts a status update after an upstream delivery report is received.
{
"event": "message.delivery_status",
"message_id": 1054,
"reference": "PROVIDER-REFERENCE",
"recipient": "2348012345678",
"sender_id": "MyBrand",
"route": "transactional",
"status": "delivered",
"failure_reason": null,
"segments": 1,
"total_cost": 4.7,
"vat_rate": 7.5,
"vat_amount": 0.35,
"total_billed": 5.05,
"network": "mtn",
"wallet_refunded": false,
"occurred_at": "2026-10-16T21:00:00+01:00"
}
total_cost is the message charge before VAT. vat_amount is recorded as a separate wallet transaction, and total_billed is the combined wallet debit.
Status polling fallback
If your callback is delayed, query the message or batch reference returned by the send endpoint. Messaging.ng refreshes pending Gemini messages from the delivery network before returning the result. Authentication uses the same X-Public-Key and bearer secret.
GET /api/v1/messages/{reference}/status
curl -H "X-Public-Key: pk_live_..." \
-H "Authorization: Bearer msg_live_..." \
https://messaging.ng/api/v1/messages/MSG-ABC123/status
Messaging.ng reports delivery states as submitted, delivered, undelivered, or failed. Submitted means the message was accepted and is awaiting a final delivery report.
Each request includes X-Messaging-Event: message.delivery_status and an X-Messaging-Signature value formatted as sha256=.... Compute HMAC-SHA256 over the exact raw request body using the signing secret shown under Developer Access, then compare signatures with a timing-safe function.
$expected = 'sha256=' . hash_hmac(
'sha256',
$rawRequestBody,
$signingSecret
);
if (! hash_equals($expected, $signatureHeader)) {
http_response_code(401);
exit;
}
Return any HTTP 2xx response after accepting the event. Messaging.ng retries temporary callback failures and records the final HTTP result against the message.
Messaging.ng forwards live USSD requests to the callback URL saved in your approved service request. Every network route uses the same provider-neutral field names, so your callback remains unchanged when Messaging.ng updates the upstream route.
Callback Request
POST your configured callback URL sessionId=ATUid_12345 serviceCode=*347*307*12# phoneNumber=+2348012345678 text=1*2*3
Expected Response
CON Welcome to your service 1. Balance 2. Transfer OR END Thank you for using our service
Events URL
If you save an events URL with your USSD request, Messaging.ng forwards end-of-session and related event payloads to that endpoint as they are received.
Subcode Assignment
Messaging.ng routes each incoming USSD request to the workspace that owns the assigned subcode. If your assigned subcode is 0, Messaging.ng treats that service as the primary code and forwards the callback to your platform with the primary code value.
Customer Setup Flow