Connectors

SMS Connector

The SMS connector configures an SMS gateway for sending one-time passwords and notifications via text message. Kiwire supports any HTTP-based SMS gateway through a flexible, template-driven integration — configure the API endpoint, authentication, and message format once, and Kiwire handles OTP delivery for SMS-based login methods on the captive portal.

'alt' => 'Dashboard overview', 'caption' => 'The default Kiwire dashboard layout', 'screenshot' => true, 'class' => '', ]) Drop images into: public/assets/img/docs/{page}/{filename} --}}

Image not uploaded yet public/assets/img/docs/connector-sms/overview.png

The SMS connector configuration — API endpoint, authentication credentials, and message body template.

How It Works

When a guest selects SMS OTP as their login method on the captive portal, Kiwire generates a one-time code and calls your configured SMS gateway API to deliver it to the guest's phone number. The gateway API call is assembled using the body template and placeholder variables you configure here. Kiwire supports both GET and POST API calls to accommodate the variety of HTTP SMS gateway conventions.

Configuration Fields

Field	Description
`name`	Instance label (e.g., Twilio, Nexmo, Local SMS Gateway)
`is_active`	Enable or disable this SMS connector without losing configuration
`api_url`	The full URL of the SMS gateway API endpoint (e.g., `https://api.smsprovider.com/send`). Must be HTTPS in production environments.
`api_key`	API key or account SID for authenticating with the gateway. How this is used depends on the gateway — it may be an HTTP header, a query parameter, or part of the request body.
`api_secret`	API secret, auth token, or password paired with the API key. Stored encrypted at rest.
`sender_id`	Alphanumeric sender name or phone number shown on the recipient's device (e.g., `KiwireWiFi` or `+60123456789`). Alphanumeric sender IDs are not supported in all countries — consult your gateway provider.
`method`	HTTP method for the gateway API call: `GET` or `POST`. Most modern gateways prefer `POST` with a JSON body.
`body_template`	The request body (for POST) or query string (for GET) sent to the gateway. Supports placeholder variables — see the Placeholders section below.

Body Template Placeholders

The body_template field supports two placeholder variables that are substituted at send time:

Placeholder	Replaced with
`{{phone}}`	The recipient's phone number in international format (e.g., `+60123456789`)
`{{message}}`	The full SMS message text, including the OTP code (e.g., Your Kiwire WiFi OTP is 482917. Valid for 5 minutes.)

Template Examples

JSON POST body (most modern gateways):

{
    "to": "{{phone}}",
    "from": "KiwireWiFi",
    "message": "{{message}}"
}

GET query string (some legacy gateways):

to={{phone}}&from=KiwireWiFi&msg={{message}}&apikey={{api_key}}

If your SMS gateway uses HTTP Basic Auth or Bearer token authentication, configure the credentials in the api_key / api_secret fields and select the appropriate auth type in Advanced Configuration, rather than embedding them in the body template. This keeps credentials out of logs.

Usage in Captive Portal

Once the SMS connector is active, the SMS OTP login method becomes available to enable on captive portal journeys. When a guest selects this login method:

The guest enters their mobile phone number on the portal login page.
Kiwire generates a numeric OTP (typically 6 digits) and calls the SMS gateway API to deliver it.
The guest enters the OTP code on the portal. On success, they are authenticated and connected.

OTP codes expire after a configurable period (default 5 minutes). Each phone number can request a new OTP after a cooldown period to prevent abuse.

SMS delivery is asynchronous and subject to carrier delays, especially in areas with poor mobile coverage. The OTP expiry window is intentionally generous (5 minutes) to account for typical SMS delivery latency. For environments with reliable carrier coverage, you may reduce the expiry window for improved security.

Testing the Configuration

Click Send Test SMS after saving. Enter a mobile phone number in international format (e.g., +60123456789) and Kiwire will call the gateway API with a test message. Verify you receive the text message on the specified phone.

If the test fails, check:

API URL — ensure it is correct and reachable from the Kiwire server (run a connectivity test from the server if needed)
Credentials — verify the API key and secret against your SMS gateway dashboard
Body template — ensure it matches the exact format expected by your gateway (consult the gateway's API documentation)
Sender ID — some gateways require the sender ID to be pre-registered before it can be used

Required Permissions

view-connector-sms · edit-connector-sms