path: root/README.org

#+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.