taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

challenger-send-sms-seven.1.rst (5989B)


      1 challenger-send-sms-seven(1)
      2 ############################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **challenger-send-sms-seven** - transmit a Challenger TAN by SMS via seven.io
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **challenger-send-sms-seven** *PHONE_NUMBER*
     16 
     17 
     18 Description
     19 ===========
     20 
     21 **challenger-send-sms-seven** transmits a TAN to a mobile phone number using
     22 the seven.io REST/HTTP API.
     23 
     24 It is normally invoked by challenger-send-sms(1) as one provider in a fallback
     25 chain, and not directly. Its calling convention differs from that of the
     26 dispatcher: *PHONE_NUMBER* is the **bare phone number**, already extracted from
     27 the address object and already checked for general E.164 form. The message to
     28 transmit, including the TAN, is read from **standard input**.
     29 
     30 seven.io answers with HTTP 200 even for an authentication failure and reports
     31 the outcome in the ``success`` field of the response body, which carries a
     32 numeric return code. A submission that is accepted only means the gateway took
     33 the message; delivery is confirmed separately by polling the outbound logbook
     34 for the returned message id, for a bounded period. A message still in flight
     35 when the polling window closes is reported as accepted, not as a failure.
     36 
     37 A single bad-number code covers every unusable recipient, so a number that is
     38 malformed, too short, too long or unallocated cannot be distinguished at
     39 submission time.
     40 
     41 seven.io blocks a message whose text and recipient are identical to one
     42 accepted within the previous three minutes. Because the suppressed message is by
     43 definition identical to one already accepted, the TAN will still reach the user,
     44 and this is reported as a success. Note that a deployment may switch this block
     45 off in its seven.io account settings, in which case duplicates are charged for
     46 and this helper never reports that status. The provider also enforces a daily
     47 cap per recipient number; since another provider keeps its own counter, that is
     48 reported as a rate limit rather than as a problem with the number.
     49 
     50 **The delivery report carries no reason code**, only a status word. A confirmed
     51 non-delivery for which the status word itself names no cause is therefore
     52 reported as unclassified rather than guessed at as a bad number, which also
     53 lets the dispatcher try the next provider.
     54 
     55 The logbook entry returned while polling echoes the message text, and hence the
     56 TAN, back to the helper. Like every Challenger helper, this one writes status
     57 diagnostics rather than provider responses to standard error, so the TAN does
     58 not reach the log of the invoking daemon.
     59 
     60 
     61 Environment
     62 ===========
     63 
     64 **SEVEN_API_KEY**
     65    API key for the seven.io REST/HTTP API, as created in the developer area of
     66    the seven.io dashboard. Required. The helper fails with status 40 if it is
     67    unset or empty, or if it contains a line break, as the key is sent in an
     68    HTTP header.
     69 
     70 **SEVEN_SENDER**
     71    Sender identity to show on the message, at most 11 alphanumeric or 16
     72    numeric characters. Optional; if it is unset or empty, the sender is
     73    ``Taler Ops``. An alphanumeric sender must be pre-registered with the
     74    operator in several countries, and a sender the operator does not accept
     75    fails every message; where that applies, configure a sender the operator
     76    accepts, or a numeric one.
     77 
     78 Credentials are taken from the environment of the invoking daemon, never from a
     79 configuration file.
     80 
     81 
     82 Exit Status
     83 ===========
     84 
     85 An exit status of 0, or in the 200 to 210 band, means the TAN was
     86 transmitted, or will be. Any other status means it was not. The success
     87 band starts at 200 rather than at 1 because GNUnet reports a helper it
     88 could not execute as exit status 1, which must not be mistaken for a
     89 delivery. The subset below is what this helper can actually
     90 report; see challenger-send-sms(1) for the full table.
     91 
     92 **0**
     93    Delivery to the handset was confirmed.
     94 
     95 **201**
     96    seven.io accepted the message but delivery was not confirmed within the
     97    polling window, including the case of a message buffered for a handset that
     98    is switched off.
     99 
    100 **202**
    101    The message was suppressed as a duplicate of one accepted for the same
    102    recipient within the previous three minutes. The earlier copy carries the
    103    same TAN and is in flight.
    104 
    105 **14**
    106    The recipient number was rejected by the gateway. This one code covers a
    107    malformed, too short, too long or unallocated number alike.
    108 
    109 **21**
    110    The message was not delivered before its validity period expired.
    111 
    112 **22**
    113    The network operator rejected the message.
    114 
    115 **30**
    116    seven.io is unavailable, timed out, or reported an error while sending.
    117 
    118 **31**
    119    seven.io answered with something other than one of its documented return
    120    codes, together with a client-error HTTP status.
    121 
    122 **32**
    123    The daily limit for this recipient number has been reached.
    124 
    125 **40**
    126    **SEVEN_API_KEY** is not set, is empty, or contains a line break; the helper
    127    was invoked with the wrong number of arguments; or the gateway rejected a
    128    parameter of the request, such as the configured sender, a message that is
    129    too long, or a parameter it does not support.
    130 
    131 **41**
    132    seven.io refused the API key, the key has no access to the endpoint, or the
    133    request came from an IP address that is not on the account's permitted list.
    134 
    135 **42**
    136    The pre-paid seven.io account has insufficient credit to send the message.
    137 
    138 **50**
    139    The message was reported as not delivered, with no reason given, or the
    140    gateway reported a return code that could not be classified.
    141 
    142 Because the delivery report has no reason code, this helper never reports
    143 status 13, 15 or 20, and the single bad-number code means it never reports
    144 status 11 or 12.
    145 
    146 
    147 See Also
    148 ========
    149 
    150 challenger-send-sms(1), challenger-send-sms-gatewayapi(1),
    151 challenger-send-sms-budgetsms(1), challenger-send-sms-aspsms(1),
    152 challenger-send-sms-clicksend(1), challenger-send-sms-telesign(1),
    153 challenger-httpd(1), challenger.conf(5).
    154 
    155 
    156 Bugs
    157 ====
    158 
    159 Report bugs by using https://bugs.taler.net or by sending electronic
    160 mail to <taler@gnu.org>.