Custom Gateway Setup

WSMS lets you integrate any HTTP-based SMS provider that is not in the built-in gateway library. The Custom gateway supports both flat key-value APIs (?to=...&message=...) and modern Postman-style JSON APIs (with nested objects or arrays such as recipients: ["+31..."]).

Step 1: Select the Custom Gateway

1. Go to WSMS → Settings → Gateway
2. From the gateway dropdown, select Custom
3. The provider-specific fields below appear once Custom is selected

Step 2: Send SMS API URL

Enter the full endpoint URL the provider gave you, for example:

https://api.example.com/v1/send

Step 3: HTTP Headers

Add one Header-Name: value per line. Most JSON APIs need a content type and an authorization token:

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

Header lines are kept exactly as written. Make sure each header is on its own line and includes the full prefix (Bearer , Basic , Token , etc.) the provider expects.

Step 4: Body Format

Choose how WSMS builds the request body:

Mode	Use when
Key-Value	The provider accepts flat key=value parameters, either as a query string or as a simple JSON body
Raw JSON	The provider expects a Postman-style JSON payload, especially with nested objects or arrays like recipients: ["+31..."]

The fields shown below depend on the mode you pick.

Step 5a: Configure Key-Value Mode

In HTTP Parameters, list one key:value per line. WSMS replaces the placeholders below with the actual values at send time:

Placeholder	Replaced with
{from}	Sender ID configured under Sender Name
{to}	Recipient phone number(s), comma-separated
{message}	The SMS text

Example:

to:{to}
message:{message}
sender:{from}

Sending a value as a JSON array. Wrap the value in square brackets to send it as a JSON array (split by comma, trimmed):

recipients:[{to}]
tags:[otp,verify]

Send As POST. Set to Yes to send the parameters as a JSON body, or No to append them to the URL as query parameters (GET).

Step 5b: Configure Raw JSON Mode

In Request Body (JSON), paste the full JSON payload exactly as the provider documents it. WSMS replaces these placeholders inside the payload at send time:

Placeholder	Replaced with
{from}	Sender ID configured under Sender Name
{to}	Recipient phone number(s), comma-separated string
{message}	The SMS text (JSON-escaped)
{recipients}	Recipient phone number(s) as a comma-separated list of JSON strings, ready to drop inside an array

Any other keys in the JSON pass through untouched, so you can add provider-specific fields (route, callback_url, reference, etc.).

Example payload for an API that requires a recipients array:

{
  "body": "{message}",
  "originator": "{from}",
  "recipients": [{recipients}],
  "route": "business",
  "reference": "wsms-order-42"
}

Raw JSON mode always sends as POST. The Send As POST toggle does not apply.

Step 6: Encode Message

Setting	Use when
No (recommended for JSON APIs)	The provider accepts the message as plain text. Spaces, colons, and Unicode pass through untouched
Yes	The provider is a legacy GET / form-encoded endpoint that expects the message to be URL-encoded

If you turn this on with a JSON API, the SMS body arrives URL-encoded (spaces become +, : becomes %3A, etc.). Leave it No unless your provider explicitly requires URL-encoded message text.

Step 7: Sender Name

Enter the sender ID that should appear on the recipient’s phone. This value is used wherever you write the {from} placeholder.

Most providers enforce limits on this field. Common rules:

• Alphanumeric sender IDs: typically max 11 characters, no spaces or symbols
• Numeric sender IDs: typically max 14 digits

If the provider rejects your messages with errors like “originator must be a valid format”, check the provider’s allowed sender ID format first.

Step 8: Save and Test

1. Click Save Changes
2. Go to WSMS → Send SMS
3. Send a test message to verify the configuration

Common Issues

• The recipients must be an array - Switch Body Format to Raw JSON and use [{recipients}] inside the JSON payload, or in Key-Value mode use recipients:[{to}]
• Message arrives with + instead of spaces or %3A instead of : - Set Encode Message to No
• The originator must be a valid format - Shorten the Sender Name to the limit your provider allows (often 11 alphanumeric characters)
• Headers split incorrectly - Make sure each header is on its own line and the value includes the full prefix (e.g. Bearer before the token)

Use Cases

• Regional SMS providers not in the default list
• Private or enterprise SMS gateways
• Modern JSON / REST APIs that require nested payloads (Spryng, MessageBird, custom internal APIs)

Related

• Gateway Configuration - Standard gateway setup