taler-docs

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

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


      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 **ASPSMS_SENDER**
     58    Sender identity to show on the message (ASPSMS's ``Originator``), at most 11
     59    alphanumeric or 16 numeric characters. Optional; if it is unset or empty,
     60    the sender is ``Challenger``. An alphanumeric sender must be pre-registered
     61    with the operator in several countries; where that applies, configure a
     62    sender the operator accepts, or a numeric one.
     63 
     64 The helper fails with status 40 if either of the two required variables is
     65 unset or empty. Credentials are taken from the environment of the invoking
     66 daemon, never from a configuration file.
     67 
     68 
     69 Exit Status
     70 ===========
     71 
     72 An exit status of 0, or in the 200 to 210 band, means the TAN was
     73 transmitted, or will be. Any other status means it was not. The success
     74 band starts at 200 rather than at 1 because GNUnet reports a helper it
     75 could not execute as exit status 1, which must not be mistaken for a
     76 delivery. The subset below is what this helper can actually
     77 report; see challenger-send-sms(1) for the full table.
     78 
     79 **0**
     80    Delivery to the handset was confirmed.
     81 
     82 **201**
     83    ASPSMS accepted the message but delivery was not confirmed within the polling
     84    window, including the common case of a message still buffered for a handset
     85    that is switched off.
     86 
     87 **13**
     88    The destination is not equipped for SMS, is not a subscriber, or the facility
     89    is not supported or not provided by the network.
     90 
     91 **14**
     92    The subscriber is unknown, or the destination address is invalid.
     93 
     94 **15**
     95    The number is barred, either for calls or for the requested operation.
     96 
     97 **20**
     98    The subscriber is absent: the handset is switched off or out of coverage.
     99 
    100 **21**
    101    The message expired after the network gave up retrying delivery.
    102 
    103 **22**
    104    A mobile network component failed, or a service centre was congested.
    105 
    106 **30**
    107    ASPSMS is unavailable, timed out, or reported a transmission error.
    108 
    109 **31**
    110    ASPSMS rejected the request, for instance because the message exceeded the
    111    maximum length or a parameter was invalid.
    112 
    113 **40**
    114    **ASPSMS_USERKEY** or **ASPSMS_PASSWORD** is not set, or the helper was
    115    invoked with the wrong number of arguments.
    116 
    117 **41**
    118    ASPSMS refused the credentials, denied access to the account, or the
    119    configured originator is not authorized.
    120 
    121 **42**
    122    The pre-paid ASPSMS account has insufficient credits.
    123 
    124 **50**
    125    The delivery report carried a reason code that could not be classified.
    126 
    127 ASPSMS documents no rate limit and no rate-limit code, so status 32 is never
    128 reported by this helper.
    129 
    130 
    131 See Also
    132 ========
    133 
    134 challenger-send-sms(1), challenger-send-sms-clicksend(1),
    135 challenger-send-sms-telesign(1), challenger-send-sms-seven(1),
    136 challenger-send-sms-gatewayapi(1), challenger-send-sms-budgetsms(1),
    137 challenger-httpd(1), challenger.conf(5).
    138 
    139 
    140 Bugs
    141 ====
    142 
    143 Report bugs by using https://bugs.taler.net or by sending electronic
    144 mail to <taler@gnu.org>.