challenger-send-sms-gatewayapi.1.rst (7511B)
1 challenger-send-sms-gatewayapi(1) 2 ################################# 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **challenger-send-sms-gatewayapi** - transmit a Challenger TAN by SMS via GatewayAPI 10 11 12 Synopsis 13 ======== 14 15 **challenger-send-sms-gatewayapi** *PHONE_NUMBER* 16 17 18 Description 19 =========== 20 21 **challenger-send-sms-gatewayapi** transmits a TAN to a mobile phone number 22 using the GatewayAPI REST 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 The provider runs two platforms: ``gatewayapi.eu``, on which hosting, 31 ownership and routing stay inside the European Union, and 32 ``gatewayapi.com``. This helper uses the EU platform unless told 33 otherwise, and an API token is only valid on the platform it was 34 created for. 35 36 A submission that is accepted returns a message id and means only that 37 GatewayAPI took the message. Delivery is confirmed separately by polling the 38 message by that id, for a bounded period. A message still in flight when the 39 polling window closes is reported as accepted, not as a failure. The polling 40 request answers with HTTP 404 until the message has been transferred to 41 long-term storage, which is not an error. 42 43 GatewayAPI carries its diagnosis in the body of a failed request, as a 32-bit 44 error code written in hexadecimal whose first byte identifies the origin of the 45 error: the API itself, the subscriber database, the mobile switching centre, a 46 screening rule, the service centre, routing, the SMSC protocol, the service 47 provider, or GatewayAPI's own filters. Every code ending in ``00`` to ``0F`` is 48 a generic placeholder whose meaning depends on its context; such a code does not 49 override the classification implied by the delivery status itself. The same 50 codes accompany a delivery status notification, which is what lets this helper 51 distinguish an unknown subscriber from a barred one, a switched-off handset 52 from a congested network, and a message blocked by a content filter from one 53 the operator never accepted. 54 55 A delivery status of ``UNDELIVERABLE`` without an accompanying code is reported 56 as a problem with the number, which is how GatewayAPI documents that status. A 57 status of ``REJECTED`` or ``SKIPPED`` without a code is reported as a carrier 58 failure rather than as a barred number: without a code naming a filter there is 59 no evidence that the number itself is at fault, and the next provider takes a 60 different route. A status of ``ACCEPTED`` is final, but it means the operator 61 accepted the message on the subscriber's behalf rather than the handset 62 confirming receipt, so it is reported as accepted rather than as delivered. 63 64 Environment 65 =========== 66 67 **GATEWAYAPI_TOKEN** 68 API token for the GatewayAPI REST API, as created in the GatewayAPI 69 dashboard of the platform in use. Required. The helper fails with status 40 70 if it is unset or empty, or if it contains a line break, as the token is 71 sent in an HTTP header. 72 73 **GATEWAYAPI_BASE_URL** 74 Base URL of the GatewayAPI platform to use. Optional, defaults to 75 ``https://gatewayapi.eu``, the platform that keeps hosting and routing 76 inside the European Union. Set it to ``https://gatewayapi.com`` for an 77 account on the global platform. A token is only valid on the platform it was 78 created for, so a mismatch is reported as a refused credential. 79 80 Credentials are taken from the environment of the invoking daemon, never from a 81 configuration file. 82 83 No sender identity is configured by this helper: the account default applies. 84 An alphanumeric sender must be pre-registered with the operator in several 85 countries, and a sender the operator does not accept fails every message. 86 87 88 Exit Status 89 =========== 90 91 An exit status of 0, or in the 200 to 210 band, means the TAN was 92 transmitted, or will be. Any other status means it was not. The success 93 band starts at 200 rather than at 1 because GNUnet reports a helper it 94 could not execute as exit status 1, which must not be mistaken for a 95 delivery. The subset below is what this helper can actually 96 report; see challenger-send-sms(1) for the full table. 97 98 **0** 99 Delivery to the handset was confirmed. 100 101 **201** 102 GatewayAPI accepted the message but delivery was not confirmed within the 103 polling window, including the case of a message still en route or buffered, 104 and the case of the operator accepting the message on the subscriber's 105 behalf. 106 107 **13** 108 The subscription cannot receive SMS: the teleservice is not provisioned, the 109 facility is not supported, or the equipment is not short-message equipped. 110 111 **14** 112 The subscriber is unknown or unidentified, the destination address is 113 invalid, its number plan or network type is not supported, or the number 114 matches a pattern known to be unreachable. 115 116 **15** 117 Delivery is barred or screened: the subscriber is barred or illegal, a 118 screening rule applies, or a GatewayAPI content or destination filter 119 stopped the message. 120 121 **20** 122 The subscriber is absent, detached, busy for mobile-terminated SMS, out of 123 handset memory, or out of pre-paid credit. 124 125 **21** 126 The message was not delivered before its validity period expired. 127 128 **22** 129 A mobile network component failed, a service centre was congested, routing 130 failed, the operator timed out, or the network declined to carry the message 131 without naming a filter. 132 133 **30** 134 GatewayAPI is unavailable, timed out, reported an internal error, or its 135 outbound queue is full. 136 137 **31** 138 GatewayAPI rejected the request, or the protocol exchange between the 139 gateway and the service centre failed. 140 141 **32** 142 A rate limit was exceeded, or a quota for the destination was exhausted. 143 144 **33** 145 The submission was answered with a success status but without a message id, 146 so whether the message was accepted could not be determined. 147 148 **40** 149 **GATEWAYAPI_TOKEN** is not set, is empty, or contains a line break; the 150 helper was invoked with the wrong number of arguments; or the account is not 151 authorized for the destination country or operator, the message class is not 152 configured, a parameter was missing or unsupported, or the submitted message 153 or sender was unacceptable. 154 155 **41** 156 GatewayAPI refused the token or the account: invalid credentials, an 157 unauthorized or unknown IP address, a frozen account, or an account for 158 which SMS is not enabled. A token created for the other platform is also 159 reported here. 160 161 **42** 162 The GatewayAPI account has insufficient credit to send the message. 163 164 **50** 165 The delivery failed with a code that names no cause, such as the unspecified 166 delivery error, or with a code that could not be classified. 167 168 GatewayAPI has no submission-time check that distinguishes a number that is 169 merely too short or too long, so status 11 and 12 are never reported, and 170 nothing in its error table means that an identical message is already in 171 flight, so status 202 is never reported either. 172 173 174 See Also 175 ======== 176 177 challenger-send-sms(1), challenger-send-sms-seven(1), 178 challenger-send-sms-budgetsms(1), challenger-send-sms-aspsms(1), 179 challenger-send-sms-clicksend(1), challenger-send-sms-telesign(1), 180 challenger-httpd(1), challenger.conf(5). 181 182 183 Bugs 184 ==== 185 186 Report bugs by using https://bugs.taler.net or by sending electronic 187 mail to <taler@gnu.org>.