Your own SMS provider

Build an integration

An integration tells Akedly how to call your SMS provider's API. Build it once in the BYO SMS registry, test it, and activate it.

Build with AI agents

Managed Vodafone integrations differ

BYO SMS here describes an integration you build and own. If Akedly operates a managed Vodafone integration for your account, several of the capabilities described below are fixed by Akedly and are not yours to set — see Managed Vodafone.

Where to build it

The SMS Integrations page holds your account-level registry. Select New integration to open the builder.

View in dashboardChannels → Setup → BYO SMS Setup

Open the SMS Integrations registry and create an integration. A managed Vodafone integration cannot be created this way — Akedly provisions it for you, and the rest of this page describes the builder you will not use.

Own SMS fee

The registry shows each integration's resolved Own SMS fee. For OTP, the flat platform fee is charged per successful verification; for utility SMS, it is charged per accepted provider submission. The default is 0.05 EGP, and an Akedly-set account or integration override may apply; see the Overview for billing details. Organisation admins always see these fees; members need the rates-explorer permission, and the fee is hidden from them without it.

Step 1: Basics

Identify the integration in the registry.

Use a clear name

Name integrations by provider and scope so operators can distinguish them in the registry and pipeline settings.

Control	Effect
Namestring · required	The integration name shown in the registry and in verification history entries that used it.
Descriptionstring · optional	A short note about the provider, environment, or intended coverage.

Step 2: Coverage & failure behavior

Choose where the integration can route and what Akedly should do if its request chain fails. On a managed Vodafone integration neither is yours to set — coverage is fixed to Egypt and the failure behaviour is Akedly's.

Utility SMS coverage

Utility SMS has no Akedly SMS route behind it. To send utility SMS to a country, include that country in the coverage list (or use a catch-all) so the destination routes through your provider. OTP routing is separate and may still use Akedly's own providers where available.

Control	Effect
Send to all countriestoggle	Turn on for catch-all coverage — the integration can serve any destination country. Turn off to select specific countries.
Countriessearchable picker	Appears when Send to all countries is off. Select from Akedly's routable catalog of ISO-coded countries. A managed Vodafone integration is fixed to Egypt and rejects any other coverage.
If your API failsselect	For OTP sends, Fall back to Akedly's SMS (recommended) handles a failed request chain by sending through Akedly's own SMS providers at their normal SMS rates. Strict fails the SMS instead and lets the normal channel fallback chain continue. Utility SMS always treats a failed chain as strict and does not use an Akedly SMS fallback.

Step 3: Secrets

Store provider credentials once, then reference them from any request-chain field.

Managed Vodafone: three fixed credentials

A managed Vodafone integration does not take arbitrary named secrets. It accepts exactly accountId, password and secureHashSecretKey, and rejects any other name. None can be removed once set, and changing any of them deactivates the integration until it passes its test again.

Secrets are write-only

Akedly encrypts secret values and does not display them after saving. Keep the source value in your own secret manager.

Control	Effect
Secret namestring	A stable name for the credential, such as `apiToken`.
Secret referencetemplate	Reference the credential anywhere in a step as `{{secrets.name}}`, replacing `name` with the stored secret name.
Add secretbutton	Adds another named, encrypted credential to the integration.

Step 4: Request chain

Not applicable to a managed Vodafone integration

This step and the two that follow it — Advanced options (per step) and Chain execution limits — describe a request chain you author. On a managed Vodafone integration none of it is yours: the chain is stored empty, the dashboard rejects any attempt to set one, and Akedly's adapter performs the provider call under its own timing. Read all three only for an integration you build yourself.

Define the ordered HTTP requests Akedly fires to send one SMS. Multi-step flows can fetch an auth token before calling the provider's send API. A managed Vodafone integration has no request chain of yours — Akedly's adapter carries the send, and this step does not apply.

Choose exactly one send step

After the send step succeeds, Akedly stops the chain, preventing duplicate sends.

Control	Effect
Step namestring · optional	A label that describes the request, such as `Get auth token` or `Send SMS`.
Requestmethod + URL	Select the HTTP method and enter the provider's HTTPS URL.
Body formatselect	Choose how the request body is encoded: JSON, Form-encoded, Raw text, or No body.
Body fieldseditor	Enter the data your provider expects. For a JSON body, add key/value Fields or switch to Manual JSON to write the template directly. Template variables are allowed in the values.
Send stepradio	Marks the one request whose success means the SMS was accepted.
Add stepbutton	Appends another request to the chain.

Template variables

Use these placeholders in URLs, headers, query parameters, and body templates.

Variable	Value
`{{otp}}`	The OTP code for verification sends; for one-way utility SMS, the complete message text
`{{message}}`	The same message value as `{{otp}}`: the OTP code for verification sends or the complete utility message
`{{phone}}`	Destination number in international format (+2010…)
`{{phoneLocal}}`	Destination number as international digits, including the country code, with `+` removed
`{{companyName}}`	Your company name, as set on your account
`{{locale}}`	The normalized OTP locale for verification sends
`{{otpMessage}}`	The localized OTP message for verification sends
`{{transactionId}}`	The Akedly transaction ID for this send
`{{vars.name}}`	A value extracted from an earlier step's response
`{{secrets.name}}`	A secret you stored on this integration

Check variable names

Despite its dashboard label, {{phoneLocal}} resolves to the international number's digits, including the country code, with the + removed. Unknown or misspelled placeholders resolve to an empty string without an error. If the same integration also delivers one-way utility SMS, {{otp}} carries the complete utility message on those sends, not a code — template it as the message body, not inside a sentence.

Advanced options (per step)

Expand Advanced — headers, auth & response handling inside each step.

Verify provider success

Akedly checks each step's HTTP status against the Success status codes list. The dashboard's success check is status-only, so a provider error inside an accepted HTTP status can still count as success; prefer an endpoint that signals failure with an HTTP error status and confirm real delivery when you test the integration.

Control	Effect
Headerskey/value	Add custom request headers with Add header. Template variables are supported.
Query parameterskey/value	Add URL query values with Add parameter.
Authenticationselect	Choose None, Bearer token (token), Basic auth (username and password), or API-key header (header name and value). Template variables are supported in credential values.
Success status codescomma-separated	Defaults to `200, 201, 202`. A status outside the list counts as a failed step.
Retries on failurenumber	Appears only on the first step, and only when a later step is the send step. If that first step fails with a request or status error, Akedly retries it up to 3 times (default 0) before the chain fails. The send step itself is never retried, and retries still count against the 5-second chain limit.
Extract from the responsemapping	Use Add extraction to store a response value as `{{vars.name}}` for a later step. Choose JSON path, Response header, Status code, or Regex. Enter a dotted path, header name, or regex pattern as appropriate. A JSON path accepts bracket indexes for arrays (`data[0].id`) as well as dotted segments; a regex uses capture group 1 when present, otherwise the full match. Status code uses the response status.

Chain execution limits

Limits apply to the entire chain

Each request has a default 3-second timeout, and the whole chain must finish within 5 seconds.
Redirects are not followed.
Each response body is capped at 64 KB (64 KiB).
Every request must use HTTPS and resolve only to a public address; private, loopback, link-local, and other blocked IP ranges are rejected.

What's next

After you build the integration, test and activate it. An active integration does not route by itself: BYO SMS must also be enabled for the pipeline. See Enable on pipelines & cloning.