24.11. challenger-send-sms-gatewayapi(1)

24.11.1. Name

challenger-send-sms-gatewayapi - transmit a Challenger TAN by SMS via GatewayAPI

24.11.2. Synopsis

challenger-send-sms-gatewayapi PHONE_NUMBER

24.11.3. Description

challenger-send-sms-gatewayapi transmits a TAN to a mobile phone number using the GatewayAPI REST API.

It is normally invoked by challenger-send-sms(1) as one provider in a fallback chain, and not directly. Its calling convention differs from that of the dispatcher: PHONE_NUMBER is the bare phone number, already extracted from the address object and already checked for general E.164 form. The message to transmit, including the TAN, is read from standard input.

The provider runs two platforms: gatewayapi.eu, on which hosting, ownership and routing stay inside the European Union, and gatewayapi.com. This helper uses the EU platform unless told otherwise, and an API token is only valid on the platform it was created for.

A submission that is accepted returns a message id and means only that GatewayAPI took the message. Delivery is confirmed separately by polling the message by that id, for a bounded period. A message still in flight when the polling window closes is reported as accepted, not as a failure. The polling request answers with HTTP 404 until the message has been transferred to long-term storage, which is not an error.

GatewayAPI carries its diagnosis in the body of a failed request, as a 32-bit error code written in hexadecimal whose first byte identifies the origin of the error: the API itself, the subscriber database, the mobile switching centre, a screening rule, the service centre, routing, the SMSC protocol, the service provider, or GatewayAPI’s own filters. Every code ending in 00 to 0F is a generic placeholder whose meaning depends on its context; such a code does not override the classification implied by the delivery status itself. The same codes accompany a delivery status notification, which is what lets this helper distinguish an unknown subscriber from a barred one, a switched-off handset from a congested network, and a message blocked by a content filter from one the operator never accepted.

A delivery status of UNDELIVERABLE without an accompanying code is reported as a problem with the number, which is how GatewayAPI documents that status. A status of REJECTED or SKIPPED without a code is reported as a carrier failure rather than as a barred number: without a code naming a filter there is no evidence that the number itself is at fault, and the next provider takes a different route. A status of ACCEPTED is final, but it means the operator accepted the message on the subscriber’s behalf rather than the handset confirming receipt, so it is reported as accepted rather than as delivered.

24.11.4. Environment

GATEWAYAPI_TOKEN

API token for the GatewayAPI REST API, as created in the GatewayAPI dashboard of the platform in use. Required. The helper fails with status 40 if it is unset or empty, or if it contains a line break, as the token is sent in an HTTP header.

GATEWAYAPI_BASE_URL

Base URL of the GatewayAPI platform to use. Optional, defaults to https://gatewayapi.eu, the platform that keeps hosting and routing inside the European Union. Set it to https://gatewayapi.com for an account on the global platform. A token is only valid on the platform it was created for, so a mismatch is reported as a refused credential.

Credentials are taken from the environment of the invoking daemon, never from a configuration file.

No sender identity is configured by this helper: the account default applies. An alphanumeric sender must be pre-registered with the operator in several countries, and a sender the operator does not accept fails every message.

24.11.5. Exit Status

An exit status of 0, or in the 200 to 210 band, means the TAN was transmitted, or will be. Any other status means it was not. The success band starts at 200 rather than at 1 because GNUnet reports a helper it could not execute as exit status 1, which must not be mistaken for a delivery. The subset below is what this helper can actually report; see challenger-send-sms(1) for the full table.

0

Delivery to the handset was confirmed.

201

GatewayAPI accepted the message but delivery was not confirmed within the polling window, including the case of a message still en route or buffered, and the case of the operator accepting the message on the subscriber’s behalf.

13

The subscription cannot receive SMS: the teleservice is not provisioned, the facility is not supported, or the equipment is not short-message equipped.

14

The subscriber is unknown or unidentified, the destination address is invalid, its number plan or network type is not supported, or the number matches a pattern known to be unreachable.

15

Delivery is barred or screened: the subscriber is barred or illegal, a screening rule applies, or a GatewayAPI content or destination filter stopped the message.

20

The subscriber is absent, detached, busy for mobile-terminated SMS, out of handset memory, or out of pre-paid credit.

21

The message was not delivered before its validity period expired.

22

A mobile network component failed, a service centre was congested, routing failed, the operator timed out, or the network declined to carry the message without naming a filter.

30

GatewayAPI is unavailable, timed out, reported an internal error, or its outbound queue is full.

31

GatewayAPI rejected the request, or the protocol exchange between the gateway and the service centre failed.

32

A rate limit was exceeded, or a quota for the destination was exhausted.

33

The submission was answered with a success status but without a message id, so whether the message was accepted could not be determined.

40

GATEWAYAPI_TOKEN is not set, is empty, or contains a line break; the helper was invoked with the wrong number of arguments; or the account is not authorized for the destination country or operator, the message class is not configured, a parameter was missing or unsupported, or the submitted message or sender was unacceptable.

41

GatewayAPI refused the token or the account: invalid credentials, an unauthorized or unknown IP address, a frozen account, or an account for which SMS is not enabled. A token created for the other platform is also reported here.

42

The GatewayAPI account has insufficient credit to send the message.

50

The delivery failed with a code that names no cause, such as the unspecified delivery error, or with a code that could not be classified.

GatewayAPI has no submission-time check that distinguishes a number that is merely too short or too long, so status 11 and 12 are never reported, and nothing in its error table means that an identical message is already in flight, so status 202 is never reported either.

24.11.6. See Also

challenger-send-sms(1), challenger-send-sms-seven(1), challenger-send-sms-budgetsms(1), challenger-send-sms-aspsms(1), challenger-send-sms-clicksend(1), challenger-send-sms-telesign(1), challenger-httpd(1), challenger.conf(5).

24.11.7. Bugs

Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>.