taler-docs

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

challenger-send-sms-telesign.1.rst (3978B)

      1 challenger-send-sms-telesign(1)
      2 ###############################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **challenger-send-sms-telesign** - transmit a Challenger TAN by SMS via Telesign
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **challenger-send-sms-telesign** *PHONE_NUMBER*
     16 
     17 
     18 Description
     19 ===========
     20 
     21 **challenger-send-sms-telesign** transmits a TAN to a mobile phone number using
     22 the Telesign Messaging 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 The message is submitted to the Telesign messaging endpoint. Telesign accepts a
     31 message for delivery without confirming that it reached the handset, so the
     32 delivery status is then polled for a bounded period. A message still in flight
     33 when the polling window closes is reported as accepted, not as a failure.
     34 
     35 Telesign reports the outcome in the ``status.code`` field of the response body,
     36 for successful and unsuccessful requests alike, and its documentation directs
     37 callers to use that field in preference to the HTTP status. A malformed number
     38 is reported as ``11000`` with an HTTP status of 400, so the response body must
     39 be retained even when the HTTP request is unsuccessful.
     40 
     41 Telesign does not distinguish a number that is too short from one that is too
     42 long; both are reported as ``11000``. Detecting that a number belongs to a
     43 landline or VoIP service requires Telesign's separate PhoneID product and is not
     44 attempted here.
     45 
     46 
     47 Environment
     48 ===========
     49 
     50 **TELESIGN_AUTH_TOKEN**
     51    Basic authentication token for the Telesign REST API. Required. The helper
     52    fails with status 40 if it is unset or empty.
     53 
     54 Credentials are taken from the environment of the invoking daemon, never from a
     55 configuration file.
     56 
     57 
     58 Exit Status
     59 ===========
     60 
     61 An exit status of 0, or in the 200 to 210 band, means the TAN was
     62 transmitted, or will be. Any other status means it was not. The success
     63 band starts at 200 rather than at 1 because GNUnet reports a helper it
     64 could not execute as exit status 1, which must not be mistaken for a
     65 delivery. The subset below is what this helper can actually
     66 report; see challenger-send-sms(1) for the full table.
     67 
     68 **0**
     69    Delivery to the handset was confirmed.
     70 
     71 **201**
     72    Telesign accepted the message but delivery was not confirmed within the
     73    polling window, or Telesign reported that the final status is unknown.
     74 
     75 **13**
     76    SMS is not supported by this phone, carrier or subscription.
     77 
     78 **14**
     79    The number is invalid, unallocated, or the subscriber is unknown.
     80 
     81 **15**
     82    The message was blocked: by a rule configured on the Telesign account, by
     83    Telesign's global blocklist, by a carrier spam filter, or by the subscriber.
     84 
     85 **20**
     86    The subscriber is absent: the handset is switched off, out of coverage, or
     87    roaming.
     88 
     89 **21**
     90    The message expired in the mobile provider's queue before delivery.
     91 
     92 **22**
     93    The carrier or mobile operator rejected the message or failed.
     94 
     95 **30**
     96    Telesign, or a Telesign delivery partner, is unavailable or reported an
     97    internal error.
     98 
     99 **31**
    100    Telesign rejected the request as malformed or unsupported.
    101 
    102 **32**
    103    A Telesign rate limit or transaction cap was exceeded.
    104 
    105 **40**
    106    **TELESIGN_AUTH_TOKEN** is not set, or the helper was invoked with the wrong
    107    number of arguments.
    108 
    109 **41**
    110    Telesign refused the credentials, or the account is suspended.
    111 
    112 **42**
    113    The pre-paid Telesign wallet has insufficient funds.
    114 
    115 **50**
    116    Telesign reported a status that could not be classified.
    117 
    118 
    119 See Also
    120 ========
    121 
    122 challenger-send-sms(1), challenger-send-sms-aspsms(1),
    123 challenger-send-sms-clicksend(1), challenger-httpd(1), challenger.conf(5).
    124 
    125 
    126 Bugs
    127 ====
    128 
    129 Report bugs by using https://bugs.taler.net or by sending electronic
    130 mail to <taler@gnu.org>.