Send API

One POST call sends a utility message — WhatsApp over your own Business Account, or SMS over your own BYO provider. This page is the reference for the endpoint, its responses, and the errors it returns by name — an unexpected internal failure can still surface as an uncoded 500.

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; 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, but is not a hard cap — and does not affect what you pay: the BYO fee is flat per message.)

Channel resolution

The channel is decided before sending, and a send goes out on exactly one channel — the send call itself never retries on the other channel.

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

SMS is feasible when your BYO routing resolves for the destination. Akedly takes the first feasible channel in your pipeline's channel order — WhatsApp first by default, but an SMS-first order sends SMS even when WhatsApp is also feasible. A destination with no feasible WhatsApp path and no BYO route fails with UTILITY_SMS_REQUIRES_BYO or UTILITY_SMS_COUNTRY_NOT_ROUTED — both 409.

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": "Successful",
    "channel": "sms",
    "provider": "own-sms",
    "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 an idempotency key to make retries safer — in the Idempotency-Key header, or as an idempotencyKey field in the request body if a header is inconvenient. Akedly reads the header first and falls back to the body field, for every integration and not just Vodafone; the header wins when both are present. The value must be a string of at most 255 characters. The stored-response reservation uses your key exactly as sent — it is not trimmed, so "a" and " a " reserve separately and a whitespace-only key is reserved like any other. BYO SMS separately trims the key before deriving the identities it sends with — both the transaction identity and the provider's dispatch key — so those two spellings can still converge there; and Vodafone trims it before requiring it, so a whitespace-only key is refused as missing (see below). Send the same exact string every time and none of this can bite you. When Akedly has stored a response for that key, retrying with the same key replays it instead of sending again — but whether a response is stored depends on the channel and on how far the request got, so a key is not on its own a guarantee against a second send.

Beyond that, what a retry actually does depends on the channel and on how far the original request got.

SMS through your own provider (BYO SMS)

• Akedly marks a carrier boundary the moment it hands your message to your provider's API.

• Before that boundary, a non-2xx failure releases the key: retrying with the same key starts a fresh attempt. Any 2xx pre-boundary response is stored and replayed for 24 hours — including a 200 with status: "skipped", which is not a send at all.

• After it, the record no longer expires, and what a retry gets depends on the outcome:

  • Most post-boundary responses — success or error — are stored and replayed verbatim. A retry replays rather than re-attempts. That is deliberate: past that point a new key could submit the message a second time and bill you twice.
  • 503 provider_outcome_reconciliation_pending is the one to think about, and you cannot tell from outside which way it will go. Akedly marks most of these non-replayable on purpose: the stored body is discarded, so a same-key retry re-enters reconciliation and can return a different outcome later — a success, or a 502 send_failed. At least one path does not get that marking and is stored like any other post-boundary response, so the same 503 replays. Do not model either behaviour; keeping the same key is safe both ways. What separates them is progress — an identical 503 returning unchanged over a long period is the stored case, and needs Akedly rather than more retries.

• All of this needs a key. Idempotency here is opt-in for generic integrations — but Vodafone utility SMS requires one, and a Vodafone send without one is refused with 400 VODAFONE_IDEMPOTENCY_KEY_REQUIRED before anything is dispatched. What is required is the key, not specifically the header — either source above satisfies Vodafone, but the value is trimmed before it is checked, so " " is refused exactly like an absent one. Without a key nothing is stored and nothing replays, so do not retry an unclear outcome automatically. WhatsApp

• The WhatsApp path sets no carrier boundary, so none of the BYO SMS storage rules apply to it.

• A failed send is never stored: the key is released and a same-key retry starts a genuinely new attempt.

• ⚠️ That includes ambiguous failures. A timeout or network error is reported as a send failure even though Meta may already have accepted the message, so retrying can deliver it twice. Treat an unclear WhatsApp failure as a support case, not a retry case.

• Any 2xx response is stored and replayed for 24 hours — including a 200 with status: "skipped", which is not a send.

Both channels

• Keys are scoped to your account.
• Reusing a key with different request parameters returns 422 IDEMPOTENCY_KEY_REUSE. The comparison ignores your API key and the idempotencyKey body field, so changing only those is not a reuse — changing the recipient, the text or the template is.
• Retrying before the carrier boundary returns 409 IDEMPOTENCY_IN_PROGRESS while the reservation is younger than 60 seconds. The clock, not the first request, is what decides: Akedly cannot see whether that request is still alive, so a retry after a crash is still refused for the rest of the minute, and past it the reservation is treated as abandoned and reclaimed by the retry, which becomes the live attempt. Back off briefly and retry.
• A BYO SMS reservation past the boundary never returns 409 and is never reclaimed, even inside those 60 seconds: the retry adopts the in-flight record and continues into reconciliation instead of being turned away. ⚠️ WhatsApp never sets that marker, so an expired lease is not evidence that Meta was never reached — do not retry a WhatsApp request automatically just because the 60 seconds elapsed.

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

Request validation errors

Template and content errors

Channel errors

Billing and delivery errors

Idempotency errors