challenger-send-sms-aspsms.1.rst (4690B)
1 challenger-send-sms-aspsms(1) 2 ############################# 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **challenger-send-sms-aspsms** - transmit a Challenger TAN by SMS via ASPSMS 10 11 12 Synopsis 13 ======== 14 15 **challenger-send-sms-aspsms** *PHONE_NUMBER* 16 17 18 Description 19 =========== 20 21 **challenger-send-sms-aspsms** transmits a TAN to a mobile phone number using 22 the ASPSMS web 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 Each submission carries a generated transaction reference number, which is then 31 used to poll the ASPSMS send log for a delivery report, for a bounded period. A 32 message still in flight when the polling window closes is reported as accepted, 33 not as a failure. 34 35 ASPSMS accepts a message and reports errors in the body of an otherwise 36 successful HTTP response; the integer ``ErrorCode`` field carries the outcome, 37 and a value of 1 means success. The accompanying description text is not stable 38 and is not used for classification. 39 40 **ASPSMS has no error code for an unusable recipient number.** A malformed or 41 unallocated number is accepted at submission, consuming a credit, and the 42 problem is only revealed later in the delivery report as a reason code. A 43 message to a switched-off handset may remain buffered for up to 24 hours before 44 a final status is reported, far longer than the polling window, so such a 45 message is reported as accepted rather than failed. 46 47 48 Environment 49 =========== 50 51 **ASPSMS_USERKEY** 52 ASPSMS account user key. Required. 53 54 **ASPSMS_PASSWORD** 55 ASPSMS API password. Required. 56 57 **ASPSMS_SENDER** 58 Sender identity to show on the message (ASPSMS's ``Originator``), at most 11 59 alphanumeric or 16 numeric characters. Optional; if it is unset or empty, 60 the sender is ``Challenger``. An alphanumeric sender must be pre-registered 61 with the operator in several countries; where that applies, configure a 62 sender the operator accepts, or a numeric one. 63 64 The helper fails with status 40 if either of the two required variables is 65 unset or empty. Credentials are taken from the environment of the invoking 66 daemon, never from a configuration file. 67 68 69 Exit Status 70 =========== 71 72 An exit status of 0, or in the 200 to 210 band, means the TAN was 73 transmitted, or will be. Any other status means it was not. The success 74 band starts at 200 rather than at 1 because GNUnet reports a helper it 75 could not execute as exit status 1, which must not be mistaken for a 76 delivery. The subset below is what this helper can actually 77 report; see challenger-send-sms(1) for the full table. 78 79 **0** 80 Delivery to the handset was confirmed. 81 82 **201** 83 ASPSMS accepted the message but delivery was not confirmed within the polling 84 window, including the common case of a message still buffered for a handset 85 that is switched off. 86 87 **13** 88 The destination is not equipped for SMS, is not a subscriber, or the facility 89 is not supported or not provided by the network. 90 91 **14** 92 The subscriber is unknown, or the destination address is invalid. 93 94 **15** 95 The number is barred, either for calls or for the requested operation. 96 97 **20** 98 The subscriber is absent: the handset is switched off or out of coverage. 99 100 **21** 101 The message expired after the network gave up retrying delivery. 102 103 **22** 104 A mobile network component failed, or a service centre was congested. 105 106 **30** 107 ASPSMS is unavailable, timed out, or reported a transmission error. 108 109 **31** 110 ASPSMS rejected the request, for instance because the message exceeded the 111 maximum length or a parameter was invalid. 112 113 **40** 114 **ASPSMS_USERKEY** or **ASPSMS_PASSWORD** is not set, or the helper was 115 invoked with the wrong number of arguments. 116 117 **41** 118 ASPSMS refused the credentials, denied access to the account, or the 119 configured originator is not authorized. 120 121 **42** 122 The pre-paid ASPSMS account has insufficient credits. 123 124 **50** 125 The delivery report carried a reason code that could not be classified. 126 127 ASPSMS documents no rate limit and no rate-limit code, so status 32 is never 128 reported by this helper. 129 130 131 See Also 132 ======== 133 134 challenger-send-sms(1), challenger-send-sms-clicksend(1), 135 challenger-send-sms-telesign(1), challenger-send-sms-seven(1), 136 challenger-send-sms-gatewayapi(1), challenger-send-sms-budgetsms(1), 137 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>.