24.9. challenger-send-sms-budgetsms(1)

24.9.1. Name

challenger-send-sms-budgetsms - transmit a Challenger TAN by SMS via BudgetSMS

24.9.2. Synopsis

challenger-send-sms-budgetsms PHONE_NUMBER

24.9.3. Description

challenger-send-sms-budgetsms transmits a TAN to a mobile phone number using the BudgetSMS HTTP 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.

Unlike the other provider helpers, this API returns no JSON. Every call answers with a single line, either OK followed by a value or ERR followed by a numeric error code, always with HTTP status 200. A successful submission returns the identifier of the message and means only that BudgetSMS handed the message to one of its uplinks; it already deducts credit, while a submission reported as an error does not. Delivery is confirmed separately by polling the delivery status for that identifier, for a bounded period. A message still in flight when the polling window closes is reported as accepted, not as a failure.

The error codes returned at submission are the most detailed of any configured provider for the shape of the number: a number that is too short, one that is not numeric or formatted invalidly, and one that is simply invalid as a destination are distinguished from each other. There is no code for a number that is too long.

The delivery statuses carry no reason code. The status for a failed delivery says only that delivery failed, so it is reported as unclassified rather than guessed at as a bad number, which also lets the dispatcher try the next provider. The statuses that mean the outcome is unknown are only reachable 24 to 72 hours after sending and thus never within the polling window.

This API requires a sender identity on every message, so unlike the other helpers this one sends a default sender that can be overridden; see BUDGETSMS_SENDER below.

24.9.4. Environment

BUDGETSMS_USERNAME

BudgetSMS account username. Required.

BUDGETSMS_USERID

Numeric BudgetSMS user id. Required. The helper fails with status 40 if the value is not a sequence of digits, as it is used to build the request URL.

BUDGETSMS_HANDLE

BudgetSMS API handle, the account’s API credential. Required.

BUDGETSMS_SENDER

Sender identity to show on the message, at most 11 alphanumeric or 16 numeric characters. Optional, defaults to Challenger. An alphanumeric sender must be pre-registered with the operator in several countries; where that applies, configure a sender the operator accepts, or a numeric one.

The helper fails with status 40 if any of the three required variables is unset or empty. Credentials are taken from the environment of the invoking daemon, never from a configuration file.

24.9.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

BudgetSMS accepted the message but delivery was not confirmed within the polling window, including the case of a message that has been sent but not yet acknowledged by the handset.

10

The destination is not numeric, is empty, or is formatted invalidly.

11

The destination number is too short.

14

The destination is invalid: either rejected as such at submission, or reported as an invalid destination address in the delivery status.

15

The message was not allowed to the destination.

21

The message expired before it could be delivered.

22

The service centre could not process the message, or the route reported a wrong operator for the destination.

30

BudgetSMS is unavailable or timed out, there is no route to the destination, the gateway is unreachable, a system error occurred, or the message was never sent.

31

BudgetSMS rejected the request, for instance because the message identifier used for the delivery query was invalid or a custom identifier had already been used.

32

BudgetSMS answered with a rate-limit HTTP status.

40

BUDGETSMS_USERNAME, BUDGETSMS_USERID or BUDGETSMS_HANDLE is not set or empty, BUDGETSMS_USERID is not numeric, the helper was invoked with the wrong number of arguments, or BudgetSMS rejected a parameter of the request such as an empty or over-long message, an unacceptable sender, a character-set problem, or an account without a route set up.

41

BudgetSMS refused the credentials, the account is not active, or the request came from an IP address that is not registered for the account.

42

The pre-paid BudgetSMS account has insufficient credits to send messages.

50

Delivery failed with no reason given, or BudgetSMS reported an unknown error or a code that could not be classified.

BudgetSMS has no error code for a number that is too long, so status 12 is never reported; none that means an identical message is already in flight, so status 202 is never reported; and neither its error codes nor its delivery statuses distinguish a non-mobile subscription from an unreachable handset, so status 13 and 20 are never reported either.

24.9.6. See Also

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

24.9.7. Bugs

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