Send API

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();
}

import hashlib, hmac, json, os, time, uuid
import requests

def send_utility_message():
    body = json.dumps({
        "APIKey": os.environ["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
    timestamp = str(int(time.time() * 1000))
    nonce = uuid.uuid4().hex
    body_hash = hashlib.sha256(body.encode()).hexdigest()
    signature = hmac.new(
        os.environ["AKEDLY_SIGNING_SECRET"].encode(),
        f"{timestamp}.{nonce}.{body_hash}".encode(),
        hashlib.sha256,
    ).hexdigest()

    res = requests.post(
        "https://api.akedly.io/api/v1/utilities/send",
        headers={
            "Content-Type": "application/json",
            "x-akedly-timestamp": timestamp,
            "x-akedly-nonce": nonce,
            "x-akedly-signature": signature,
        },
        data=body,
    )
    return res.json()

<?php
function sendUtilityMessage() {
  $body = json_encode([
    "APIKey" => getenv("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
  $timestamp = (string) round(microtime(true) * 1000);
  $nonce = bin2hex(random_bytes(16));
  $bodyHash = hash("sha256", $body);
  $signature = hash_hmac(
    "sha256",
    "$timestamp.$nonce.$bodyHash",
    getenv("AKEDLY_SIGNING_SECRET")
  );

  $ch = curl_init("https://api.akedly.io/api/v1/utilities/send");
  curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      "Content-Type: application/json",
      "x-akedly-timestamp: $timestamp",
      "x-akedly-nonce: $nonce",
      "x-akedly-signature: $signature",
    ],
    CURLOPT_POSTFIELDS => $body,
  ]);
  $res = curl_exec($ch);
  curl_close($ch);
  return json_decode($res, true);
}

BODY='{"APIKey":"YOUR_API_KEY","pipelineID":"YOUR_PIPELINE_ID","templateId":"TEMPLATE_ID","variableValues":{"orderNumber":"1042"},"phone":"+201234567890","customerUserId":"user_123"}'
TS=$(($(date +%s) * 1000))
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')
SIG=$(printf '%s' "$TS.$NONCE.$BODY_HASH" \
  | openssl dgst -sha256 -hmac "$AKEDLY_SIGNING_SECRET" -hex | awk '{print $NF}')

curl -X POST https://api.akedly.io/api/v1/utilities/send \
  -H "Content-Type: application/json" \
  -H "x-akedly-timestamp: $TS" \
  -H "x-akedly-nonce: $NONCE" \
  -H "x-akedly-signature: $SIG" \
  -d "$BODY"

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

{
  "APIKey": "<AKEDLY_API_KEY>",
  "pipelineID": "<YOUR_PIPELINE_ID>",
  "text": "Your order #1042 has shipped.",
  "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 by provider",
  "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 the BYO SMS storage rules do not apply to it. It has its own dispatch point instead: the moment just before Akedly calls Meta, after your fee has been reserved.

• Before the dispatch point, a non-2xx — a refused fee, a missing WABA, a template render error, a quota or spend-cap refusal — releases the key: a same-key retry starts a fresh attempt, and nothing was sent.

• After it, a definite failure — Meta rejecting the message (502 send_failed, or a provider-specific code), or a 503 about fee or spend-limit reconciliation — is stored and replayed verbatim for 24 hours. A same-key retry returns that stored failure and does not send again. Once the 24 hours pass the key is gone, and a retry is a new send.

• An unclear outcome is never released. A timeout, a dropped connection, a Meta server error, a Meta reply with no message ID, or a failure after Meta accepted the message is recorded as unknown: the response is 503 IDEMPOTENCY_OUTCOME_UNKNOWN, it is stored with no expiry, and the same key returns it every time. Treat an unclear WhatsApp failure as a support case, not a retry case. A new key, or a retry with no key, is a new send and can deliver the message twice.

• 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 while the first request still holds the key returns a 409, and which one depends on how far it got. If Akedly has only reserved the key and has not yet started the provider call (before the carrier boundary on BYO SMS, before the dispatch point on WhatsApp), the retry gets 409 IDEMPOTENCY_OUTCOME_UNKNOWN while the reservation is younger than 2 minutes. Once the provider call has started, it gets 409 IDEMPOTENCY_IN_PROGRESS for 2 minutes after that call started. 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 those 2 minutes. A reservation that never started a provider call is treated as abandoned after 2 minutes and reclaimed by the retry, which becomes the live attempt. Back off, then retry with the same key.
• A BYO SMS reservation past the carrier boundary never returns 409 and is never reclaimed, even inside those 2 minutes: the retry adopts the in-flight record and continues into reconciliation instead of being turned away. A WhatsApp request that has passed its dispatch point is never reclaimed either: if 2 minutes pass with no stored outcome, the retry gets 503 IDEMPOTENCY_OUTCOME_UNKNOWN (stored with no expiry) rather than a second send.

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