AKKED DEVELOPER API

Send reliable WhatsApp template messages

Use a connected Meta Cloud API or WhatsApp connection for OTPs, order updates, abandoned-cart recovery, and transactional notifications. API access follows your plan and uses your account credits.

Quick start OpenAPI 3.1 JSON

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.Use a plan with API access and connect a Meta or 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 bound sender and its capabilities.
4.Send a published template with an Idempotency-Key, then poll its status_url.

cURL

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"
    }
  }'

Node.js / TypeScript

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.

Endpoint reference

GET/api/v1/senders

Show the Meta or WhatsApp sender bound to this API key.

GET/api/v1/templates

List template contracts and capabilities for the bound sender.

POST/api/v1/messages

Validate, reserve one credit, and queue an approved template message.

GET/api/v1/messages/{id}

Read queued, sending, sent, delivered, read, or failed status.

Idempotency is required. Use a stable business identifier such as order-1048-confirmation. Reuse the same key and identical payload when retrying an uncertain request.

Template contracts

Parameter names are exact and extra fields are rejected. Meta senders require the matching approved template in the connected WABA; WhatsApp connections render the same safe library as text.

order_confirmationUTILITY · en, ar

معاينة بالإنجليزية

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

معاينة بالعربية

أهلاً 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, ar

معاينة بالإنجليزية

Thank you Mona, your order 1048 is confirmed.

معاينة بالعربية

شكراً Mona، تم تأكيد طلبك رقم 1048.

Parameter	Contract	Description
customer_name	string · required · max 120	Customer name
order_number	string · required · max 80	Order number

cancelled_replyUTILITY · en, ar

معاينة بالإنجليزية

Your order 1048 has been cancelled, Mona.

معاينة بالعربية

تم إلغاء طلبك رقم 1048 يا Mona.

Parameter	Contract	Description
customer_name	string · required · max 120	Customer name
order_number	string · required · max 80	Order number

paid_orderUTILITY · en, ar

معاينة بالإنجليزية

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

معاينة بالعربية

شكراً 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, ar

معاينة بالإنجليزية

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.

معاينة بالعربية

أهلاً 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, ar

معاينة بالإنجليزية

Your verification code is: 482901 Do not share this code with anyone.

معاينة بالعربية

رمز التحقق الخاص بك هو: 482901 لا تشارك هذا الرمز مع أي شخص.

Parameter	Contract	Description
code	string · required · max 10	One-time password

Responses and errors

202 Accepted

{
  "id": "dispatch-uuid",
  "status": "queued",
  "status_url": "/api/v1/messages/dispatch-uuid"
}

401Invalid or revoked API key

402Insufficient message credits

403API access, sender, or safety acknowledgement unavailable

409Idempotency-Key reused with a different payload

422Invalid request, opt-out, suppression, or frequency cap

429Send rate limit exceeded

503Database or message queue temporarily unavailable

AI-agent integration prompt

Copy this complete contract into Codex, ChatGPT, Claude, Cursor, or another coding agent.

AI_AGENT_INSTRUCTIONS.md

You are integrating the Akked WhatsApp API.

Base URL: https://akked.app
Authentication: Authorization: Bearer ak_live_YOUR_KEY
Plan requirement: an active plan with API access and a connected sender selected when the API key was created.
Rate limit: 60 authenticated send requests per API key per minute.
Credits: one account credit is reserved for each message and consumed only after the provider accepts it.
Baileys safety: unofficial senders are protected by opt-out checks, frequency caps, warm-up limits, and health pauses, but WhatsApp can still restrict unofficial automation.

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; 403 inactive Growth or sender; 404 sender/template/message not found; 409 idempotency conflict; 422 invalid payload or template parameters; 429 rate limit; 503 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.

Production checklist

Keep API keys server-side and never expose them in browser JavaScript.
يحدد مفتاح API الرقم المستخدم؛ لا تطلب من العملاء إدخال معرّف الرقم.
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.