API reference
Send a WhatsApp message
Sign up, connect a number, and create keys in this console. The console also lists templates, sets the webhook, shows logs and usage, and shows the inbox of replies and accepted sends. Creating a template and sending a message are requests to the base URL below. There is no send or reply form. Paths in the examples are relative to that URL.
Base URL
https://api.actionpackd.com/v1
Authorization
Bearer apk_test_… or apk_live_…
- Sign up, then connect the WhatsApp Business number on Number.
- A test key is a sandbox: sends are validated and return delivered with a webhook, but nothing reaches WhatsApp and nothing is billed. Test keys cannot submit templates or upload media. A live key sends on the connected number.
- Create a key on Keys. Copy it once. The examples below use
$KEY.
1GET /whatsapp
Confirm the number
GET /whatsapp needs numbers:read. A live send needs a connected WhatsApp Business number.
API=https://api.actionpackd.com/v1
KEY=apk_test_...
curl "$API/whatsapp" \
-H "Authorization: Bearer $KEY"2POST /templates
Create a template
POST /templates needs templates:write. A live key also needs a connected number. The same name, language, and content returns the existing template with 200. A different body for that name returns 409 and TEMPLATE_EXISTS.
Placeholders use Meta's {{1}} form. Each one needs a sample in bodyExamples, in the same order. Meta rejects a variable at the start or end of the text. Template fundamentals
The request uses body, header, footer, and buttons. We build the components array WhatsApp stores. GET /templates/$TEMPLATE_ID returns that array. Meta template components
category is MARKETING, UTILITY, or AUTHENTICATION. {{1}} needs the first bodyExamples string, and the body needs text before and after the variable.
API=https://api.actionpackd.com/v1
KEY=apk_live_...
curl -X POST "$API/templates" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d @- <<'JSON'
{
"name": "order_update",
"category": "UTILITY",
"language": "en",
"body": "Your order {{1}} is on the way.",
"bodyExamples": [
"1842"
]
}
JSON201 includes id and status. Poll GET /templates/$TEMPLATE_ID until status is APPROVED, or call POST /templates/sync.
3POST /messages
Send the template
POST /messages needs messages:send and an Idempotency-Key header.
That key is a unique string you make for one send. If the request times out and you retry with the same key and the same body, the API returns the original message id and does not send WhatsApp a second time. A different recipient, or a different template, needs a new key. In a shell, $(uuidgen) creates one. In Node, use crypto.randomUUID(). In Python, use str(uuid.uuid4()). Do not reuse one key for every request.
template.componentsis Meta's send-template parameter list: type and parameters. We pass that array through on the Cloud API template message. Leave it out when the template has no variables. One {{1}} in the body needs one text parameter. Those objects are Meta's send syntax in template components and template fundamentals.
API=https://api.actionpackd.com/v1
KEY=apk_live_...
curl -X POST "$API/messages" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"to": "919876543210",
"type": "template",
"template": {
"name": "order_update",
"language": "en",
"components": [
{ "type": "body", "parameters": [{ "type": "text", "text": "1842" }] }
]
}
}'202 means the message is queued. Save id as $MESSAGE_ID.
4POST /messages
Reply inside the 24-hour window
Free-form text, interactive messages, and documents are only accepted after that customer has messaged your number in the last 24 hours. A closed window returns 409. Send an approved template instead. This is a new send, so it gets a new idempotency key.
API=https://api.actionpackd.com/v1
KEY=apk_live_...
curl -X POST "$API/messages" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"to":"919876543210","type":"text","text":{"body":"Your order has shipped."}}'Interactive
Same window, same POST /messages call. interactive is the Cloud API object. A bad shape returns 400 INVALID_INTERACTIVE.
Body up to 1,024 characters. 1–3 buttons. Title up to 20, id up to 256. Meta
API=https://api.actionpackd.com/v1
KEY=apk_live_...
curl -X POST "$API/messages" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d @- <<'JSON'
{
"to": "919876543210",
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "Confirm this order?"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "yes",
"title": "Confirm"
}
},
{
"type": "reply",
"reply": {
"id": "no",
"title": "Cancel"
}
}
]
}
}
}
JSONA button tap and a list tap arrive on your webhook as message.interactive.button_reply or message.interactive.list_reply. A URL button opens the browser and does not send a reply.
5POST /media · POST /messages
Send a document
Upload the file first with POST /media, then send it with type: "document" and the returned id. You can also pass a public https link instead of uploading. Both need messages:send. Uploads need a live key. A production test key returns 403.
Allowed types are pdf, txt, doc, docx, xls, xlsx, ppt, and pptx, up to 100 MB. The media id expires 30 days after upload. document must include exactly one of id or link. Filename is optional, at most 240 characters. Caption is optional, at most 1,024.
API=https://api.actionpackd.com/v1
KEY=apk_live_...
curl -X POST "$API/media" \
-H "Authorization: Bearer $KEY" \
-F "file=@invoice.pdf" \
-F "filename=invoice.pdf"API=https://api.actionpackd.com/v1
KEY=apk_live_...
curl -X POST "$API/messages" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"to":"919876543210","type":"document","document":{"id":"MEDIA_ID","filename":"invoice.pdf","caption":"Invoice for order 1842"}}'6GET /messages/{id}
Read the result
GET /messages/$MESSAGE_ID needs messages:read. Status moves from queued to sent, delivered, read, or failed.
API=https://api.actionpackd.com/v1
KEY=apk_test_...
MESSAGE_ID=the-id-from-the-202-response
curl "$API/messages/$MESSAGE_ID" \
-H "Authorization: Bearer $KEY"7PUT /webhook
Receive replies and receipts
PUT /webhook needs webhooks:write. The first save returns secret once. Changing only the URL keeps it; send "rotate_secret": true for a new one.
Verify X-Actionpackd-Signature-V2: HMAC-SHA256 of `${timestamp}.${rawBody}`, where timestamp is X-Actionpackd-Timestamp in Unix seconds. Reject timestamps older than 5 minutes. X-Actionpackd-Signature (raw body only) stays for existing integrations.
API=https://api.actionpackd.com/v1
KEY=apk_test_...
curl -X PUT "$API/webhook" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hooks/whatsapp"}'Status codes
| Code | Status | Meaning |
|---|---|---|
| 202 | Accepted | Message accepted and queued for delivery. |
| 201 | Created | Template submitted to Meta, or a document uploaded to /v1/media. |
| 200 | OK | The same template name, language, and content already exist. |
| 400 | Bad Request | Payload failed validation, the template is not approved, or Idempotency-Key is missing. |
| 401 | Unauthorized | Missing, invalid, or revoked API key. |
| 402 | Payment Required | Live key needs a connected number, or a Meta invoice is unpaid past the grace period. |
| 403 | Forbidden | Test key used to submit a template or call /v1/media, or the key is missing the scope for this call. |
| 409 | Conflict | A session text, interactive, or document message was rejected because the 24-hour window is closed, or this template name already exists with different content. |
Error codes
Failed calls return JSON { "error", "code" }. Branch on code. 401 and a missing-scope 403 have no code field.
| HTTP | code | When |
|---|---|---|
| 400 | IDEMPOTENCY_KEY_REQUIRED | POST /messages without Idempotency-Key. |
| 400 | INVALID_TYPE | type is not text, template, interactive, or document. |
| 400 | INVALID_INTERACTIVE | interactive is missing, the subtype is unsupported, or a Cloud API limit is exceeded. |
| 400 | INVALID_DOCUMENT | type is document and document is missing, or it does not have exactly one of id or link. |
| 400 | INVALID_MEDIA | file or url is missing, or the filename is too long. |
| 400 | MEDIA_URL_NOT_ALLOWED | The media URL is not a public HTTPS host. Upload the file instead. |
| 400 | MEDIA_EXPIRED | The media id is older than 30 days. Upload the file again. |
| 413 | MEDIA_TOO_LARGE | The document is larger than 100 MB. |
| 415 | UNSUPPORTED_MEDIA_TYPE | Use pdf, txt, doc, docx, xls, xlsx, ppt, or pptx. |
| 400 | INVALID_PHONE | to has fewer than 8 or more than 15 digits. Always start with the country code. |
| 400 | INVALID_TEXT | type is text and text.body is missing. |
| 400 | INVALID_TEMPLATE | type is template and template.name is missing. |
| 400 | TEMPLATE_NOT_APPROVED | Name is unknown or not APPROVED for this workspace. |
| 400 | INVALID_WEBHOOK_URL | Webhook URL is not HTTPS. |
| 400 | WEBHOOK_NOT_CONFIGURED | POST /webhook/test before PUT /webhook. |
| 402 | NUMBER_NOT_BILLABLE | No phone number id, or a live key on a number that is not a customer line. |
| 402 | META_INVOICE_OVERDUE | Meta invoice unpaid after 7 days. Sends pause. Template writes do not. |
| 403 | KEY_CREATION_DISABLED | New API keys are paused. Existing keys still authenticate. |
| 403 | TEST_KEY_NOT_ALLOWED | apk_test_ tried to submit a template or call /v1/media. |
| 404 | MEDIA_NOT_FOUND | The media id does not exist in this workspace, or it was deleted. |
| 409 | SESSION_WINDOW_CLOSED | Session text, interactive, or document message, and that recipient has not messaged you in 24 hours. |
| 429 | MEDIA_RATE_LIMITED | This workspace already has 2 document uploads in progress, or 30 in the last hour. |
| 502 | MEDIA_UPLOAD_FAILED | WhatsApp rejected the upload. |
| 502 | MEDIA_FETCH_FAILED | The media URL could not be downloaded. |
| 502 | MEDIA_DELETE_FAILED | WhatsApp rejected the delete. |
| 409 | IDEMPOTENCY_CONFLICT | Same Idempotency-Key, different body. |
| 409 | TEMPLATE_EXISTS | Same template name and language, different content. |



