22.11. challenger-send-sms(1)

22.11.1. Name

challenger-send-sms - transmit a Challenger TAN by SMS

22.11.2. Synopsis

challenger-send-sms ADDRESS

22.11.3. Description

challenger-send-sms transmits a TAN to a mobile phone number. It is not itself an SMS sender: it validates the number, then tries each installed provider helper in turn until one of them accepts the message.

The command is not normally invoked by hand. It is named in the AUTH_COMMAND option of a [challenger] configuration section (see challenger.conf(5)), and is executed by challenger-httpd(1) whenever a TAN must be delivered. The same invocation contract is used by the Anastasis authorization plugins and by the GNU Taler merchant backend, so the helper may be executed by any of those services.

ADDRESS is the user-supplied address object, as compact JSON. The field consulted is CONTACT_PHONE, and its name derives from the enter-$ADDRESS_TYPE-form template on the Challenger side; an address object without that field is rejected.

The message to transmit — including the TAN itself — is read from standard input. It is the MESSAGE_TEMPLATE_FILE of challenger-httpd(1) after expansion. The TAN is never passed on the command line, so that it does not appear in the process table.

Standard error is inherited from the invoking daemon and is used for diagnostics.

Before contacting any provider, the number is checked against the general E.164 form: a leading + followed by 7 to 15 digits. This is deliberately a generic check. It rejects grossly malformed input such as +41 without consulting a provider, but it cannot enforce per-country lengths, so a number that is merely one digit short or long, or that has a transposed digit, is passed on and will be reported by whichever provider first classifies it.

Providers are resolved by name from the directory holding challenger-send-sms itself, as challenger-send-sms-PROVIDER, and are tried in the order telesign, clicksend, aspsms. A provider whose helper is absent or not executable is skipped silently.

Whether a failing provider causes the next one to be tried depends on the class of the failure. An address that one provider rejects will be rejected by all of them, so such a failure is reported immediately; a provider that is misconfigured, out of credit, rate limited or down does not prevent another provider from succeeding, so those cause a fall-through.

If every provider has been tried without success, the most actionable code seen is reported, preferring address errors, then recipient errors, then configuration errors, then provider errors.

22.11.4. Environment

challenger-send-sms itself reads no environment variables, but the provider helpers it invokes require credentials to be present in the environment of the invoking daemon. See challenger-send-sms-telesign(1), challenger-send-sms-clicksend(1) and challenger-send-sms-aspsms(1).

22.11.5. Exit Status

An exit status below 10 means the TAN was transmitted, or will be. Any other status means it was not.

0

The TAN was delivered and receipt on the handset was confirmed.

1

A provider accepted the TAN for delivery, but delivery was not confirmed within the polling window. This is a success: the message is in flight.

2

A provider suppressed the message as a duplicate, because an identical message was recently accepted for the same recipient. The earlier copy is in flight, so this too is a success.

10

The address is malformed: the CONTACT_PHONE field is missing, or its value is not of the form + followed by digits.

11

The phone number is too short.

12

The phone number is too long.

13

The number is not a mobile subscription. Reported only on a best-effort basis; most providers cannot make this distinction.

14

The number is syntactically plausible but unallocated, or the subscriber is unknown. This is the status reported for a number with a missing, extra or transposed digit that the local check cannot catch.

15

Delivery to this number is blocked, barred, or the number is on a blocklist.

20

The handset is switched off or out of coverage.

21

The message expired before it could be delivered to the handset.

22

The mobile operator or an intermediate carrier failed.

30

The SMS provider is down or reported an internal error.

31

The SMS provider rejected the request.

32

A provider rate limit was exceeded.

33

No verdict: the outcome of the submission could not be determined.

40

Local configuration or invocation error: a required credential is absent from the environment, or the helper was called with the wrong arguments.

41

A provider refused the configured credentials.

42

A provider account has insufficient balance. All supported providers are pre-paid.

50

The transmission failed for a reason that could not be classified.

22.11.6. See Also

challenger-send-sms-aspsms(1), challenger-send-sms-clicksend(1), challenger-send-sms-telesign(1), challenger-send-email(1), challenger-send-post(1), challenger-httpd(1), challenger.conf(5).

22.11.7. Bugs

Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>.