Next File Manager 6.1.0: share links, Trash, a phone app and a Health check Next Exams 6.3.0: exam parts, scaled scores, listening and speaking tests Next Restaurant 6.1.0: move your data in, run payroll, and connect other systems Next Inventory 6.2.0: a REST API and webhooks for your other systems Next DB 6.1: Auto-Updating Tables, Printing, Phone Layout and SEO Next Task 6.0.0: a task manager for Joomla
NextSoftware

HTTP SMS gateway

Sends the text messages of your automations through any SMS provider with a simple HTTP API: you describe the provider's send request once, and every text goes out through it.

Use it for a provider without its own plugin. For Twilio, use the Twilio gateway.


How it works

  1. An automation's SMS action fires and puts the text in the outbox.
  2. The Send queued emails task sends it: your site calls the provider's address with the body you set up, the guest's number, the text and the sender filled in.
  3. A 2xx answer counts as sent (or, with a Success text, only an answer that contains it). If the answer is JSON with an id, the id is kept.
  4. Timeouts, network errors, HTTP 408, 429 and 5xx answers are tried again. Redirects and other 4xx answers are not: no retry would fix them.

The request waits at most 10 seconds for an answer.


Setting it up

1. Switch on SMS

Open Configure > Apps, switch on SMS and check that the HTTP gateway app is on. Configure > SMS gateways then appears in the menu.

2. Read your provider's API documentation

Find the provider's send address, whether it takes a form or JSON body, the names of its fields for the number, the text and the sender, and how the API key is passed (a header or a field).

3. Add the profile

On Configure > SMS gateways, click Add profile and choose HTTP gateway as the Provider. Then fill in:

Field Value
Address The provider's send address, for example https://api.example.com/sms/send. Only http and https on the standard ports, only public internet addresses, never your own network. Redirects are not followed, so enter the final address
Method POST sends the body as the request body. GET adds it to the address as a query string
Body format For POST: Form (application/x-www-form-urlencoded) or JSON (application/json), as the provider asks
Body template The request with the placeholders (see below). Empty: the example for the chosen format
Sender What {from} becomes: your sender number or name, as the provider expects it (optional)
Header name One extra request header, usually for the API key, for example Authorization or X-API-Key (optional)
Header value The header's value, for example Bearer followed by your API key. Never written to a log or kept in an error message
Success text For providers that answer 200 OK even when they refuse a message: a text their answer always contains when a message is accepted, for example "status":"sent" or OK. Empty: any 2xx answer counts as sent
Test mode On: no request is made. Each message is written to the Joomla log (address query, body and header value hidden) and counted as sent

Publish the profile, save it, and click Make default if it should send every text. Set the Default country code on the same page for numbers typed without one.

Placeholders

Placeholder Becomes
{to} The recipient's number in international format, for example +447700900123
{text} The message
{from} The Sender field

Each value is encoded for where it lands:

  • Form and GET: write the template as a query string. Values are URL-encoded for you.

    to={to}&text={text}&from={from}
  • JSON: put each placeholder inside quotes. Values are JSON-escaped for you, without the quotes.

    {"to":"{to}","text":"{text}","from":"{from}"}

An API key can also sit in the template, for example api_key=abc123&to={to}&text={text}. It is never written to a log.

Headers your site sets itself (such as Host, Content-Type and Content-Length) cannot be used as the extra header.


Test it

  1. Turn Test mode on, type your number under Phone number and click Send test SMS. The answer is "Test mode is on: nothing was sent." and the outline of the request is in the Joomla log.
  2. Turn Test mode off and send again. "The gateway accepted the message (...)" means a 2xx answer (with your success text, if set). Check that the text arrives on your phone.
  3. If the provider says it refused the message but the test reports success, set a Success text.

Several profiles and "Send through"

Add as many profiles as you need, on one provider or several. The default profile sends every text; an automation's SMS action can pick another one under Send through. A profile that is switched off falls back to the default.


Troubleshooting

Symptom Cause and fix
The address is refused It is not http or https on port 80 or 443, or it points to a private network address. Use the provider's public address
"Redirects are not followed" or a 3xx answer Enter the final address the provider documents, often with https:// or a different host
401 or 403 The API key is wrong or in the wrong place: header or body, as the provider documents
400 or 422 The field names in the Body template do not match the provider's, or the format (form or JSON) is wrong
The test reports success but nothing arrives The provider answers 200 OK on refusal. Set a Success text
Texts counted as sent but nobody gets them Test mode is on
Special characters arrive broken in JSON Keep each placeholder inside quotes: "{text}"

See also

All Extensions