What is gcsms?
gcsms allows you to programmatically send SMS for free to anyone who has a Google account. gcsms is written to present Google Calendars as messaging lists, something akin to regular mailing lists, where users who subscribe receive all the messages sent to the mailing list. In this case, anyone who is subscribed to a messaging list will receive SMSes. gcsms uses Google Calendar API v3 to create/delete calendars and events. Everything that gcsms can do, can also be done through Google Calendar's web interface.
Initially, this project came to being to cut on costs of monitoring the health of a website by making use of the free SMS notification service offered by Google Calendar, instead of using an SMS gateway like twilio or tropo. Bells and whistles, such as ability to send to multiple recipients was later added in order to create a generic multipurpose tool.
Sold. How do I do it?
There are various scenarios in which gcsms can be used. We start with the most simple one and build on that.
But before anything, install gcsms:
$ pip install gcsms
Scenario A (single subscriber)
You want to get an SMS every time your website returns a 5xx HTTP code.
You must set up a few things before using gcsms to send SMS:
- Setup a Google account if you don't already have one (https://gmail.com).
- In Google Calendar (https://calendar.google.com), under 'Calendar Settings' -> 'Mobile Setup', enter your mobile number and verify it.
- In API Console (https://code.google.com/apis/console), click 'Create Project' and enable 'Calendar API'.
- In API Console, under 'API Access', click 'Create an OAuth 2.0 client ID...' and input 'gcsms' as Product Name. Click 'Next' and under 'Application type' choose 'Installed application'. It should default to 'Other' in 'Installed application type' section. Finalize by clicking 'Create Client ID' and note down 'Client ID' and 'Client Secret' from the following window.
~/.gcsmsand enter the 'Client ID' and 'Client Secret' and save - see sample.config for the format of the config file
gcsms.py authand follow the instructions, granting calendar access to gcsms.
At this point, you no longer need to use the web interface - everything can be done using gcsms commands. Let's create a new messaging list (ie Calendar):
$ gcsms create web-health :email@example.com
That long and ugly output that starts with
: is the messaging list ID.
It's unique and is the preferred way of referring to messaging lists
when using gcsms in other scripts for automation. IDs always start with
:. Also, you can have multiple messaging lists with identical names
but each will have a unique ID.
You can see a list of all the messaging lists you have joined (which includes all the ones you create/own):
$ gcsms ls web-health
-l option gives you a more detailed view:
$ gcsms ls -l rwom web-health :firstname.lastname@example.org
The first three letters indicate your access to the messaging list:
rmeans you can receive messages
wmeans you can send messages
omeans you can manage other people's access and also delete the messaging list (using
gcsms rm) which will delete it for everyone
m indicates that the messaging list is silenced (muted). In this mode,
you will not receive any SMSes until you unmute the messaging list:
$ gcsms unmute web-health $ gcsms ls -l rwo- web-health :email@example.com
Note: All messaging lists you create or join are muted by default.
At this stage, you can send yourself a message:
$ gcsms send web-health 'Site down: 502'
You should receive an SMS shortly after the above command returns. But have patience. There might be 5 to 30 seconds delay or sometimes more. From time to time, you may receive multiple copies of the same message. Unfortunately the promptness of the delivery cannot be controlled and if your application requires a more timely delivery, you should consider paying for use of an SMS gateway service like twilio.
Scenario B (multiple subscribers)
Alice, your business partner would also like to know when the website is not feeling well.
First, Alice needs to do the steps to set up her API access (see the six steps in scenario A). Next, you need to give her access to your messaging list:
[you]$ gcsms acl-set web-health firstname.lastname@example.org reader
The above command gives Alice permission to only receive messages.
Alice needs to join your messaging list. She will need its unique ID.
You can find that out by using
gcsms ls -l. Once Alice has the ID, she
can join and subsequently unmute the newly joined messaging list, ready
to receive SMSes:
[alice]$ gcsms join :email@example.com [alice]$ gcsms unmute web-health
Now, if you run
gcsms send web-health 'Site down: 502', both you and
Alice will receive an SMS.
A while later, Alice gets annoyed by all the SMSes and wants to stop
receiving them. She can either
gcsms mute the messaging list. This
allows her to easily
unmute it later. She could also
gcsms leave the
messaging list. She can always
join later provided her access is not
revoked by you (using
Scenario C (multiple subscribers using web interface)
There are situations where the receivers don't have their API access setup or don't have the environment to run gcsms. That is OK. You can still use gcsms to send SMS to them. But they need to setup somethings manually through the web interface.
As per scenario B, you must give each user access:
$ gcsms acl-set web-health firstname.lastname@example.org reader $ gcsms acl-set web-health email@example.com reader
Now, if David and Jimmy log into their Google account and navigate to
https://calendar.google.com, they will see a new calendar named
gcsms:web-health added to their list of calendars. All calendars used
as messaging lists by gcsms are named with a prefix of
gcsms ls will not show you any calendars that doesn't follow
David and Jimmy need to add an 'SMS Event reminder' with exactly '1 minute' setting. They can do that by going into 'Calendar Settings' > 'Calendars' > 'gcsms:web-health' > 'Reminders and notifications' tab. It is needless to say, they must have already setup their mobile phone number and verified it (see steps 1 and 2 in scenario A).
That's it! Like Alice, David and Jimmy will now receive an SMS every
time you issue
gcsms send web-health.
We have pretty much covered all the commands. There are few more but you
can figure them out yourselves. Just run
gcsms -h to find out more.
- Renaming a messaging list using
gcsms renameonly affects the name in your list.
- You can import
gcsmsas a python module and use
GCSMSclass to do anything you can do with the command line program.
- If you have a Google Apps for Business account, in order to be able to
allow users outside of your domain to receive SMS or send SMS to
messaging lists you create, you must do the following:
- Go to Google Apps cpanel (https://www.google.com/a/cpanel/name.com)
- Go to 'Settings' tab > 'Calendar' settings
- Under 'External Sharing options for primary calendars', select any option other than the first one ('Only free/busy information') depending on the extent you wish to give outsiders access.
contribution instructions originally written by Linus Torvalds
If you want to contribute code, please either send signed-off patches or a pull request with signed-off commits. If you don't sign off on them, we will not accept them. This means adding a line that says "Signed-off-by: Name " at the end of each commit, indicating that you wrote the code and have the right to pass it on as an open source patch.
Also, please write good git commit messages. A good commit message looks like this:
Header line: explaining the commit in one line Body of commit message is a few lines of text, explaining things in more detail, possibly giving some background about the issue being fixed, etc etc. The body of the commit message can be several paragraphs, and please do proper word-wrap and keep columns shorter than about 74 characters or so. That way "git log" will show things nicely even when it's indented. Reported-by: whoever-reported-it Signed-off-by: Your Name <firstname.lastname@example.org>
where that header line really should be meaningful, and really should be just one line. That header line is what is shown by tools like gitk and shortlog, and should summarize the change in one readable line of text, independently of the longer explanation.