mirror of
https://github.com/therootcompany/golib.git
synced 2026-01-27 23:18:05 +00:00
doc(sendsms): add README.md
This commit is contained in:
parent
8654c1c1f5
commit
674960b497
148
cmd/sendsms/README.md
Normal file
148
cmd/sendsms/README.md
Normal file
@ -0,0 +1,148 @@
|
||||
# [sendsms](https://github.com/therootcompany/golib/tree/main/cmd/sendsms)
|
||||
|
||||
A little ditty I created for sending mass texts for community and professional events - church, school, meetups, etc.
|
||||
|
||||
I bought a $30 Android phone on Facebook marketplace, a $5/month [Tello SIM](https://tello.com/buy/custom_plans), and installed [SMS Gateway for Android™](https://github.com/capcom6/android-sms-gateway) - because Twilio was getting way too expensive with all the plan and compliance fees and such to basically just send a handful of messages now and then.
|
||||
|
||||
```sh
|
||||
sendsms --csv ./messages.csv --start-time '11:30am' --end-time '1:30pm'
|
||||
```
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- Example
|
||||
- Usage
|
||||
- CSV Data
|
||||
- Templates
|
||||
- Tips for High Delivery
|
||||
- Legal
|
||||
|
||||
## Example
|
||||
|
||||
You get a summary of what's about to happen:
|
||||
|
||||
```text
|
||||
Warning: skipped 2 rows with missing or invalid data
|
||||
(pass --verbose for more detail)
|
||||
|
||||
Info: list of 123 messages
|
||||
Info: start after 10:00am (11h30m30s ago)
|
||||
Info: end around 11:30pm (59m30s from now)
|
||||
Info: delay 20s between messages (15s + 10s jitter)
|
||||
Info: This is what a sample message from list look like:
|
||||
|
||||
To: +18015551234 (Joe)
|
||||
Hey {Name}, Widget workshop tonight. You coming? - Dude Man
|
||||
Hey Joe, Widget workshop tonight. You coming? - Dude Man
|
||||
|
||||
Continue? [y/N]
|
||||
```
|
||||
|
||||
And the messages as they send:
|
||||
|
||||
```text
|
||||
# Send to +1 (801) 555-1234
|
||||
Hey Joe, Widget workshop tonight. You coming? - Dude Man
|
||||
sleep 21.098s
|
||||
|
||||
# Send to +1 (385) 555-4321
|
||||
Hey Jon, Widget workshop tonight. You coming? - Dude Man
|
||||
sleep 34.567s
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```text
|
||||
Usage of sendsms
|
||||
-csv string
|
||||
Path to file with newline-delimited phone numbers (default "./messages.csv")
|
||||
-dry-run
|
||||
Skip sending messages and sleeping, runs without confirmation
|
||||
-end-time string
|
||||
don't send messages after this time (e.g. 4pm, 23:59) (default "8:30pm")
|
||||
-max-duration duration
|
||||
don't send messages for more than this long (e.g. 10m, 2h30m, 6h)
|
||||
-min-delay duration
|
||||
don't send messages closer together on average than this (e.g. 10s, 2m) (Default: 20s)
|
||||
-print-curl
|
||||
Show full curl commands instead of messages
|
||||
-shuffle
|
||||
Randomize the list
|
||||
-start-time string
|
||||
don't send messages before this time (e.g. 10:00, 10am, 00:00) (default "10am")
|
||||
-verbose
|
||||
Show parse warnings and other debug info
|
||||
-y Confirm without prompting
|
||||
```
|
||||
|
||||
Human, debug, and error output goes to `stderr` (`Info`, `Warn`, `Skip`, `Error`).
|
||||
|
||||
Machine-parsable output goes to `stdout` (mostly the comment for tracking success, `curl`, `sleep`)
|
||||
|
||||
## Config
|
||||
|
||||
1. Copy the example
|
||||
```sh
|
||||
cp -RPp ./example.env ./.env
|
||||
```
|
||||
2. Season `.env` to taste
|
||||
```sh
|
||||
SMSGW_BASEURL=http://192.168.1.200:8080
|
||||
#SMSGW_BASEURL=https://smsgateway.example.com
|
||||
SMSGW_USERNAME=smsgw
|
||||
SMSGW_PASSWORD=xxxx-xxxx-xxxx-xxxx
|
||||
```
|
||||
|
||||
## CSV Data
|
||||
|
||||
The CSV is required to have these 3 named headers:
|
||||
|
||||
| Field | Purpose |
|
||||
| ---------- | ------------------------------------------------------------------------------- |
|
||||
| `Name` | Printed with errors, may be used in templates. May be empty. |
|
||||
| `Phone` | Used for sending messages |
|
||||
| `Message` | A literal or template message that will be templated and sent to this recipient |
|
||||
| _Whatever_ | All other fields can be used for templates and are otherwise ignored |
|
||||
|
||||
For example:
|
||||
|
||||
```csv
|
||||
Name,Phone,Message,Spice Level,Lucky number
|
||||
Bob,1800.555-1234,"Hello {Name}, Welcome to the fold!",Hot,2
|
||||
Suze,8005553456,"Hello {Name}, Welcome to the fold!",,11
|
||||
Jon,800.555.5678,"Hello {Name}, Be bold! {-Spice Level-}!",Volcano,
|
||||
,+1 (800) 555-5678,"Hello {Name}, Be bold! {-Spice Level-}!",,37
|
||||
```
|
||||
|
||||
- `Name`, `Phone`, and `Message` are present, as required
|
||||
- `Spice Level` and `Lucky number` can be used in templates.
|
||||
|
||||
## Message Templates
|
||||
|
||||
By default, templates do _The Right Thing™_ - meaning that **empty variables cut** the left thing:
|
||||
|
||||
`Hey {Name}!` becomes `Hey Joe!` when _Name_ is set and `Hey!` when _Name_ is empty.
|
||||
|
||||
The template syntax works like this:
|
||||
|
||||
| Syntax | Example | "Joe" | Empty ("") | Comment |
|
||||
| ---------- | -------------- | ----------- | ---------- | ----------------------------- |
|
||||
| `{Name}` | `Hey {Name}!` | `Hey Joe!` | `Hey!` | cuts left character if empty |
|
||||
| `{Name-}` | `1,{Name-},3` | `1,Joe,3` | `1,3` | cuts right character if empty |
|
||||
| `{-Name-}` | `Hey! {Name}!` | `Hey! Joe!` | `Hey!` | cuts left and right if empty |
|
||||
| `{+Name}` | `Name:{+Name}` | `Name:Joe` | `Name:` | keeps left character always |
|
||||
|
||||
You just just as well use `{Spice Level}` or `{Lucky number}` (you just can't use `{Phone}` or `{Message}`).
|
||||
|
||||
I DO NOT plan on making a robust template system. I was only interested in solving the _leading space_ / _trailing comma_ problem. \
|
||||
(but if I did, it would solve that problem too)
|
||||
|
||||
## Delivery-Rate Tips
|
||||
|
||||
Based on my own experience, having a few different messages (I typically have 4 or 5 for a list of 100+ people) with a delay of at least 10 seconds yields much better delivery than sending the same message as fast as possible.
|
||||
|
||||
And be careful to "warm up" the number first before sending long messages or messages with links. To do that, send out messages that get real replies - such as to friends, colleagues, etc.
|
||||
|
||||
# Legal
|
||||
|
||||
MPL-2.0
|
||||
@ -1,5 +1,5 @@
|
||||
Preferred,Phone,Message
|
||||
Bob,1800.555-1234,"Hello {First}, Welcome to the fold!"
|
||||
Suze,8005553456,"Hello {First}, Welcome to the fold!"
|
||||
Jon,800.555.5678,"Hello {First}, Be bold!"
|
||||
Jane,+1 (800) 555-5678,"Hello {First}, Be bold!"
|
||||
Name,Phone,Message,Spice Level,Lucky number
|
||||
Bob,1800.555-1234,"Hello {Name}, Welcome to the fold!",Hot,2
|
||||
Suze,8005553456,"Hello {Name}, Welcome to the fold!",,11
|
||||
Jon,800.555.5678,"Hello {Name}, Be bold! {-Spice Level-}!",Volcano,
|
||||
,+1 (800) 555-5678,"Hello {Name}, Be bold! {-Spice Level-}!",,37
|
||||
|
||||
|
4
cmd/sendsms/example.env
Normal file
4
cmd/sendsms/example.env
Normal file
@ -0,0 +1,4 @@
|
||||
#export SMSGW_BASEURL=http://192.168.1.200:8080
|
||||
export SMSGW_BASEURL=https://smsgateway.example.com
|
||||
export SMSGW_USERNAME=sms
|
||||
export SMSGW_PASSWORD=xxxx-xxxx-xxxx-xxxx
|
||||
Loading…
x
Reference in New Issue
Block a user