AKKED DEVELOPER API
Send reliable WhatsApp template messages
Use an active Meta WhatsApp Cloud API sender for OTPs, order updates, abandoned-checkout recovery, and transactional notifications. API access follows your plan and account billing allowance.
Common use cases
OTP and verification
Send 4–10 digit authentication codes using Meta's copy-code button.
Order lifecycle
Confirm receipt, payment, confirmation, or cancellation with consistent parameters.
Cart recovery
Send an approved marketing template containing a secure checkout recovery URL.
Backend automation
Trigger messages from checkout, CRM, ERP, support, or serverless workflows.
Quick start
- 1.Connect a Meta WhatsApp sender.
- 2.Create an API key in Dashboard → API Keys, choose the sender, and save it once.
- 3.Call GET /api/v1/senders to confirm the sender bound to the API key.
- 4.Send a published template with an Idempotency-Key, then poll its status_url.
curl -X POST https://akked.app/api/v1/messages \
-H "Authorization: Bearer ak_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1048-confirmation" \
-d '{
"to": "+201012345678",
"template_key": "confirmed_reply",
"language": "en",
"parameters": {
"customer_name": "Mona",
"order_number": "1048"
}
}'const response = await fetch("https://akked.app/api/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer ak_live_YOUR_KEY",
"Content-Type": "application/json",
"Idempotency-Key": `order-${order.id}-confirmation`,
},
body: JSON.stringify({
to: customer.phone,
template_key: "confirmed_reply",
language: "en",
parameters: {
customer_name: customer.name,
order_number: String(order.id),
},
}),
});
const message = await response.json();
if (!response.ok) throw new Error(message.error?.message);
// Poll message.status_url until sent, delivered, read, or failed.AI-agent integration prompt
Copy this complete contract into ChatGPT, Claude, Gemini, Perplexity, or another coding assistant.
You are integrating the Akked WhatsApp API.
Base URL: https://akked.app
Authentication: Authorization: Bearer ak_live_YOUR_KEY
Requirement: an active Meta WhatsApp sender bound to the API key.
Rate limits: 60 authenticated send requests per API key per minute and 120 per sender per minute.
Billing: legacy message-credit billing reserves one account credit per message. With contact billing, the first outbound message to a contact in a billing month reserves one unit from the plan's monthly unique-contact allowance; further sends to that contact in the same month, from any of your numbers, use no additional unit. The response's credits_remaining equals the remaining unique-contact allowance; billing.contact_allowance has the full usage detail.
WhatsApp policy: use approved templates as required by Meta, respect customer consent and opt-outs, and follow the template category and messaging rules.
Workflow:
1. GET /api/v1/senders to confirm the sender bound to the API key.
2. GET /api/v1/templates to read template contracts for that sender.
3. POST /api/v1/messages with a unique Idempotency-Key header.
4. Poll GET /api/v1/messages/{id} using the returned status_url.
POST /api/v1/messages body:
{
"to": "+E164_PHONE",
"template_key": "one of the contracts below",
"language": "en or ar",
"parameters": { "exact keys required by that template": "values" }
}
Never retry with a new Idempotency-Key when the outcome is uncertain. Reuse the same key and payload. A reused key with a different payload returns 409.
Template contracts:
- order_confirmation [en, ar]: customer_name (string, required, max 120); order_number (string, required, max 80); store_name (string, required, max 120); total (string, required, max 40); currency (string, required, max 3); items (string, required, max 2000); address (string, required, max 512); order_date (string, required, max 64)
- confirmed_reply [en, ar]: customer_name (string, required, max 120); order_number (string, required, max 80)
- cancelled_reply [en, ar]: customer_name (string, required, max 120); order_number (string, required, max 80)
- paid_order [en, ar]: customer_name (string, required, max 120); order_number (string, required, max 80); store_name (string, required, max 120); total (string, required, max 40); currency (string, required, max 3); items (string, required, max 2000); address (string, required, max 512); order_date (string, required, max 64)
- abandoned_cart [en, ar]: customer_name (string, required, max 120); store_name (string, required, max 120); total (string, required, max 40); currency (string, required, max 3); cart_step (string, required, max 120); recovery_url (string, required, max 2048)
- otp [en, ar]: code (string, required, max 10)
Important errors: 401 invalid key; 402 insufficient credits or contact allowance; 403 API access or sender unavailable; 404 sender/template/message not found; 409 idempotency conflict; 422 invalid payload, template parameters, or recipient policy; 429 rate limit; 503 API queue unavailable.
Generate production code that validates configuration, preserves the Idempotency-Key across retries, logs the x-request-id response header, and never logs the API secret.Endpoint reference
/api/v1/sendersShow the Meta or WhatsApp sender bound to this API key.
/api/v1/templatesList template contracts and capabilities for the bound sender.
/api/v1/messagesValidate billing allowance, reserve usage, and queue an approved template message.
/api/v1/messages/{id}Read queued, sending, sent, delivered, read, or failed status.
Template contracts
Parameter names are exact and extra fields are rejected. Each API key exposes templates approved and available to its bound Meta WhatsApp sender.
Use an approved Meta template you own
An API key bound to a Meta sender can list and send approved templates owned by that sender's WABA. Use template_name instead of template_key and pass normalized component parameters in Meta order.
{
"to": "+201012345678",
"template_name": "delivery_report",
"language": "ar",
"components": [{
"type": "body",
"parameters": [
{ "type": "text", "text": "Ahmed" },
{ "type": "text", "text": "95%" }
]
}]
}order_confirmationUTILITY · en, arEnglish preview
Hi Mona! 👋 Your order 1048 from Akked Store has been received. Total: 450 EGP Items: 1 x Sneakers Delivery to: Cairo, Egypt Order date: July 26, 2026
Arabic preview
أهلاً Mona! 👋 نؤكد استلام طلبك رقم 1048 من Akked Store الإجمالي: 450 EGP المنتجات: 1 x Sneakers العنوان: Cairo, Egypt تاريخ الطلب: July 26, 2026
| Parameter | Contract | Description |
|---|---|---|
| customer_name | string · required · max 120 | Customer name |
| order_number | string · required · max 80 | Order number |
| store_name | string · required · max 120 | Store name |
| total | string · required · max 40 | Formatted order total |
| currency | string · required · max 3 | ISO 4217 currency code |
| items | string · required · max 2000 | Formatted line items |
| address | string · required · max 512 | Delivery address |
| order_date | string · required · max 64 | Order date |
confirmed_replyUTILITY · en, arEnglish preview
Thank you Mona, your order 1048 is confirmed.
Arabic preview
شكراً Mona، تم تأكيد طلبك رقم 1048.
| Parameter | Contract | Description |
|---|---|---|
| customer_name | string · required · max 120 | Customer name |
| order_number | string · required · max 80 | Order number |
cancelled_replyUTILITY · en, arEnglish preview
Your order 1048 has been cancelled, Mona.
Arabic preview
تم إلغاء طلبك رقم 1048 يا Mona.
| Parameter | Contract | Description |
|---|---|---|
| customer_name | string · required · max 120 | Customer name |
| order_number | string · required · max 80 | Order number |
paid_orderUTILITY · en, arEnglish preview
Thank you Mona! Your order 1048 from Akked Store has been paid and confirmed. Total: 450 EGP Items: 1 x Sneakers Delivery to: Cairo, Egypt
Arabic preview
شكراً Mona! تم دفع وتأكيد طلبك رقم 1048 من Akked Store. الإجمالي: 450 EGP المنتجات: 1 x Sneakers العنوان: Cairo, Egypt
| Parameter | Contract | Description |
|---|---|---|
| customer_name | string · required · max 120 | Customer name |
| order_number | string · required · max 80 | Order number |
| store_name | string · required · max 120 | Store name |
| total | string · required · max 40 | Formatted order total |
| currency | string · required · max 3 | ISO 4217 currency code |
| items | string · required · max 2000 | Formatted line items |
| address | string · required · max 512 | Delivery address |
| order_date | string · required · max 64 | Order date |
abandoned_cartMARKETING · en, arEnglish preview
Hi Mona! Your products from Akked Store are still waiting for you. Total: 450 EGP Last step: checkout Complete your order here: https://akked.app/r/example-token Reply STOP if you no longer want these messages.
Arabic preview
أهلاً Mona! ما زالت منتجاتك من Akked Store في انتظارك. الإجمالي: 450 EGP آخر خطوة: checkout أكمل طلبك من هنا: https://akked.app/r/example-token إذا لم تعد ترغب في استلام هذه الرسائل، أرسل STOP.
| Parameter | Contract | Description |
|---|---|---|
| customer_name | string · required · max 120 | Customer name |
| store_name | string · required · max 120 | Store name |
| total | string · required · max 40 | Formatted cart total |
| currency | string · required · max 3 | ISO 4217 currency code |
| cart_step | string · required · max 120 | Checkout step |
| recovery_url | string · required · max 2048 | Checkout recovery URL |
otpAUTHENTICATION · en, arEnglish preview
Your verification code is: 482901 Do not share this code with anyone.
Arabic preview
رمز التحقق الخاص بك هو: 482901 لا تشارك هذا الرمز مع أي شخص.
| Parameter | Contract | Description |
|---|---|---|
| code | string · required · max 10 | One-time password |
Responses and errors
{
"id": "dispatch-uuid",
"status": "queued",
"status_url": "/api/v1/messages/dispatch-uuid",
"credits_remaining": 120,
"billing": {
"model": "unique_contacts",
"contact_allowance": {
"limit": 500,
"used": 12,
"reserved": 1,
"remaining": 487,
"current_contact_already_counted": false,
"period_ends_at": "2026-10-01T00:00:00.000Z"
}
},
"rate_limits": { "api_key_per_minute": 60, "sender_per_minute": 120 }
}With contact billing, each distinct contact counts once per billing month across all of your senders. Pending reservations reduce the remaining allowance too. credits_remaining equals the remaining unique-contact allowance; billing.contact_allowance has the full detail. API rate limits are independent of billing. A sent status means Meta accepted the message; poll status_url for delivered, read, or failed (outbound webhooks are planned).
401Invalid or revoked API key402Insufficient message credits403API access, sender, or safety acknowledgement unavailable409Idempotency-Key reused with a different payload422Invalid request, opt-out, suppression, or frequency cap429Send rate limit exceeded503Database or message queue temporarily unavailableProduction checklist
- Keep API keys server-side and never expose them in browser JavaScript.
- The API key selects the sender; do not ask customers to provide a sender UUID.
- Persist Idempotency-Key values with the business event you are sending.
- Log x-request-id and dispatch id, but never log the API key or OTP code.
- Handle failed delivery statuses and alert an operator when failures repeat.