challenger-send-sms-seven.1.rst (5799B)
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 Credentials are taken from the environment of the invoking daemon, never from a 71 configuration file. 72 73 No sender identity is configured by this helper: the account default applies. 74 An alphanumeric sender must be pre-registered with the operator in several 75 countries, and a sender the operator does not accept fails every message. 76 77 78 Exit Status 79 =========== 80 81 An exit status of 0, or in the 200 to 210 band, means the TAN was 82 transmitted, or will be. Any other status means it was not. The success 83 band starts at 200 rather than at 1 because GNUnet reports a helper it 84 could not execute as exit status 1, which must not be mistaken for a 85 delivery. The subset below is what this helper can actually 86 report; see challenger-send-sms(1) for the full table. 87 88 **0** 89 Delivery to the handset was confirmed. 90 91 **201** 92 seven.io accepted the message but delivery was not confirmed within the 93 polling window, including the case of a message buffered for a handset that 94 is switched off. 95 96 **202** 97 The message was suppressed as a duplicate of one accepted for the same 98 recipient within the previous three minutes. The earlier copy carries the 99 same TAN and is in flight. 100 101 **14** 102 The recipient number was rejected by the gateway. This one code covers a 103 malformed, too short, too long or unallocated number alike. 104 105 **21** 106 The message was not delivered before its validity period expired. 107 108 **22** 109 The network operator rejected the message. 110 111 **30** 112 seven.io is unavailable, timed out, or reported an error while sending. 113 114 **31** 115 seven.io answered with something other than one of its documented return 116 codes, together with a client-error HTTP status. 117 118 **32** 119 The daily limit for this recipient number has been reached. 120 121 **40** 122 **SEVEN_API_KEY** is not set, is empty, or contains a line break; the helper 123 was invoked with the wrong number of arguments; or the gateway rejected a 124 parameter of the request, such as the configured sender, a message that is 125 too long, or a parameter it does not support. 126 127 **41** 128 seven.io refused the API key, the key has no access to the endpoint, or the 129 request came from an IP address that is not on the account's permitted list. 130 131 **42** 132 The pre-paid seven.io account has insufficient credit to send the message. 133 134 **50** 135 The message was reported as not delivered, with no reason given, or the 136 gateway reported a return code that could not be classified. 137 138 Because the delivery report has no reason code, this helper never reports 139 status 13, 15 or 20, and the single bad-number code means it never reports 140 status 11 or 12. 141 142 143 See Also 144 ======== 145 146 challenger-send-sms(1), challenger-send-sms-gatewayapi(1), 147 challenger-send-sms-budgetsms(1), challenger-send-sms-aspsms(1), 148 challenger-send-sms-clicksend(1), challenger-send-sms-telesign(1), 149 challenger-httpd(1), challenger.conf(5). 150 151 152 Bugs 153 ==== 154 155 Report bugs by using https://bugs.taler.net or by sending electronic 156 mail to <taler@gnu.org>.