Send API

One POST call sends a utility message — WhatsApp over your own Business Account, or SMS inside Egypt. This page is the complete reference for the endpoint, its responses, and every error it can return.

The send call

const crypto = require("crypto");

async function sendUtilityMessage() {
  const body = JSON.stringify({
    APIKey: process.env.AKEDLY_API_KEY,
    pipelineID: "<YOUR_PIPELINE_ID>", // your utility pipeline
    templateId: "<TEMPLATE_ID>", // Order shipped (en)
    variableValues: {
      orderNumber: "1042", // {{orderNumber}}
    },
    phone: "+201234567890", // recipient, E.164
    customerUserId: "user_123", // your internal user id
  });

  // sign the exact body bytes with this pipeline's signing secret
  const timestamp = Date.now().toString();
  const nonce = crypto.randomUUID();
  const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
  const signature = crypto
    .createHmac("sha256", process.env.AKEDLY_SIGNING_SECRET)
    .update(`${timestamp}.${nonce}.${bodyHash}`)
    .digest("hex");

  const res = await fetch("https://api.akedly.io/api/v1/utilities/send", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-akedly-timestamp": timestamp,
      "x-akedly-nonce": nonce,
      "x-akedly-signature": signature,
    },
    body,
  });
  return res.json();
}

{
  "APIKey": "<AKEDLY_API_KEY>",
  "pipelineID": "<YOUR_PIPELINE_ID>",
  "templateId": "<TEMPLATE_ID>",
  "variableValues": {
    "orderNumber": "1042"
  },
  "phone": "+201234567890",
  "customerUserId": "user_123"
}

Two body modes

• Template mode — templateId + variableValues. Works on WhatsApp and SMS; the only mode that can reach WhatsApp.
• Free-text mode — text instead of a template. SMS-only and Egypt-only; useful for content that does not fit a fixed template.

Provide one or the other. A body with neither returns MISSING_TEXT.

Template variables

Template variables are the {{name}} placeholders in a template body; your send call fills them via variableValues (keys are case-sensitive and must match the declared names). Each variable can also carry two optional attributes — set when you author the template.

The whole template body is capped at 1024 characters — checked with your example values when the template is created, the same limit Meta applies to WhatsApp bodies. (SMS segment count grows with the rendered length for billing, but is not a hard cap.)

Channel resolution

The channel is decided before sending, and a send goes out on exactly one channel — there is no cross-channel retry.

WhatsApp is used when all of these hold:

1. WhatsApp is enabled on the pipeline
2. The send is template mode and the template is WhatsApp-usable and Meta-approved
3. Your WhatsApp Business Account is connected and active
4. The destination country is in the pipeline's allowed-countries list

Otherwise SMS is used for Egyptian numbers. When both channels are feasible, the pipeline's channel order decides (default: WhatsApp first). An international destination with no feasible WhatsApp path fails with utility_international_requires_whatsapp.

Responses

{
  "status": "success",
  "message": "Utility WhatsApp accepted",
  "data": {
    "transactionID": "AKDLYTXN…",
    "status": "Pending",
    "channel": "whatsapp",
    "provider": "own-waba",
    "recipient": "+201234567890",
    "customerUserId": "user_123",
    "wamid": "wamid.HBgM…",
    "billed": false,
    "billing": { "status": "deferred" }
  }
}

{
  "status": "success",
  "message": "Utility SMS accepted",
  "data": {
    "transactionID": "AKDLYTXN…",
    "status": "Pending",
    "channel": "sms",
    "provider": "cequens",
    "segments": 1,
    "encoding": "GSM7",
    "recipient": "+201234567890",
    "customerUserId": "user_123",
    "billed": true,
    "billing": { "…": "…" }
  }
}

{
  "status": "skipped",
  "code": "RECIPIENT_SUPPRESSED",
  "message": "Recipient has opted out; message not sent.",
  "data": {
    "recipient": "+201234567890",
    "skipped": true,
    "transactionID": "AKDLYTXN…"
  }
}

Idempotent retries

Send the optional Idempotency-Key header (any unique string, up to 255 characters) to make retries safe: if the send succeeded, retrying with the same key replays the original response instead of sending twice.

• Only successful (2xx) responses are stored and replayed. Errors release the key, so a failed send stays retryable with the same key.
• The replay window is 24 hours per key, scoped to your account.
• Reusing a key with a different body returns 422 IDEMPOTENCY_KEY_REUSE.
• Retrying while the first request is still running returns 409 IDEMPOTENCY_IN_PROGRESS — back off briefly and retry.

Because a retried request is a new HTTP request, sign it with a fresh timestamp and nonce; only the Idempotency-Key stays the same.

Rate limits

Rate limits are configured per pipeline in the dashboard, as per-recipient and per-pipeline windows (per minute, hour, and day). Exceeding one returns 429 with a machine-readable cooldown:

{
  "status": "error",
  "code": "RATE_LIMIT_PHONENUMBER_PERMINUTE",
  "message": "Rate limit exceeded for phoneNumber per minute",
  "retryable": true,
  "retryAfter": "2026-07-14T12:01:00.000Z",
  "cooldownSeconds": 42,
  "details": { "type": "phoneNumber", "window": "perMinute", "max": 1, "current": 1 }
}

The code combines the limited identifier (PHONENUMBER or PIPELINE) with the window (PERMINUTE, PERHOUR, PERDAY). Honor retryAfter — retrying earlier only re-hits the limit.

Error reference

Errors share one structure:

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Human-readable description"
}

Rate-limit errors add retryable, retryAfter, cooldownSeconds, and details; template variable errors add missing (SMS) or variable (WhatsApp).

Key limits

Authentication and pipeline errors

Request signing errors

Recipient and eligibility errors

Template and content errors

Channel errors

Billing and delivery errors

Idempotency errors