taler-docs

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

challenger-send-sms-clicksend.1.rst (4614B)

      1 challenger-send-sms-clicksend(1)
      2 ################################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **challenger-send-sms-clicksend** - transmit a Challenger TAN by SMS via ClickSend
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **challenger-send-sms-clicksend** *PHONE_NUMBER*
     16 
     17 
     18 Description
     19 ===========
     20 
     21 **challenger-send-sms-clicksend** transmits a TAN to a mobile phone number using
     22 the ClickSend v3 SMS 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 ClickSend reports per-message outcomes in the response body rather than in the
     31 HTTP status, and its documentation states explicitly that the HTTP status does
     32 not reflect the status of an individual message. A successful submission
     33 therefore only means the message was **queued**; delivery is confirmed
     34 separately by polling, for a bounded period. A message still in flight when the
     35 polling window closes is reported as accepted, not as a failure.
     36 
     37 ClickSend validates the number format and prefix before submitting to the
     38 network. A number failing either check is reported immediately, is never sent,
     39 and is not charged for. This makes ClickSend the most reliable of the
     40 configured providers for detecting an unusable number, though it does not
     41 distinguish a number that is too short from one that is too long.
     42 
     43 ClickSend suppresses a message whose body is identical to one recently sent to
     44 the same recipient. Because the suppressed message is by definition identical to
     45 one already accepted, the TAN will still reach the user, and this is reported as
     46 a success.
     47 
     48 Delivery failures are all reported under a single status code, with the
     49 distinguishing information carried only in accompanying free text whose wording
     50 ClickSend does not guarantee to be stable. A failure whose text is not
     51 recognised is therefore reported as unclassified rather than guessed at.
     52 
     53 
     54 Environment
     55 ===========
     56 
     57 **CLICKSEND_USERNAME**
     58    ClickSend account username. Required.
     59 
     60 **CLICKSEND_API_KEY**
     61    ClickSend API key. Required.
     62 
     63 The helper fails with status 40 if either is unset or empty. Credentials are
     64 taken from the environment of the invoking daemon, never from a configuration
     65 file.
     66 
     67 
     68 Exit Status
     69 ===========
     70 
     71 An exit status of 0, or in the 200 to 210 band, means the TAN was
     72 transmitted, or will be. Any other status means it was not. The success
     73 band starts at 200 rather than at 1 because GNUnet reports a helper it
     74 could not execute as exit status 1, which must not be mistaken for a
     75 delivery. The subset below is what this helper can actually
     76 report; see challenger-send-sms(1) for the full table.
     77 
     78 **0**
     79    Delivery to the handset was confirmed.
     80 
     81 **201**
     82    ClickSend queued the message but delivery was not confirmed within the
     83    polling window.
     84 
     85 **202**
     86    The message was suppressed as a duplicate of one recently sent to the same
     87    recipient. The earlier copy carries the same TAN and is in flight.
     88 
     89 **14**
     90    The number is invalid: it failed ClickSend's format or prefix check, or the
     91    network reported an unknown, unidentified or illegal subscriber.
     92 
     93 **15**
     94    The message was blocked: stopped by ClickSend's compliance review, rejected
     95    by a network anti-spam filter, or sent to a country or sender identity not
     96    enabled on the account.
     97 
     98 **20**
     99    The subscriber is absent, or the handset has insufficient memory to accept
    100    the message.
    101 
    102 **21**
    103    The delivery receipt expired before a final status was reported.
    104 
    105 **22**
    106    The recipient network rejected the message, was congested, timed out, or
    107    could not route it.
    108 
    109 **30**
    110    ClickSend is unavailable or reported an internal error.
    111 
    112 **31**
    113    ClickSend rejected the request as malformed or incomplete.
    114 
    115 **32**
    116    A ClickSend rate limit was exceeded.
    117 
    118 **40**
    119    **CLICKSEND_USERNAME** or **CLICKSEND_API_KEY** is not set, or the helper was
    120    invoked with the wrong number of arguments.
    121 
    122 **41**
    123    ClickSend refused the credentials, or the account is not activated.
    124 
    125 **42**
    126    The ClickSend account is out of message credits.
    127 
    128 **50**
    129    Delivery failed for a reason ClickSend did not report in a form that could be
    130    classified.
    131 
    132 
    133 See Also
    134 ========
    135 
    136 challenger-send-sms(1), challenger-send-sms-aspsms(1),
    137 challenger-send-sms-telesign(1), 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>.