challenger-send-sms-budgetsms.1.rst (6209B)
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 unlike the other 53 helpers this one sends a default sender that can be overridden; see 54 **BUDGETSMS_SENDER** below. 55 56 57 Environment 58 =========== 59 60 **BUDGETSMS_USERNAME** 61 BudgetSMS account username. Required. 62 63 **BUDGETSMS_USERID** 64 Numeric BudgetSMS user id. Required. The helper fails with status 40 if the 65 value is not a sequence of digits, as it is used to build the request URL. 66 67 **BUDGETSMS_HANDLE** 68 BudgetSMS API handle, the account's API credential. Required. 69 70 **BUDGETSMS_SENDER** 71 Sender identity to show on the message, at most 11 alphanumeric or 16 72 numeric characters. Optional, defaults to ``Challenger``. An alphanumeric 73 sender must be pre-registered with the operator in several countries; where 74 that applies, configure a sender the operator accepts, or a numeric one. 75 76 The helper fails with status 40 if any of the three required variables is unset 77 or empty. Credentials are taken from the environment of the invoking daemon, 78 never from a configuration file. 79 80 81 Exit Status 82 =========== 83 84 An exit status of 0, or in the 200 to 210 band, means the TAN was 85 transmitted, or will be. Any other status means it was not. The success 86 band starts at 200 rather than at 1 because GNUnet reports a helper it 87 could not execute as exit status 1, which must not be mistaken for a 88 delivery. The subset below is what this helper can actually 89 report; see challenger-send-sms(1) for the full table. 90 91 **0** 92 Delivery to the handset was confirmed. 93 94 **201** 95 BudgetSMS accepted the message but delivery was not confirmed within the 96 polling window, including the case of a message that has been sent but not 97 yet acknowledged by the handset. 98 99 **10** 100 The destination is not numeric, is empty, or is formatted invalidly. 101 102 **11** 103 The destination number is too short. 104 105 **14** 106 The destination is invalid: either rejected as such at submission, or 107 reported as an invalid destination address in the delivery status. 108 109 **15** 110 The message was not allowed to the destination. 111 112 **21** 113 The message expired before it could be delivered. 114 115 **22** 116 The service centre could not process the message, or the route reported a 117 wrong operator for the destination. 118 119 **30** 120 BudgetSMS is unavailable or timed out, there is no route to the destination, 121 the gateway is unreachable, a system error occurred, or the message was 122 never sent. 123 124 **31** 125 BudgetSMS rejected the request, for instance because the message identifier 126 used for the delivery query was invalid or a custom identifier had already 127 been used. 128 129 **32** 130 BudgetSMS answered with a rate-limit HTTP status. 131 132 **40** 133 **BUDGETSMS_USERNAME**, **BUDGETSMS_USERID** or **BUDGETSMS_HANDLE** is not 134 set or empty, **BUDGETSMS_USERID** is not numeric, the helper was invoked 135 with the wrong number of arguments, or BudgetSMS rejected a parameter of the 136 request such as an empty or over-long message, an unacceptable sender, a 137 character-set problem, or an account without a route set up. 138 139 **41** 140 BudgetSMS refused the credentials, the account is not active, or the request 141 came from an IP address that is not registered for the account. 142 143 **42** 144 The pre-paid BudgetSMS account has insufficient credits to send messages. 145 146 **50** 147 Delivery failed with no reason given, or BudgetSMS reported an unknown error 148 or a code that could not be classified. 149 150 BudgetSMS has no error code for a number that is too long, so status 12 is 151 never reported; none that means an identical message is already in flight, so 152 status 202 is never reported; and neither its error codes nor its delivery 153 statuses distinguish a non-mobile subscription from an unreachable handset, so 154 status 13 and 20 are never reported either. 155 156 157 See Also 158 ======== 159 160 challenger-send-sms(1), challenger-send-sms-seven(1), 161 challenger-send-sms-gatewayapi(1), challenger-send-sms-aspsms(1), 162 challenger-send-sms-clicksend(1), challenger-send-sms-telesign(1), 163 challenger-httpd(1), challenger.conf(5). 164 165 166 Bugs 167 ==== 168 169 Report bugs by using https://bugs.taler.net or by sending electronic 170 mail to <taler@gnu.org>.