Platform Documentation
The complete developer guide to deploying Akmond Notify for messaging workflows and custom software architectures.
1. Platform Integration Guide
Akmond Notify provides two robust integration pathways. Choose the one that matches your technical environment:
Option A: Zero-Code Secure Syncing
Best for business owners without in-house developers. Our platform securely syncs with your database to detect failed transactions and manual funding requests instantlyβwithout you writing a single line of code.
Step 1: Link Your Platform
Connect via Direct Sync (requires IP whitelist) OR use our Secure HTTP Bridge file if your host blocks remote access.
Step 2: Map Your Alerts
- Inside your Dashboard, navigate to Remote DB Mapping.
- Select your connection type and input your secure credentials.
- Scroll to Map Transaction Table and select a quick-preset or map your columns manually.
- Click Activate Engine Rules. Your automation is now live!
Option B: Instant API Webhooks
Built for developers. Trigger alerts exactly when transactions fail or succeed directly from within your code execution.
Step 1: Obtain Secret Key
Generate your akm_live_... API Bearer token from the Developer API Hub.
Step 2: Install PHP Helper
Add this drop-in function to your script's core logic to trigger alerts in 0.1s:
function send_akmond_alert($secret_key, $message, $phone = '') {
$ch = curl_init('https://notify.akmondpay.com/api/v1/send.php');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 3);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'recipient' => $phone,
'message' => $message
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $secret_key,
'Content-Type: application/json'
]);
$res = curl_exec($ch); curl_close($ch);
return $res;
}
2. WooCommerce Plugin Guide
Deploy automated WhatsApp order receipts and shipping updates to your WordPress store in minutes.
- Log into your Akmond Dashboard and navigate to the Developer API Hub β‘.
- Click Generate API Key and securely copy your
akm_live_...secret. - Click the Download Plugin (.zip) button on the hub page.
- In your WordPress Admin Panel, go to Plugins → Add New → Upload Plugin and select the downloaded file.
- Activate the plugin, then click on Akmond Notify in your WordPress sidebar settings.
- Paste your Secret Key and save. Your store is now fully automated!
3. Universal REST API & OTP Engine
Trigger instant messaging workflows and Multi-Channel OTP verifications from any custom software architecture (Node.js, Python, Ruby, PHP).
3.1 Send Transactional Message
Dispatch standard text notifications, receipts, or system alerts to direct numbers or WhatsApp groups.
Required Headers
- Content-Type: application/json
- Authorization: Bearer YOUR_AKMOND_LIVE_SECRET
JSON Payload Parameters
| Parameter | Type | Description |
|---|---|---|
| message | String *Required | The exact text you want to send. Supports WhatsApp markdown (*bold*, _italic_). |
| recipient | String Optional | Target phone number (e.g., "2348030000000"). If empty, falls back to your Admin Group. |
curl -X POST "https://notify.akmondpay.com/api/v1/send.php" \
-H "Authorization: Bearer akm_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipient": "2348012345678",
"message": "π *Hello from my App!*\n\nYour order has been shipped."
}'
const axios = require('axios');
async function sendAlert(customerPhone) {
const payload = {
recipient: customerPhone,
message: `π *Hello from my App!*\n\nYour order has been shipped.`
};
const res = await axios.post('https://notify.akmondpay.com/api/v1/send.php', payload, {
headers: { 'Authorization': 'Bearer akm_live_YOUR_KEY' }
});
console.log(res.data);
}
API Response Reference
{
"status": "success",
"message": "Message dispatched successfully.",
"data": {
"message_id": "akm_msg_a1b2c3d4e5f6",
"channel": "whatsapp",
"recipient": "2348012345678",
"credits_used": 1,
"credits_remaining": 247
}
}
| HTTP Code | status field | Meaning & Fix | Example Response |
|---|---|---|---|
| 200 | success | Message dispatched. Deduct credits_used from your local balance counter. | "status":"success" |
| 400 | error | Bad request β missing or invalid field. Check that message is not empty and recipient is a valid international number. |
"message":"Missing required field: message" |
| 401 | error | Unauthorized β API key missing, malformed, or revoked. Ensure your Authorization: Bearer akm_live_... header is present and the key is active. |
"message":"Invalid or expired API key" |
| 402 | error | Insufficient credits β top up your notification wallet on the Billing page to continue. | "message":"Insufficient credits" |
| 403 | error | Forbidden β your account is suspended or the feature is disabled. Contact support. | "message":"Account suspended" |
| 429 | error | Rate limited β too many requests per minute. Implement exponential back-off. Retry after the value in the Retry-After header (seconds). |
"message":"Too many requests" |
| 500 | error | Internal server error β retry after 30 seconds. If persistent, open a support ticket with the request_id from the response. |
"message":"Internal server error" |
3.2 OTP Engine: Initiate Verification
Dispatch a 6-digit verification code. The engine intelligently handles code generation, expiration (10 minutes), and routing based on the selected method. You are not billed for unverified OTPs.
JSON Payload Parameters
| Parameter | Type | Description |
|---|---|---|
| phone | String *Required | The target phone number to verify (e.g., "2348030000000"). |
| method | String Optional | Channel to use: whatsapp, sms, or voice. Defaults to whatsapp. |
curl -X POST "https://notify.akmondpay.com/api/v1/otp/initiate.php" \
-H "Authorization: Bearer akm_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "2348012345678",
"method": "whatsapp"
}'
OTP Initiation β Response Reference
{
"status": "success",
"message": "OTP dispatched successfully.",
"data": {
"session_id": "otp_9f3a21bc",
"channel": "whatsapp",
"expires_in": 600,
"phone": "2348012345678"
}
}
| HTTP Code | status | Meaning & Fix |
|---|---|---|
| 200 | success | OTP sent. Store the session_id β pass it to your verify call to avoid phone number collisions. |
| 400 | error | Invalid phone number format. Must be in international format without + (e.g. 2348012345678). |
| 429 | error | OTP rate limit β max 3 OTP requests per phone per 10 minutes. Show the user a countdown timer before allowing resend. |
| 402 | error | Insufficient credits. OTPs are only billed on successful verification, not initiation β but your balance must be positive. |
3.3 OTP Engine: Verify Code
Validate the 6-digit PIN entered by the user. If verified successfully, the appropriate credit cost will be deducted from your wallet to finalize the authentication.
JSON Payload Parameters
| Parameter | Type | Description |
|---|---|---|
| phone | String *Required | The exact phone number that initiated the request. |
| code | String *Required | The 6-digit PIN provided by the user. |
curl -X POST "https://notify.akmondpay.com/api/v1/otp/verify.php" \
-H "Authorization: Bearer akm_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "2348012345678",
"code": "123456"
}'
OTP Verification β Response Reference
{
"status": "success",
"message": "Phone number verified successfully.",
"data": {
"phone": "2348012345678",
"verified": true,
"method": "whatsapp",
"credits_used": 2,
"credits_remaining": 245
}
}
{
"status": "error",
"message": "Invalid OTP code.",
"data": {
"verified": false,
"attempts_remaining": 2
}
}
| HTTP Code | status | Meaning & Fix |
|---|---|---|
| 200 + verified: true | success | PIN correct. Mark the user as verified in your system. Credits deducted now. |
| 200 + verified: false | error | Wrong PIN. Show attempts_remaining to the user. No credits deducted. |
| 400 | error | Missing phone or code field, or code is not 6 digits. |
| 410 | error | OTP expired (10-minute window passed) or already used. Prompt user to request a new code β call initiate again. |
| 423 | error | Locked β too many wrong attempts (max 5). Force the user to request a new OTP after a cooldown period. |
3.4 Recommended Error Handling Pattern
Copy this pattern into any language β it covers every possible API response state cleanly.
function akmondSend(string $phone, string $message): array {
$ch = curl_init('https://notify.akmondpay.com/api/v1/send.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
CURLOPT_POSTFIELDS => json_encode(['recipient' => $phone, 'message' => $message]),
CURLOPT_HTTPHEADER => ['Authorization: Bearer akm_live_YOUR_KEY', 'Content-Type: application/json'],
]);
$raw = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$res = json_decode($raw, true) ?? [];
switch ($httpCode) {
case 200: return ['ok' => true, 'data' => $res['data']];
case 400: throw new \InvalidArgumentException($res['message'] ?? 'Bad request');
case 401: throw new \RuntimeException('Invalid API key β check Developer Hub');
case 402: throw new \RuntimeException('Insufficient credits β top up billing wallet');
case 403: throw new \RuntimeException('Account suspended β contact support');
case 429:
$retryAfter = $res['retry_after'] ?? 60;
throw new \RuntimeException("Rate limited. Retry in {$retryAfter}s");
default: throw new \RuntimeException("Akmond API error {$httpCode}: " . ($res['message'] ?? 'Unknown'));
}
}
const AKMOND_KEY = 'akm_live_YOUR_KEY';
async function akmondSend(phone, message) {
const res = await fetch('https://notify.akmondpay.com/api/v1/send.php', {
method: 'POST',
headers: { 'Authorization': `Bearer ${AKMOND_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ recipient: phone, message }),
signal: AbortSignal.timeout(5000),
});
const data = await res.json();
if (res.ok) return data.data; // 200 β success
if (res.status === 400) throw new Error(`Bad request: ${data.message}`);
if (res.status === 401) throw new Error('Invalid API key');
if (res.status === 402) throw new Error('Insufficient credits β top up billing wallet');
if (res.status === 429) throw new Error(`Rate limited. Retry in ${data.retry_after ?? 60}s`);
throw new Error(`Akmond API error ${res.status}: ${data.message}`);
}
// Usage
akmondSend('2348012345678', 'β
Your order has been shipped!')
.then(data => console.log('Sent! Credits used:', data.credits_used))
.catch(err => console.error('Failed:', err.message));
import requests
AKMOND_KEY = 'akm_live_YOUR_KEY'
AKMOND_URL = 'https://notify.akmondpay.com/api/v1/send.php'
def akmond_send(phone: str, message: str) -> dict:
resp = requests.post(
AKMOND_URL,
json = {'recipient': phone, 'message': message},
headers = {'Authorization': f'Bearer {AKMOND_KEY}'},
timeout = 5
)
data = resp.json()
if resp.status_code == 200: return data['data']
if resp.status_code == 400: raise ValueError(f"Bad request: {data.get('message')}")
if resp.status_code == 401: raise PermissionError('Invalid API key')
if resp.status_code == 402: raise RuntimeError('Insufficient credits')
if resp.status_code == 429:
retry = data.get('retry_after', 60)
raise RuntimeError(f'Rate limited. Retry in {retry}s')
raise RuntimeError(f"Akmond API error {resp.status_code}: {data.get('message')}")
# Usage
try:
result = akmond_send('2348012345678', 'β
Your order has been shipped!')
print(f"Sent! Credits used: {result['credits_used']}")
except Exception as e:
print(f"Failed: {e}")
4. WhatsApp Bot Setup (Inbound Webhooks)
Build custom interactive WhatsApp bots for your existing platform. By configuring a Webhook, our engine will instantly forward incoming WhatsApp messages to your server in real-time.
4.1 Configure Your Webhook URL
To start receiving messages, log into your Akmond Notify Dashboard and paste your application's Webhook URL (e.g., https://yourwebsite.com/webhook.php) into the Webhook settings. Ensure your server can accept standard HTTP POST requests.
4.2 Incoming Webhook Payload
When a user sends a message to your connected WhatsApp number, our platform will make a POST request to your Webhook URL with a JSON body formatted like this:
{
"event": "message.received",
"data": {
"sender": "2348012345678",
"message": "Hello, I need help with my order.",
"timestamp": 1720000000
}
}
4.3 Replying to the User
Once your server parses the incoming message and decides on a response (e.g., matching a keyword or interacting with a database), you simply reply by making an API call to our Send Transactional Message endpoint (documented in Section 3.1).
// Example PHP Bot Logic (webhook.php)
$input = file_get_contents('php://input');
$payload = json_decode($input, true);
if ($payload['event'] === 'message.received') {
$sender = $payload['data']['sender'];
$incoming_text = strtolower(trim($payload['data']['message']));
$reply_message = "";
// Simple Keyword Routing
if ($incoming_text === 'hi' || $incoming_text === 'hello') {
$reply_message = "Welcome to our store! Reply with '1' for Support.";
} elseif ($incoming_text === '1') {
$reply_message = "An agent will be with you shortly.";
} else {
$reply_message = "Sorry, I didn't understand that command.";
}
// Call the Send API (Section 3.1) to dispatch the response
send_akmond_alert("akm_live_YOUR_KEY", $reply_message, $sender);
}