diff options
Diffstat (limited to 'README.org')
| -rw-r--r-- | README.org | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/README.org b/README.org new file mode 100644 index 0000000..f7ec597 --- /dev/null +++ b/README.org @@ -0,0 +1,59 @@ +#+TITLE: sendsms + +A CLI to send SMS via [[https://console.twilio.com][twilio's API]]. + +The CLI takes as argument the path to a configuration file that contains credentials to the API. It also has a number of sub commands, and each sub command is associated with a specific action. + +For each action, a section in the configuration file is expected. The two actions currently supported are: +- =reboot= +- =hello= + +=hello= is a simple one used for testing, it sends "hello world". + +=reboot= is used to create a message that contains the host's name and the IP address of the network interface specified in the configuration file. + +* Usage +The tool supports sub-commands, which are profiles with predefined messages. + +Output using one of the test phone numbers: +#+begin_src sh +> sendsms -c sendsms-test.toml reboot +failed to send the message: (400) The 'From' number +15005550001 is not a valid phone number, shortcode, or alphanumeric sender ID. +#+end_src + +For example, you can write a =systemd= unit that is triggered after a reboot to send an SMS with =sendsms reboot=. The SMS will contain the host's name and the IP of a predefined interface. +* Configuration +A configuration looks like this: +#+begin_src toml +account_sid='xxx' +auth_token='xxx' +from='+1500xxx' +to='+1415xxxxxx' + +[reboot] +ifname='wlan0' +#+end_src + +You can find the =account_sid= and =auth_token= information in the [[https://console.twilio.com/?frameUrl=%2Fconsole%3Fx-target-region%3Dus1][console]]. +* Testing +For testing, you can use the [[https://console.twilio.com/us1/account/keys-credentials/api-keys?frameUrl=%2Fconsole%2Fproject%2Fapi-keys%3Fx-target-region%3Dus1][testing credentials]]. This will not send an SMS and you won't be charged. + +When testing, you can use the following phone numbers for =from=: +| number | description | status code | +| +15005550001 | This phone number is invalid. | 21212 | +| +15005550007 | This phone number is not owned by your account or is not SMS-capable. | 21606 | +| +15005550008 | This number has an SMS message queue that is full. | 21611 | +| +15005550006 | This number passes all validation. | No error | +| All Others | This phone number is not owned by your account or is not SMS-capable. | 21606 | + +For =to=: +| number | description | status code | +| +15005550001 | This phone number is invalid. | 21211 | +| +15005550002 | Twilio cannot route to this number. | 21612 | +| +15005550003 | Your account doesn't have the international permissions necessary to SMS this number. | 21408 | +| +15005550004 | This number is blocked for your account. | 21610 | +| +15005550009 | This number is incapable of receiving SMS messages. | 21614 | +| All Others | Any other phone number is validated normally. | Input-dependent | + +* Build +This can be build via =nix build .= from the root of the repository, or =cargo build= from inside the directory. |