Utilities
Send one-way transactional messages — order confirmations, shipping updates, appointment reminders — from your backend. Utilities are WhatsApp-first: messages go out over your own WhatsApp Business Account, with SMS available as an Egypt-only secondary channel.
Server-to-server only
Utilities are a machine-to-machine API. Sends are triggered from your code — your backend picks a pipeline and template, fills the variables, and calls /utilities/send. There is no captcha or end-user ceremony; security comes from your API key, per-pipeline request signing, and the recipient-eligibility gate.
Get set up
Utilities is configured once in the dashboard, then driven by a single API call. Four one-time steps, then you send.
1. Connect your WhatsApp Business Account
Utility WhatsApp messages go out from your own WABA — never a shared Akedly number — so recipients see your brand. Connect it from the WhatsApp Setup page using Meta's Embedded Signup; it takes about two minutes.
Skip this only if you will send SMS to Egypt exclusively.
2. Create a utility pipeline
A pipeline is your sending policy — channels, allowed destination countries, rate limits, a spend cap, and who's eligible. Create one under Utilities → Pipelines. Its pipelineID is what every API call references. Utility pipelines are separate from OTP pipelines.
3. Create and approve a template
Write your message once as a template with {{variable}} placeholders, then submit it. Every template needs Akedly approval; WhatsApp additionally needs Meta approval. A template you can send with right now is a sendable template — see Templates and dual approval.
4. Reveal your two secrets
Each pipeline has two reveal-once secrets, found in its settings:
- a request-signing secret (
usk_…) your backend signs every API call with — see Request Signing; - a hash secret (
uhs_…) used only to hash allowlist numbers on your device — see Allowlist.
Reveal each once from the pipeline's settings and store them like passwords.
5. Send your first message
With a sendable template and at least one eligible recipient, send with a single signed POST to /utilities/send.
Utilities vs OTP
A utility message is one-way: Akedly delivers it and reports the outcome. There is no verify step.
| Aspect | Utilities | OTP |
|---|---|---|
| Purpose | Notify — confirmations, updates, reminders | Verify — the user proves possession of the number |
| Flow | One call: send | Create, send, verify |
| Channels | WhatsApp (your own WABA), SMS (Egypt only) | WhatsApp, Telegram, SMS, Email with fallback |
| Who can receive | Eligible recipients only (verified or allowlisted) | Any number the user submits |
| Content | Approved templates (free text on SMS) | OTP codes |
| Billing | Per message; WhatsApp billed on delivery | Per message, or PPSA on V2.0 |
Utility pipelines and OTP pipelines are separate. A utility send must reference a utility pipeline — calls against an OTP pipeline are rejected with NOT_A_UTILITY_PIPELINE.
How a send works
Every send is a single POST to https://api.akedly.io/api/v1/utilities/send, authenticated by your API key and pipeline ID in the body and signed with your pipeline's request-signing secret. Akedly then:
- Verifies the request signature and applies your pipeline's rate limits.
- Checks the recipient is eligible.
- Resolves the channel — WhatsApp over your own WABA when the template and destination allow it, otherwise SMS for Egyptian numbers.
- Sends, records the message, and bills it. WhatsApp delivery and billing settle asynchronously when Meta reports the delivery outcome.
The response carries a transactionID you can track in the dashboard's Send History.
Recipient eligibility
Utilities cannot message arbitrary numbers. Every send passes an eligibility gate: the recipient needs at least one of two independent proofs, checked per pipeline.
- Name
verified- Type
- proof
- Description
The number completed a successful Akedly OTP verification for your account before. If you use Akedly for authentication, your verified users are already eligible.
- Name
allowlist- Type
- proof
- Description
The number is in the pipeline's hashed allowlist — numbers are hashed on your device, in the dashboard's browser panel or via the script, and only the hashes are uploaded. Your numbers never leave your device.
Both proofs are toggled in the pipeline's Audience settings and combined with OR — a recipient needs one, not both. A send to a recipient with neither proof is rejected with RECIPIENT_NOT_ELIGIBLE.
You can't message an arbitrary number
Every recipient must be eligible first — either verified through a prior Akedly OTP, or on the pipeline's allowlist. A number with neither proof is rejected with RECIPIENT_NOT_ELIGIBLE; this is the most common first-integration surprise.
To keep your own user IDs attached to eligible numbers — and look them up before a send — see End Users.
Channels
WhatsApp — primary
Sent over your own WhatsApp Business Account, nationally and internationally. A WhatsApp send requires:
- WhatsApp enabled on the pipeline
- A Meta-approved, WhatsApp-usable template
- An active connected WABA
- The destination country in the pipeline's allowed-countries list
Delivery is confirmed asynchronously by Meta, and billing settles on the delivery outcome.
SMS — Egypt only
National SMS for Egyptian numbers. This is the only channel that accepts free-text sends (a text body instead of a template), and the fallback when WhatsApp is not feasible for an Egyptian destination.
International SMS is not available: an international send that cannot resolve to WhatsApp fails with utility_international_requires_whatsapp rather than falling back.
The channel is resolved before sending — a send goes out on exactly one channel, with no cross-channel retry. When both channels are feasible, the pipeline's channel order decides; the default is WhatsApp first.
Without your own WABA, only Egyptian numbers are reachable
Utility WhatsApp goes out over your WhatsApp Business Account. Until you connect one, WhatsApp — and every non-Egyptian recipient — is unavailable: only Egyptian (+20) numbers are reachable, over SMS. An approved template and a configured pipeline still won't deliver on WhatsApp without a connected WABA.
Templates and dual approval
Templates are the message content: a body with {{variable}} placeholders your send call fills in. Every template carries two independent approval tracks:
- Name
Akedly status- Type
- required for any send
- Description
Every template is reviewed by Akedly before it can be sent — on any channel, no exceptions.
- Name
Meta status- Type
- required for WhatsApp
- Description
WhatsApp-usable templates are additionally submitted to Meta for approval. A template that is Akedly-approved but not Meta-approved can still send on SMS.
A sendable template is Akedly-approved and, for WhatsApp sends, Meta-approved. Sending with a template that lacks Akedly approval returns TEMPLATE_NOT_APPROVED; a template without Meta approval simply cannot resolve to WhatsApp.
A brand-new template can't send on WhatsApp until Meta approves it
Akedly approval clears a template for SMS right away, but WhatsApp additionally needs Meta's review, which is asynchronous. Until then, a template resolves to SMS only (or fails, if WhatsApp is the only feasible path for that recipient).
Billing
Utilities are billed per message sent — there is no per-verification pricing.
You only pay for WhatsApp messages that are actually delivered
WhatsApp billing is deferred: a send is accepted immediately but charged only when Meta confirms delivery — messages that never deliver are never billed. SMS, by contrast, bills at send time, per segment.
- WhatsApp — billing is deferred: the send is accepted immediately but billed only when Meta reports the delivery outcome. Messages that never deliver are not billed.
- SMS — billed at send time, per segment. GSM-7 text fits 160 characters per segment (153 when the message spans segments); Arabic or emoji content uses UCS-2 at 70 characters per segment (67 multi-segment). The send response reports the
segmentsandencodingyou were billed for.
Each pipeline can set a daily spend cap for its SMS sends; SMS beyond it is rejected with SPEND_CAP_EXCEEDED until the day rolls over. WhatsApp sends bill on the delivery outcome and are not pre-checked against the cap.