source: README @ 2fa9f803

The Twitter module implements Twitter support for BarnOwl. It also
supports automatic mirroring of some subset of Zephyrs you send to
Twitter.

To configure it, first

* Add your twitter credentials to ~/.owl/twitter as a JSON hash, e.g.
{"user":"nelhage", "password":"sekrit" }
* Load the module (cp Twitter.par into ~/.owl/modules and :reload-module Twitter)
* Set the twitter:class, twitter:instance, and twitter:opcode
  variables to the destination you want messages to be mirrored
  from. By default, they are -c $YOUR_USERNAME -i status -O twitter
  Setting twitter:opcode to "" will cause "normal" (i.e. no opcode)
  messages to that class/instance to be mirrored. A value of '*'
  works as a "match-anything" wildcard for any of the fields.

Twitter.par will also receive twitters and inject them into barnowl as
messages of type 'twitter'. It polls for normal messages once a
minute, and direct messages every other minute. To disable polling,
you can unset the 'twitter:poll' variable in BarnOwl.

Twitter.par now supports other Twitter-compatible microblogging
services, like identi.ca. To enable this, set the 'service' parameter
in your config hash to the API URL of your service. You will likely
also need to set 'apihost' and 'apirealm'. See Net::Twitter or your
blogging service's documentation for more information.

Twitter.par also supports using multiple Twitter and Twitter-compatible
microblogging accounts from the same instance.  To enable this, add 
additional hashes to your ~/.owl/twitter file as a JSON list, e.g.
----------8<----------cut here----------8<----------
[
  {
   "account_nickname": "twitter",
   "user": "nelhage",
   "password": "sekrit",
   "default": true,
   "publish_tweets": true
  },
  {
   "account_nickname": "identica",
   "service": "http://identi.ca/api",
   "user": "nelhage",
   "password": "sekriter",
   "publish_tweets": true
  }
  {
   "account_nickname": "sipb",
   "user": "sipb",
   "password":"m0ars3krit",
   "poll_for_tweets": false,
   "poll_for_dms": false,
  }
]
----------8<----------cut here----------8<----------

Outgoing tweets sent via ":twitter" without an explicit sender, or
mirrored from zephyr, go to every account with "publish_tweets" set.

Outgoing direct messages and @-replies without an explicit sender come
from whichever account has "default" set. If no account has "default",
the first account is assumed to have "default" set. It is an error to
have more than one account with "default" set to true.

There are several account-specific parameters that control the
behavior of Twitter.par when using multiple accounts:

* account_nickname (string, required if multiple accounts are in use)
    Specify a short name by which you can refer to the account, eg.
    "identica" (eg. :twitter-direct nelhage identica would send a
    direct message to @nelhage on identi.ca from your account
    nicknamed "identica").

* default (boolean, default false)
    If true, @-replies or direct messages you send without specifying
    an account will be sent using this account.  If no account has
    this parameter, such messages will be sent using the first account
    listed.

* poll_for_tweets (boolean, default true)
    If true, tweets sent by users this account follows will be
    displayed in your BarnOwl message list.

* poll_for_dms (boolean, default true)
    If true, direct messages sent to this account will be displayed in
    your BarnOwl message list.

* publish_tweets (boolean, default false)
    If true, tweets you send without specifying an account (either
    with the :twitter command or mirrored from a zephyr class) will be
    published to this account.

* show_mentions (boolean, default true)
    If true, BarnOwl will show all tweets that mention this account's
    username, regardless of whether or not this account is following
    the sender. Has no effect if poll_for_tweets is false.