TwitGram v0.1
by Zarnock
zarnock1212@gmail.com
The Zone BBS - zonebbs.net

TwitGram is a Python script that makes it easy to send messages from your BBS
(or anywhere) to Twitter, Telegram, or to both simultaneously.  Twitter is a
social media site that allows you to post 140 character messages which anyone
will have the ability to see.  Telegram is an instant messaging application
that is available on Android, iPhone/iPad, Windows Phones, Linux, Mac, Windows
and even has a web-version.

Using TwitGram you can announce to the world, or quietly message yourself
about the ongoings of any process (not just on your BBS).  Want to know when
a new user signs up?  Add a call to TwitGram in the new user creation process
and you'll get an instant message about it.  Want to Tweet it at the same
time?  No problem, you can do that too.  Want to know the second new echomail
arrives, your system runs maintenance, polls the hub, someone uploads a file,
enters a specific door?  Those are all possible too!

And using TwitGram you don't have to enter the command twice if you want it
to go to both Telegram and Twitter, you just use the /b switch at the end
and in one call it gets Tweeted and messaged to your Telegram.  Change your
mind later and just want it to go to one?  Edit your call to use either the
/g (Telegram) or /t (Twitter) switch instead.


** REQUIREMENTS **
Python 2.7 
pip (or know how to install the APIs)
Tweepy (Twitter Python API)
Telepot (Telegram Python API)
Twitter account
Twitter app <--------------------------------instructions at end of doc
Telegram account
Telegram bot <-------------------------------instructions at end of doc
BBS that allows calling of external executables


===INSTALLATION===
If you don't already have the APIs you can install them by typing:
pip install tweepy
pip install telepot

Put twitgram.py in a location where your BBS can run it (ex: /mystic/scripts)

Edit twitgram.py and fill in the missing information:
For Telegram: bot_api, user_id
For Twitter: consumer_key, consumer_secret, access_token, access_token_secret,
and (optional) tags.

Depending on your OS (like Windows) you will need to delete the first line of
the script "#!/usr/bin/python" and run twitgram.py with "python twitgram.py"
and depending on your setup you may it to be "python c:\path\to\twitgram.py"
instead of just /path/to/twitgram.py as you'll see in my examples.


===USEAGE===
Basic use of twitgram.py is:

/path/to/twitgram.py "String to post." <arg>
<arg> can be either /g for Telegram, /t for Twitter, or /b for both.

&T can be put in the string to insert the time in HH:MM:SS format for
Twitter but it will also prepend with " at" and append with "."
In Telegram it will be replaced with a "." as there is no need to have
time sent in Telegram as all the messages are time stamped anyway.

Twitter: "Zarnock logged in&T" -> "Zarnock logged in at 12:34:56. <tags>"
Telegram:"Zarnock logged in&T" -> "Zarnock logged in."
Note there is no space ....^

*****************************************************************************
Be aware that Tweepy (and thus TwitGram Tweets) will error if you send the
same message twice in a row.  Most people get around this by sending a time
stamp for messages that occur often.  If you get an error and/or your Tweets
are not showing up, this is the most likely culprit.
*****************************************************************************

To have it trigger from inside the BBS you must have it execute an external
program call.  In Mystic BBS this done by selecting (DD) Exec external program
and make the Data field: /path/to/twitgram.py "String to Tweet/Telegram" /b

If you want to have it Tweet whenever someone logs in it would look like
this:
------------------------------------------------
Command: (DD) Exec external program
Data: /path/to/twitgram.py "%U has logged in&T" /t &
Access: !OI
Execute: Select
------------------------------------------------
This will send the message to Twitter, filling in %U for the current username 
(in Mystic) and " at xx:yy:zz." for &T.  You can pass any BBS software related 
identifiers to TwitGram as long as the BBS inserts the information at the time 
of call (which they all essentially do).

In this case I've set access to !OI (which in Mystic means not to run if
the user has logged in invisible.)  As well as I've added & to the end which
will run the command in the background and not have a brief delay for the 
user.  This can be duplicated in Windows by using "start /B (rest of command)"

TwitGram can also be called when BBS events are run by adding it to the shell
command that will be run, can be called from a door script/batch, can be run
as a traditional menu command (for example, replacing the non-working 
(P)age SysOp command on Mystic Linux.)


===OTHER INSTRUCTIONS===
These are instructions found on the web with a quick Google search.  As
of today (3/20/2017) they SEEM correct.  I did not follow them/test them,
I take no credit for their creation, and am otherwise not responsible for 
the information and content there.

For instructions on how to create a Telegram bot and get bot_api code:
https://core.telegram.org/bots

For instructions on how to find your Telegram user_id go to:
http://telepot.readthedocs.io/en/latest/

For instructions on how to get the needed Twitter info:
https://iag.me/socialmedia/how-to-create-a-twitter-app-in-8-easy-steps/

