Akedly

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.

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.

  • Name
    Name
    Type
    string · required
    Description

    The integration name shown in the registry and in verification history entries that used it.

  • Name
    Description
    Type
    string · optional
    Description

    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.

  • Name
    Send to all countries
    Type
    toggle
    Description

    Turn on for catch-all coverage — the integration can serve any destination country. Turn off to select specific countries.

  • Name
    Countries
    Type
    searchable picker
    Description

    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.

  • Name
    If your API fails
    Type
    select
    Description

    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.

  • Name
    Secret name
    Type
    string
    Description

    A stable name for the credential, such as apiToken.

  • Name
    Secret reference
    Type
    template
    Description

    Reference the credential anywhere in a step as {{secrets.name}}, replacing name with the stored secret name.

  • Name
    Add secret
    Type
    button
    Description

    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.

  • Name
    Step name
    Type
    string · optional
    Description

    A label that describes the request, such as Get auth token or Send SMS.

  • Name
    Request
    Type
    method + URL
    Description

    Select the HTTP method and enter the provider's HTTPS URL.

  • Name
    Body format
    Type
    select
    Description

    Choose how the request body is encoded: JSON, Form-encoded, Raw text, or No body.

  • Name
    Body fields
    Type
    editor
    Description

    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.

  • Name
    Send step
    Type
    radio
    Description

    Marks the one request whose success means the SMS was accepted.

  • Name
    Add step
    Type
    button
    Description

    Appends another request to the chain.

Template variables

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

VariableValue
{{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.

  • Name
    Headers
    Type
    key/value
    Description

    Add custom request headers with Add header. Template variables are supported.

  • Name
    Query parameters
    Type
    key/value
    Description

    Add URL query values with Add parameter.

  • Name
    Authentication
    Type
    select
    Description

    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.

  • Name
    Success status codes
    Type
    comma-separated
    Description

    Defaults to 200, 201, 202. A status outside the list counts as a failed step.

  • Name
    Retries on failure
    Type
    number
    Description

    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.

  • Name
    Extract from the response
    Type
    mapping
    Description

    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.

Was this page helpful?