taler-docs

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

challenger-send-sms-budgetsms.1.rst (6191B)


      1 challenger-send-sms-budgetsms(1)
      2 ################################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **challenger-send-sms-budgetsms** - transmit a Challenger TAN by SMS via BudgetSMS
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **challenger-send-sms-budgetsms** *PHONE_NUMBER*
     16 
     17 
     18 Description
     19 ===========
     20 
     21 **challenger-send-sms-budgetsms** transmits a TAN to a mobile phone number
     22 using the BudgetSMS 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 Unlike the other provider helpers, this API returns no JSON. Every call answers
     31 with a single line, either ``OK`` followed by a value or ``ERR`` followed by a
     32 numeric error code, always with HTTP status 200. A successful submission
     33 returns the identifier of the message and means only that BudgetSMS handed the
     34 message to one of its uplinks; it already deducts credit, while a submission
     35 reported as an error does not. Delivery is confirmed separately by polling the
     36 delivery status for that identifier, for a bounded period. A message still in
     37 flight when the polling window closes is reported as accepted, not as a
     38 failure.
     39 
     40 The error codes returned at submission are the most detailed of any configured
     41 provider for the shape of the number: a number that is too short, one that is
     42 not numeric or formatted invalidly, and one that is simply invalid as a
     43 destination are distinguished from each other. There is no code for a number
     44 that is too long.
     45 
     46 **The delivery statuses carry no reason code.** The status for a failed
     47 delivery says only that delivery failed, so it is reported as unclassified
     48 rather than guessed at as a bad number, which also lets the dispatcher try the
     49 next provider. The statuses that mean the outcome is unknown are only reachable
     50 24 to 72 hours after sending and thus never within the polling window.
     51 
     52 This API requires a sender identity on every message, so this helper always
     53 sends one, ``Challenger`` unless **BUDGETSMS_SENDER** below says otherwise.
     54 
     55 
     56 Environment
     57 ===========
     58 
     59 **BUDGETSMS_USERNAME**
     60    BudgetSMS account username. Required.
     61 
     62 **BUDGETSMS_USERID**
     63    Numeric BudgetSMS user id. Required. The helper fails with status 40 if the
     64    value is not a sequence of digits, as it is used to build the request URL.
     65 
     66 **BUDGETSMS_HANDLE**
     67    BudgetSMS API handle, the account's API credential. Required.
     68 
     69 **BUDGETSMS_SENDER**
     70    Sender identity to show on the message, at most 11 alphanumeric or 16
     71    numeric characters. Optional, defaults to ``Challenger``. An alphanumeric
     72    sender must be pre-registered with the operator in several countries; where
     73    that applies, configure a sender the operator accepts, or a numeric one.
     74 
     75 The helper fails with status 40 if any of the three required variables is unset
     76 or empty. Credentials are taken from the environment of the invoking daemon,
     77 never from a configuration file.
     78 
     79 
     80 Exit Status
     81 ===========
     82 
     83 An exit status of 0, or in the 200 to 210 band, means the TAN was
     84 transmitted, or will be. Any other status means it was not. The success
     85 band starts at 200 rather than at 1 because GNUnet reports a helper it
     86 could not execute as exit status 1, which must not be mistaken for a
     87 delivery. The subset below is what this helper can actually
     88 report; see challenger-send-sms(1) for the full table.
     89 
     90 **0**
     91    Delivery to the handset was confirmed.
     92 
     93 **201**
     94    BudgetSMS accepted the message but delivery was not confirmed within the
     95    polling window, including the case of a message that has been sent but not
     96    yet acknowledged by the handset.
     97 
     98 **10**
     99    The destination is not numeric, is empty, or is formatted invalidly.
    100 
    101 **11**
    102    The destination number is too short.
    103 
    104 **14**
    105    The destination is invalid: either rejected as such at submission, or
    106    reported as an invalid destination address in the delivery status.
    107 
    108 **15**
    109    The message was not allowed to the destination.
    110 
    111 **21**
    112    The message expired before it could be delivered.
    113 
    114 **22**
    115    The service centre could not process the message, or the route reported a
    116    wrong operator for the destination.
    117 
    118 **30**
    119    BudgetSMS is unavailable or timed out, there is no route to the destination,
    120    the gateway is unreachable, a system error occurred, or the message was
    121    never sent.
    122 
    123 **31**
    124    BudgetSMS rejected the request, for instance because the message identifier
    125    used for the delivery query was invalid or a custom identifier had already
    126    been used.
    127 
    128 **32**
    129    BudgetSMS answered with a rate-limit HTTP status.
    130 
    131 **40**
    132    **BUDGETSMS_USERNAME**, **BUDGETSMS_USERID** or **BUDGETSMS_HANDLE** is not
    133    set or empty, **BUDGETSMS_USERID** is not numeric, the helper was invoked
    134    with the wrong number of arguments, or BudgetSMS rejected a parameter of the
    135    request such as an empty or over-long message, an unacceptable sender, a
    136    character-set problem, or an account without a route set up.
    137 
    138 **41**
    139    BudgetSMS refused the credentials, the account is not active, or the request
    140    came from an IP address that is not registered for the account.
    141 
    142 **42**
    143    The pre-paid BudgetSMS account has insufficient credits to send messages.
    144 
    145 **50**
    146    Delivery failed with no reason given, or BudgetSMS reported an unknown error
    147    or a code that could not be classified.
    148 
    149 BudgetSMS has no error code for a number that is too long, so status 12 is
    150 never reported; none that means an identical message is already in flight, so
    151 status 202 is never reported; and neither its error codes nor its delivery
    152 statuses distinguish a non-mobile subscription from an unreachable handset, so
    153 status 13 and 20 are never reported either.
    154 
    155 
    156 See Also
    157 ========
    158 
    159 challenger-send-sms(1), challenger-send-sms-seven(1),
    160 challenger-send-sms-gatewayapi(1), challenger-send-sms-aspsms(1),
    161 challenger-send-sms-clicksend(1), challenger-send-sms-telesign(1),
    162 challenger-httpd(1), challenger.conf(5).
    163 
    164 
    165 Bugs
    166 ====
    167 
    168 Report bugs by using https://bugs.taler.net or by sending electronic
    169 mail to <taler@gnu.org>.