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>.