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
- An automation's SMS action fires and puts the text in the outbox.
- 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.
- 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.
- 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
- 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.
- 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.
- 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}" |