Actionpackd

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_…

  1. Sign up, then connect the WhatsApp Business number on Number.
  2. 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.
  3. 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.

GET /whatsapp
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.

POST /templates
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"
  ]
}
JSON

201 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.

POST /messages
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.

POST /messages
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

POST /messages
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"
          }
        }
      ]
    }
  }
}
JSON

A 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.

POST /media
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"
POST /messages
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.

GET /messages/{id}
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.

PUT /webhook
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

CodeStatusMeaning
202AcceptedMessage accepted and queued for delivery.
201CreatedTemplate submitted to Meta, or a document uploaded to /v1/media.
200OKThe same template name, language, and content already exist.
400Bad RequestPayload failed validation, the template is not approved, or Idempotency-Key is missing.
401UnauthorizedMissing, invalid, or revoked API key.
402Payment RequiredLive key needs a connected number, or a Meta invoice is unpaid past the grace period.
403ForbiddenTest key used to submit a template or call /v1/media, or the key is missing the scope for this call.
409ConflictA 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.

HTTPcodeWhen
400IDEMPOTENCY_KEY_REQUIREDPOST /messages without Idempotency-Key.
400INVALID_TYPEtype is not text, template, interactive, or document.
400INVALID_INTERACTIVEinteractive is missing, the subtype is unsupported, or a Cloud API limit is exceeded.
400INVALID_DOCUMENTtype is document and document is missing, or it does not have exactly one of id or link.
400INVALID_MEDIAfile or url is missing, or the filename is too long.
400MEDIA_URL_NOT_ALLOWEDThe media URL is not a public HTTPS host. Upload the file instead.
400MEDIA_EXPIREDThe media id is older than 30 days. Upload the file again.
413MEDIA_TOO_LARGEThe document is larger than 100 MB.
415UNSUPPORTED_MEDIA_TYPEUse pdf, txt, doc, docx, xls, xlsx, ppt, or pptx.
400INVALID_PHONEto has fewer than 8 or more than 15 digits. Always start with the country code.
400INVALID_TEXTtype is text and text.body is missing.
400INVALID_TEMPLATEtype is template and template.name is missing.
400TEMPLATE_NOT_APPROVEDName is unknown or not APPROVED for this workspace.
400INVALID_WEBHOOK_URLWebhook URL is not HTTPS.
400WEBHOOK_NOT_CONFIGUREDPOST /webhook/test before PUT /webhook.
402NUMBER_NOT_BILLABLENo phone number id, or a live key on a number that is not a customer line.
402META_INVOICE_OVERDUEMeta invoice unpaid after 7 days. Sends pause. Template writes do not.
403KEY_CREATION_DISABLEDNew API keys are paused. Existing keys still authenticate.
403TEST_KEY_NOT_ALLOWEDapk_test_ tried to submit a template or call /v1/media.
404MEDIA_NOT_FOUNDThe media id does not exist in this workspace, or it was deleted.
409SESSION_WINDOW_CLOSEDSession text, interactive, or document message, and that recipient has not messaged you in 24 hours.
429MEDIA_RATE_LIMITEDThis workspace already has 2 document uploads in progress, or 30 in the last hour.
502MEDIA_UPLOAD_FAILEDWhatsApp rejected the upload.
502MEDIA_FETCH_FAILEDThe media URL could not be downloaded.
502MEDIA_DELETE_FAILEDWhatsApp rejected the delete.
409IDEMPOTENCY_CONFLICTSame Idempotency-Key, different body.
409TEMPLATE_EXISTSSame template name and language, different content.