challenger-send-sms-seven.1.rst (5989B)
1 challenger-send-sms-seven(1) 2 ############################ 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **challenger-send-sms-seven** - transmit a Challenger TAN by SMS via seven.io 10 11 12 Synopsis 13 ======== 14 15 **challenger-send-sms-seven** *PHONE_NUMBER* 16 17 18 Description 19 =========== 20 21 **challenger-send-sms-seven** transmits a TAN to a mobile phone number using 22 the seven.io REST/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 seven.io answers with HTTP 200 even for an authentication failure and reports 31 the outcome in the ``success`` field of the response body, which carries a 32 numeric return code. A submission that is accepted only means the gateway took 33 the message; delivery is confirmed separately by polling the outbound logbook 34 for the returned message id, for a bounded period. A message still in flight 35 when the polling window closes is reported as accepted, not as a failure. 36 37 A single bad-number code covers every unusable recipient, so a number that is 38 malformed, too short, too long or unallocated cannot be distinguished at 39 submission time. 40 41 seven.io blocks a message whose text and recipient are identical to one 42 accepted within the previous three minutes. Because the suppressed message is by 43 definition identical to one already accepted, the TAN will still reach the user, 44 and this is reported as a success. Note that a deployment may switch this block 45 off in its seven.io account settings, in which case duplicates are charged for 46 and this helper never reports that status. The provider also enforces a daily 47 cap per recipient number; since another provider keeps its own counter, that is 48 reported as a rate limit rather than as a problem with the number. 49 50 **The delivery report carries no reason code**, only a status word. A confirmed 51 non-delivery for which the status word itself names no cause is therefore 52 reported as unclassified rather than guessed at as a bad number, which also 53 lets the dispatcher try the next provider. 54 55 The logbook entry returned while polling echoes the message text, and hence the 56 TAN, back to the helper. Like every Challenger helper, this one writes status 57 diagnostics rather than provider responses to standard error, so the TAN does 58 not reach the log of the invoking daemon. 59 60 61 Environment 62 =========== 63 64 **SEVEN_API_KEY** 65 API key for the seven.io REST/HTTP API, as created in the developer area of 66 the seven.io dashboard. Required. The helper fails with status 40 if it is 67 unset or empty, or if it contains a line break, as the key is sent in an 68 HTTP header. 69 70 **SEVEN_SENDER** 71 Sender identity to show on the message, at most 11 alphanumeric or 16 72 numeric characters. Optional; if it is unset or empty, the sender is 73 ``Taler Ops``. An alphanumeric sender must be pre-registered with the 74 operator in several countries, and a sender the operator does not accept 75 fails every message; where that applies, configure a sender the operator 76 accepts, or a numeric one. 77 78 Credentials are taken from the environment of the invoking daemon, never from a 79 configuration file. 80 81 82 Exit Status 83 =========== 84 85 An exit status of 0, or in the 200 to 210 band, means the TAN was 86 transmitted, or will be. Any other status means it was not. The success 87 band starts at 200 rather than at 1 because GNUnet reports a helper it 88 could not execute as exit status 1, which must not be mistaken for a 89 delivery. The subset below is what this helper can actually 90 report; see challenger-send-sms(1) for the full table. 91 92 **0** 93 Delivery to the handset was confirmed. 94 95 **201** 96 seven.io accepted the message but delivery was not confirmed within the 97 polling window, including the case of a message buffered for a handset that 98 is switched off. 99 100 **202** 101 The message was suppressed as a duplicate of one accepted for the same 102 recipient within the previous three minutes. The earlier copy carries the 103 same TAN and is in flight. 104 105 **14** 106 The recipient number was rejected by the gateway. This one code covers a 107 malformed, too short, too long or unallocated number alike. 108 109 **21** 110 The message was not delivered before its validity period expired. 111 112 **22** 113 The network operator rejected the message. 114 115 **30** 116 seven.io is unavailable, timed out, or reported an error while sending. 117 118 **31** 119 seven.io answered with something other than one of its documented return 120 codes, together with a client-error HTTP status. 121 122 **32** 123 The daily limit for this recipient number has been reached. 124 125 **40** 126 **SEVEN_API_KEY** is not set, is empty, or contains a line break; the helper 127 was invoked with the wrong number of arguments; or the gateway rejected a 128 parameter of the request, such as the configured sender, a message that is 129 too long, or a parameter it does not support. 130 131 **41** 132 seven.io refused the API key, the key has no access to the endpoint, or the 133 request came from an IP address that is not on the account's permitted list. 134 135 **42** 136 The pre-paid seven.io account has insufficient credit to send the message. 137 138 **50** 139 The message was reported as not delivered, with no reason given, or the 140 gateway reported a return code that could not be classified. 141 142 Because the delivery report has no reason code, this helper never reports 143 status 13, 15 or 20, and the single bad-number code means it never reports 144 status 11 or 12. 145 146 147 See Also 148 ======== 149 150 challenger-send-sms(1), challenger-send-sms-gatewayapi(1), 151 challenger-send-sms-budgetsms(1), challenger-send-sms-aspsms(1), 152 challenger-send-sms-clicksend(1), challenger-send-sms-telesign(1), 153 challenger-httpd(1), challenger.conf(5). 154 155 156 Bugs 157 ==== 158 159 Report bugs by using https://bugs.taler.net or by sending electronic 160 mail to <taler@gnu.org>.