22.9. challenger-send-sms-clicksend(1)

22.9.1. Name

challenger-send-sms-clicksend - transmit a Challenger TAN by SMS via ClickSend

22.9.2. Synopsis

challenger-send-sms-clicksend PHONE_NUMBER

22.9.3. Description

challenger-send-sms-clicksend transmits a TAN to a mobile phone number using the ClickSend v3 SMS API.

It is normally invoked by challenger-send-sms(1) as one provider in a fallback chain, and not directly. Its calling convention differs from that of the dispatcher: PHONE_NUMBER is the bare phone number, already extracted from the address object and already checked for general E.164 form. The message to transmit, including the TAN, is read from standard input.

ClickSend reports per-message outcomes in the response body rather than in the HTTP status, and its documentation states explicitly that the HTTP status does not reflect the status of an individual message. A successful submission therefore only means the message was queued; delivery is confirmed separately by polling, for a bounded period. A message still in flight when the polling window closes is reported as accepted, not as a failure.

ClickSend validates the number format and prefix before submitting to the network. A number failing either check is reported immediately, is never sent, and is not charged for. This makes ClickSend the most reliable of the configured providers for detecting an unusable number, though it does not distinguish a number that is too short from one that is too long.

ClickSend suppresses a message whose body is identical to one recently sent to the same recipient. Because the suppressed message is by definition identical to one already accepted, the TAN will still reach the user, and this is reported as a success.

Delivery failures are all reported under a single status code, with the distinguishing information carried only in accompanying free text whose wording ClickSend does not guarantee to be stable. A failure whose text is not recognised is therefore reported as unclassified rather than guessed at.

22.9.4. Environment

CLICKSEND_USERNAME

ClickSend account username. Required.

CLICKSEND_API_KEY

ClickSend API key. Required.

The helper fails with status 40 if either is unset or empty. Credentials are taken from the environment of the invoking daemon, never from a configuration file.

22.9.5. Exit Status

An exit status below 10 means the TAN was transmitted, or will be. Any other status means it was not. The subset below is what this helper can actually report; see challenger-send-sms(1) for the full table.

0

Delivery to the handset was confirmed.

1

ClickSend queued the message but delivery was not confirmed within the polling window.

2

The message was suppressed as a duplicate of one recently sent to the same recipient. The earlier copy carries the same TAN and is in flight.

14

The number is invalid: it failed ClickSend’s format or prefix check, or the network reported an unknown, unidentified or illegal subscriber.

15

The message was blocked: stopped by ClickSend’s compliance review, rejected by a network anti-spam filter, or sent to a country or sender identity not enabled on the account.

20

The subscriber is absent, or the handset has insufficient memory to accept the message.

21

The delivery receipt expired before a final status was reported.

22

The recipient network rejected the message, was congested, timed out, or could not route it.

30

ClickSend is unavailable or reported an internal error.

31

ClickSend rejected the request as malformed or incomplete.

32

A ClickSend rate limit was exceeded.

40

CLICKSEND_USERNAME or CLICKSEND_API_KEY is not set, or the helper was invoked with the wrong number of arguments.

41

ClickSend refused the credentials, or the account is not activated.

42

The ClickSend account is out of message credits.

50

Delivery failed for a reason ClickSend did not report in a form that could be classified.

22.9.6. See Also

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

22.9.7. Bugs

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