24.12. challenger-send-sms-seven(1)

24.12.1. Name

challenger-send-sms-seven - transmit a Challenger TAN by SMS via seven.io

24.12.2. Synopsis

challenger-send-sms-seven PHONE_NUMBER

24.12.3. Description

challenger-send-sms-seven transmits a TAN to a mobile phone number using the seven.io REST/HTTP 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.

seven.io answers with HTTP 200 even for an authentication failure and reports the outcome in the success field of the response body, which carries a numeric return code. A submission that is accepted only means the gateway took the message; delivery is confirmed separately by polling the outbound logbook for the returned message id, for a bounded period. A message still in flight when the polling window closes is reported as accepted, not as a failure.

A single bad-number code covers every unusable recipient, so a number that is malformed, too short, too long or unallocated cannot be distinguished at submission time.

seven.io blocks a message whose text and recipient are identical to one accepted within the previous three minutes. 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. Note that a deployment may switch this block off in its seven.io account settings, in which case duplicates are charged for and this helper never reports that status. The provider also enforces a daily cap per recipient number; since another provider keeps its own counter, that is reported as a rate limit rather than as a problem with the number.

The delivery report carries no reason code, only a status word. A confirmed non-delivery for which the status word itself names no cause is therefore reported as unclassified rather than guessed at as a bad number, which also lets the dispatcher try the next provider.

The logbook entry returned while polling echoes the message text, and hence the TAN, back to the helper. Like every Challenger helper, this one writes status diagnostics rather than provider responses to standard error, so the TAN does not reach the log of the invoking daemon.

24.12.4. Environment

SEVEN_API_KEY

API key for the seven.io REST/HTTP API, as created in the developer area of the seven.io dashboard. Required. The helper fails with status 40 if it is unset or empty, or if it contains a line break, as the key is sent in an HTTP header.

Credentials are taken from the environment of the invoking daemon, never from a configuration file.

No sender identity is configured by this helper: the account default applies. An alphanumeric sender must be pre-registered with the operator in several countries, and a sender the operator does not accept fails every message.

24.12.5. Exit Status

An exit status of 0, or in the 200 to 210 band, means the TAN was transmitted, or will be. Any other status means it was not. The success band starts at 200 rather than at 1 because GNUnet reports a helper it could not execute as exit status 1, which must not be mistaken for a delivery. 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.

201

seven.io accepted the message but delivery was not confirmed within the polling window, including the case of a message buffered for a handset that is switched off.

202

The message was suppressed as a duplicate of one accepted for the same recipient within the previous three minutes. The earlier copy carries the same TAN and is in flight.

14

The recipient number was rejected by the gateway. This one code covers a malformed, too short, too long or unallocated number alike.

21

The message was not delivered before its validity period expired.

22

The network operator rejected the message.

30

seven.io is unavailable, timed out, or reported an error while sending.

31

seven.io answered with something other than one of its documented return codes, together with a client-error HTTP status.

32

The daily limit for this recipient number has been reached.

40

SEVEN_API_KEY is not set, is empty, or contains a line break; the helper was invoked with the wrong number of arguments; or the gateway rejected a parameter of the request, such as the configured sender, a message that is too long, or a parameter it does not support.

41

seven.io refused the API key, the key has no access to the endpoint, or the request came from an IP address that is not on the account’s permitted list.

42

The pre-paid seven.io account has insufficient credit to send the message.

50

The message was reported as not delivered, with no reason given, or the gateway reported a return code that could not be classified.

Because the delivery report has no reason code, this helper never reports status 13, 15 or 20, and the single bad-number code means it never reports status 11 or 12.

24.12.6. See Also

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

24.12.7. Bugs

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