aulm API

aulm is a WhatsApp messaging API. You connect a phone by scanning a QR code in the dashboard, then send messages and receive inbound events over HTTP. There is no Meta business verification, no template approval, no WABA.

Developer AI assistants (Claude, ChatGPT, Cursor) work best when given a clear specification. Copy the prompt below into your assistant to get correct, production-ready aulm code for your project immediately.

Every request takes a Bearer token in the Authorization header. Keys are generated in the dashboard and match the regex ^alm_sk_(live|test)_[0-9a-f]{64}$.

• alm_sk_live_… — real sends. Billable. Counts against your plan quota.
• alm_sk_test_… — every call is simulated. The messaging service is never invoked, no WhatsApp message is sent, the response shape is identical to live with simulated: true and message_id shaped sim_<hex>. Test sends are never billed.

Keys may also be restricted to specific session IDs. Requests against a non-whitelisted session return 403 session_not_allowed.

Authorization: Bearer alm_sk_live_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

All endpoints are served from a single base URL. The path is versioned with /v1/. Breaking changes get a new path prefix; additive changes (new optional fields, new response headers) ship under /v1/.

https://api.aulm.io

All /v1/* responses are JSON. Success bodies use { data: ..., request_id: ... }; errors use { error: { code, message } }.

Every response — success or error — sets x-request-id. Log it on your side and quote it to support; we can find the exact send in one query.

Send endpoints additionally stamp x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset (ISO 8601), and retry-after on 429s and on upstream-overload 503s.

When a send fails, two things matter: did it cost you a quota slot, and should you retry the same request. aulm publishes both answers explicitly.

Quota refund matrix

What happens to your reserved quota slot when a send fails. Transient = refunded and not billed. Client error = slot kept.

Webhook retries

After a failed attempt, the next attempt is scheduled per this table. Attempt count is 1-indexed and matches `x-aulm-attempt`. `Retry-After` from your response overrides the ladder (capped at 1h).

• Default max attempts per delivery: 6.
• Endpoint auto-disabled after 25 consecutive failures (across deliveries).
• Per-attempt HTTP timeout: 10s.
• Target first-delivery latency: ~60s.

Errors always come back as { error: { code, message } }. The HTTP status tells you the broad class; the error.code tells you the exact cause. See the full error-code index at the bottom of this page.

{
  "error": {
    "code": "session_not_ready",
    "message": "Session is not ready to send messages. Connect the session first."
  }
}

Register a single HTTPS endpoint in the dashboard. aulm POSTs JSON events to it with a signed header, retries failures per the published ladder, and gives you a stable x-aulm-delivery-id for idempotency.

Request headers

Verifying the signature

Always verify over the raw request body bytes — do not re-serialize the JSON.

const crypto = require("crypto");

function verifyAulmSignature(rawBody, header, secret) {
  // header looks like: "t=1716893742,v1=abc123..."
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=")),
  );
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  // timing-safe compare
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Events

{
  "event": "inbound_message",
  "delivery_id": "00000000-0000-4000-8000-000000000000",
  "timestamp": "2026-05-28T10:15:42.000Z",
  "session_id": "00000000-0000-4000-8000-000000000000",
  "test": false,
  "message": {
    "id": "string",
    "from": "string",
    "to": "string",
    "chat_id": "string",
    "type": "string",
    "body": "string",
    "is_group": false,
    "from_me": false,
    "media_url": "https://example.com/...",
    "received_at": "2026-05-28T10:15:42.000Z"
  }
}

{
  "event": "message_status",
  "delivery_id": "00000000-0000-4000-8000-000000000000",
  "timestamp": "2026-05-28T10:15:42.000Z",
  "session_id": "00000000-0000-4000-8000-000000000000",
  "message_id": "string",
  "status": "sent",
  "from": "string",
  "to": "string",
  "status_at": "2026-05-28T10:15:42.000Z"
}

To protect numbers from being banned by WhatsApp, two per-number limits apply to live sends (on top of your plan's daily quota). Test-mode keys (alm_sk_test_…) simulate sends and bypass these guards.

Send velocity

A number may send at most 12 messages per minute. Bursting above this returns 429 rate_too_fast with a Retry-After header. Pace your sends.

Warm-up ramp

A newly-connected number's daily send limit grows over its first two weeks, then your plan quota applies:

Exceeding the warm-up cap returns 429 warmup_daily_limit. A new number on any plan is limited during warm-up regardless of plan size — this is intentional and protects deliverability.

Opt-out (STOP)

If a recipient replies STOP, UNSUBSCRIBE, CANCEL (or equivalent), they are added to your suppression list and further sends to them return 403 recipient_opted_out. This keeps block/report rates low.

Recipient validation

Before a live send, the recipient is checked against WhatsApp. Numbers that are valid E.164 format but not registered on WhatsApp return 422 recipient_not_on_whatsapp. Malformed phone numbers return 404 invalid_request. Both keep the reserved quota slot (no charge).

Sessions per plan

Trial is a fixed 5-day window with a monotonic counter — it ends at whichever comes first: hitting the cap or 5 days from signup. Daily plans reset at next UTC midnight.

New numbers are additionally limited by the warm-up ramp for their first ~2 weeks, regardless of plan.