taler-docs

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

challenger-send-sms-aspsms.1.rst (4181B)

      1 challenger-send-sms-aspsms(1)
      2 #############################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **challenger-send-sms-aspsms** - transmit a Challenger TAN by SMS via ASPSMS
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **challenger-send-sms-aspsms** *PHONE_NUMBER*
     16 
     17 
     18 Description
     19 ===========
     20 
     21 **challenger-send-sms-aspsms** transmits a TAN to a mobile phone number using
     22 the ASPSMS web 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 Each submission carries a generated transaction reference number, which is then
     31 used to poll the ASPSMS send log for a delivery report, for a bounded period. A
     32 message still in flight when the polling window closes is reported as accepted,
     33 not as a failure.
     34 
     35 ASPSMS accepts a message and reports errors in the body of an otherwise
     36 successful HTTP response; the integer ``ErrorCode`` field carries the outcome,
     37 and a value of 1 means success. The accompanying description text is not stable
     38 and is not used for classification.
     39 
     40 **ASPSMS has no error code for an unusable recipient number.** A malformed or
     41 unallocated number is accepted at submission, consuming a credit, and the
     42 problem is only revealed later in the delivery report as a reason code. A
     43 message to a switched-off handset may remain buffered for up to 24 hours before
     44 a final status is reported, far longer than the polling window, so such a
     45 message is reported as accepted rather than failed.
     46 
     47 
     48 Environment
     49 ===========
     50 
     51 **ASPSMS_USERKEY**
     52    ASPSMS account user key. Required.
     53 
     54 **ASPSMS_PASSWORD**
     55    ASPSMS API password. Required.
     56 
     57 The helper fails with status 40 if either is unset or empty. Credentials are
     58 taken from the environment of the invoking daemon, never from a configuration
     59 file.
     60 
     61 
     62 Exit Status
     63 ===========
     64 
     65 An exit status of 0, or in the 200 to 210 band, means the TAN was
     66 transmitted, or will be. Any other status means it was not. The success
     67 band starts at 200 rather than at 1 because GNUnet reports a helper it
     68 could not execute as exit status 1, which must not be mistaken for a
     69 delivery. The subset below is what this helper can actually
     70 report; see challenger-send-sms(1) for the full table.
     71 
     72 **0**
     73    Delivery to the handset was confirmed.
     74 
     75 **201**
     76    ASPSMS accepted the message but delivery was not confirmed within the polling
     77    window, including the common case of a message still buffered for a handset
     78    that is switched off.
     79 
     80 **13**
     81    The destination is not equipped for SMS, is not a subscriber, or the facility
     82    is not supported or not provided by the network.
     83 
     84 **14**
     85    The subscriber is unknown, or the destination address is invalid.
     86 
     87 **15**
     88    The number is barred, either for calls or for the requested operation.
     89 
     90 **20**
     91    The subscriber is absent: the handset is switched off or out of coverage.
     92 
     93 **21**
     94    The message expired after the network gave up retrying delivery.
     95 
     96 **22**
     97    A mobile network component failed, or a service centre was congested.
     98 
     99 **30**
    100    ASPSMS is unavailable, timed out, or reported a transmission error.
    101 
    102 **31**
    103    ASPSMS rejected the request, for instance because the message exceeded the
    104    maximum length or a parameter was invalid.
    105 
    106 **40**
    107    **ASPSMS_USERKEY** or **ASPSMS_PASSWORD** is not set, or the helper was
    108    invoked with the wrong number of arguments.
    109 
    110 **41**
    111    ASPSMS refused the credentials, denied access to the account, or the
    112    configured originator is not authorized.
    113 
    114 **42**
    115    The pre-paid ASPSMS account has insufficient credits.
    116 
    117 **50**
    118    The delivery report carried a reason code that could not be classified.
    119 
    120 ASPSMS documents no rate limit and no rate-limit code, so status 32 is never
    121 reported by this helper.
    122 
    123 
    124 See Also
    125 ========
    126 
    127 challenger-send-sms(1), challenger-send-sms-clicksend(1),
    128 challenger-send-sms-telesign(1), challenger-httpd(1), challenger.conf(5).
    129 
    130 
    131 Bugs
    132 ====
    133 
    134 Report bugs by using https://bugs.taler.net or by sending electronic
    135 mail to <taler@gnu.org>.