POST /api/v1/whatsapp/send
Send a receipt or purchase-order template over WhatsApp using AskBiz's Meta Business API connection. Account-mode keys only — 2¢ per successful send, debited after Meta confirms delivery.
What it does
Sends a WhatsApp message through AskBiz’s Meta Business API connection, using one of two pre-approved templates: receipt or purchase_order. Your account is debited 2 cents per successful send, and only after Meta confirms the message was actually sent — a failed send never costs you anything.
This endpoint requires an account-mode key. A generic-mode key gets a 403 — generic keys have no tie to a real AskBiz business, so this deliberately can’t be used as an open message-blasting gateway for arbitrary WhatsApp numbers.
Request
curl -X POST https://askbiz.co/api/v1/whatsapp/send \
-H "x-api-key: abz_live_your_key_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7c4f1a2e-9d3b-4e6a-8f21-1b5c9a0d3e7f" \
-d '{
"phone": "+254712345678",
"template": "receipt",
"text": "Receipt #1042 — Coca-Cola 500ml x2, Total KES 160. Thank you for your purchase."
}'Body parameters
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | Recipient in international format, e.g. +254712345678. |
template | string | Yes | Either receipt or purchase_order. There is no third option — otp is reserved for AskBiz’s own login flow and is never available through this endpoint. |
text | string | Yes | Message body, max 1024 characters. |
Response
On a confirmed send:
{
"success": true
}If the send pushes your wallet below its low-balance threshold, the same 200 response also carries low_balance_warning: true and the new balance_cents — in-band, at the moment it happens, not just when you hit a 402 on a later call:
{
"success": true,
"low_balance_warning": true,
"balance_cents": 340
}If your balance can’t cover the 2¢ send before it’s even attempted:
{
"error": "Insufficient credits",
"required_cents": 2
}On a test key (abz_test_…), no message ever reaches Meta and your wallet is never touched — you get this instead, every time:
{
"success": true,
"test_mode": true
}See Build safely with a sandbox key for the full test/live picture across every endpoint.
Errors
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, invalid phone format, invalid template, or text over 1024 characters. |
| 401 | Missing or invalid x-api-key. |
| 402 | Insufficient credits — response includes required_cents. |
| 403 | Key is in generic mode. This endpoint requires an account-mode key tied to a real AskBiz business. |
| 429 | Rate limit or monthly quota exceeded — check the X-RateLimit-Remaining response header. |
| 502 | Meta’s WhatsApp API failed to send the message. Nothing is charged — safe to retry with the same Idempotency-Key. |
Send an Idempotency-Key header on every call. If a request times out and you don’t know whether it landed, retrying with the same key returns the original result instead of sending a second real WhatsApp message and debiting a second 2¢. See Errors and retries for the full contract.
WhatsApp send FAQ
Why can’t I send an OTP template through this endpoint?+
The otp template is reserved for AskBiz’s own login flow and is not exposed through the public API — only receipt and purchase_order are available to send.
Can I use a generic-mode key to send WhatsApp messages?+
No. This endpoint requires an account-mode key, which is tied to a real AskBiz business. A generic-mode key gets a 403, because without that tie the endpoint could otherwise be used as an open message-blasting gateway to arbitrary phone numbers.
When am I actually charged the 2 cents?+
Only after Meta confirms the message was sent successfully. A 400, 401, 402, 403, or 502 response is never billed.
What happens if my network call times out and I don’t know if the message went out?+
Retry the exact same request with the same Idempotency-Key header. If the first attempt already succeeded server-side, you get back that original result instead of a second message being sent and a second 2¢ debit.
Can I test this endpoint without sending a real WhatsApp message?+
Yes — use a test key (abz_test_…). It skips Meta entirely and never touches your wallet, always returning { success: true, test_mode: true }. See Build safely with a sandbox key.