@votd Help

Quick Start

Twitter this:
@votd Mt 1:1 esv

... and you will get this back:


Mat 1:1 - The book of the genealogy of Jesus Christ, the son of David, 
the son of Abraham. (ESV)

Introduction

The VOTD (Verse Of The Day) Twitterbot provides a “pull” service which replies with the text when users send a Scripture reference or a dictionary word. There are 3 commands it responds to –

the verse or word request itself,
a command to set the user’s preferences for subsequent requests, and
the ubiquitous 'help' command.

The 'bot also provides a "push" service for those who either subscribe or follow, which transmits the verse of the day each day after midnight EST.

On this help page, the originating user is assumed to have a Twitter ID of `@user`.

Request Commands and their Syntax

Add the following after the '@votd' address header:

Syntax to request a verse

[ '['message']' ] book [ chap [ :verse ] ] [ version ] [ > twitterlist ]

Where:

message is free-form text that you want to add to the verse (your comment), enclosed in square brackets

book, chap, verse are the Bible reference being sought

version is the translation preference - one of the following: ASV, DBY, ESV, HNV, KJV, NASB, NIV, NKJV, NLB, NLT, RSV, RVR, VUL, WEB, WBST, WNT, YNG

twitterlist is a comma-seperated list of Twitter addresses (@a, @b, @c)

Syntax to request lookup of a word

'['message']' ] word [ dictionary ] [ > twitterlist ]

Where:

message is free-form text that you want to add to the verse (your comment), enclosed in square brackets

word is the dictionary word being looked up; this can also be a Strong's number in a form such as 'H123' or 'G123'

dictionary is currently one of

'Hitchcock' (for "Hitchcock's Dictionary of Bible Names"),

'Strong' (for a "Strong's Word" or a "Strong's Number" lookup) or

'conc' (for a concordance based on the KJV).

Only the first 3 letters are necessary

twitterlist is a comma-seperated list of Twitter addresses (@a, @b, @c)

Syntax to return the verse of the day manually

votd [ version ] [ > twitterlist ]

Syntax to return a random verse

rand [ version ] [ > twitterlist ]

Syntax for the help request

?

Syntax to set your preferences

pref choice [ ... , choice ]
... where choice is one or more of the following choices:

1).   dict = { hit | con | str }
... (HITchcock's dictionary (default), the CONcordance to the KJV or STRong's concordance; only the first 3 letters are necessary.)

2).   ver = translation
... where translation is one of the following choices:
ASV, DBY, ESV, HNV, KJV, NASB, NIV, NKJV, NLB, NLT, RSV, RVR, VUL, WEB, WBST, YNG

3).   votd = choice
... where choice [ ... , choice ] is one or more of the following choices:
OFF, ON or PROMISES, BYGRACE or HOEKSTRA, AM, PM, UTMOST, BREAD

Examples of sending a verse request

@votd Matt 1

(verse will default to '1') - @votd will reply with:
Matt 1:1 - The book of the generation of Jesus Christ, the son of David, the son of Abraham. (KJV)

@votd [First verse of the NT] Matt 1 esv
tells @votd to use the ESV for this request, overriding any preferences that may have been set. The comment in square brackets is put in front of the response.

@votd will reply with:
First verse of the NT: Mat 1:1 - The book of the genealogy of Jesus Christ, the son of David, the son of Abraham. (ESV)

@votd Matt 1:1 esv > @tom, @dick, @harry
tells @votd to reply with Matt 1:1 in the ESV translation, and then to retweet the text to the Twitter addresses that follow the 'greater than' sign.

It will reply to the originator with:
Mat 1:1 - The book of the genealogy of Jesus Christ, the son of David, the son of Abraham. (ESV)

... and to @tom (and similarly to @dick and @harry) with:
RT @user Mat 1:1 - The book of the genealogy of Jesus Christ, the son of David, the son of Abraham. (ESV)

Examples of sending a Bible name lookup request

To look up a word in Hitchcock's Bible Dictionary (assuming it is your preferred or default dictionary)::
@votd Ruth
@votd will reply with:
Ruth={drunk; satisfied }

To look up a word in the KJV concordance::
@votd Ruth conc
@votd will reply with:
ruth={13/13= Rut 1:4,14,16,22; 2:2,8,21-22; 3:9; 4:5,10,13; Mat 1:5 };

To look up a word in Strong's concordance::
@votd Christos strong
@votd will reply with:

Christos(khris-tos')={G5547=from [G5548]; anointed, i.e. the Messiah, an epithet of 
Jesus:--Christ.};

To look up the Strong's number for a Greek or Hebrew word, use this format:
@votd G3323
@votd will reply with:

(G3323)-Messias (mes-see'-as)={of Hebrew origin ([H4899]); the Messias (i.e. 
Mashiach), or Christ:--Messias.}

Examples of setting preferences

use the KJV translation by default (for verse requests that don’t specify one); set the dictionary to Hitchcock's and turn on push of the verse of the day:
@votd pref ver=kjv, dict = hit, votd=on

Example of the 'help' request

@votd ?
will reply with a line listing the number of verses @votd has sent you, what your preferred translation and dictionary are, whether or not you are subscribed to the midnight push, and where to get help (this page, updated as new features are added):
329 verses; PREF: Ver=KJV, Dict=hit, Votd=following. For help: http://t4.gwilt.org/votdhelp.html

Details about the verse request

The 'bot only responds with a single verse.
Some things (not the Bible book or chapter) default. If the verse is missing, ‘1’ is assumed. If the translation is missing, your preferred translation is used - if you haven't set one, ‘KJV’ is assumed.
About 50% of the verses in the Bible don’t fit into a single Twitter response - the longest verse in the KJV (Esther 8:9) has 530 characters. To compensate, you’ll receive 2 (or 3 or even 4) Twitters in response to your request. They will be preceded by sequencer characters such as ‘a] ‘ in front, as seen here (sequencing is needed because Twitter does not necessarily send the messages to your client in the order in which they originated from @votd):


a] Est 8:9 - At once the royal secretaries were summoned--on the twenty-third day of the third month, the month of Sivan. They


b] wrote out all Mordecai's orders to the Jews, and to the satraps, governors and nobles of the 127 provinces stretching from


c] India to Cush.*These orders were written in the script of each province and the language of each people and also to the


d] Jews in their own script and language. (NIV)

Note that the wordwrapping for each line will vary based on the length of the requestor's Twitter screen name, since that has to be included.
If the verse can be contained in a single reply, the sequencer characters will not be sent; you will receive:


John 11:35 - Jesus wept. (KJV)

The KJV, ASV & WEB (World English Bible) and WNT (Woeger New Testament) translations are pulled from a DB on the local server. All other translations are currently returned from the Blue Letter Bible site, via its published API. As a result of their efforts, the user can read the verses from the following additional translations: DBY, ESV, HNV, NASB, NIV, NKJV, NLB, NLT, RSV, RVR, VUL, WBST & YNG (check out the other features of their tremendous site too). See the section on translation copyrights at the bottom of this page.
The parser that interprets each user’s input tends on the side of mercy. For instance, there is only one book that begins with ‘T’ - if you put in the wrong spelling you’ll still get Titus returned. In fact, you can put in the word ‘trouble’ and still get Titus. (And for those people who think that there are other books that begin with ‘T’ – they don’t – not to the parser. They begin with ‘1’ and ‘2’.)
If you select the `votd` or `rand` option manually (pull), the translation comes with an arrow indicating that @votd is 'pulling' `(KJV->votd)`; the automatic deliveries after midnight come with an arrow in the other direction `(NASB<-votd)` indicating a push.

Minimal abbreviations for the Books

The following table lays out the minimum characters to define each book. You may type more, but they will be ignored. Three abbreviations are allowed despite being ambiguous - 'Cr' for Corinthians (as opposed to Chronicles); 'phl' for Philippians rather than Philemon and 'jud' for Jude not Judges - because the BLB uses them.

Book	alt. abbrevs	Book	alt. abbrevs	Book	alt. abbrevs
Genesis		Isaiah		Romans	rm
Exodus		Jeremiah		1Corinthians	1Cr
Leviticus	lv	Lamentations	lm	2Corinthians	2Cr
Numbers		Ezekiel	ezk	Galatians
Deuteronomy		Daniel		Ephesians
Joshua	jsh	Hosea	hs	Philippians	phl, php
Judges	jdg, jg	Joel	jl	Colossians
Ruth	rt	Amos		1Thessalonians
1Samuel		Obadiah		2Thessalonians
2Samuel		Jonah	jna	1Timothy
1Kings		Micah		2Timothy
2Kings		Nahum		Titus
1Chronicles		Habukkuk		Philemon	phm
2Chronicles		Zephaniah	zp	Hebrews	hbr
Ezra		Haggai	hg	James	jm
Nehemiah	nh	Zechariah	zc	1Peter
Esther		Malachi	ml	2Peter
Job	jb	Matthew	mt, mw	1John
Psalms		Mark	mk, mr	2John
Proverbs		Luke	lk	3John
Ecclesiastes		John	jhn	Jude	jde, jud
Song of Solomon		Acts		Revelation	rv

Details about the Bible name lookup request

It is not necessary to know how to spell the word exactly. If your word cannot be found, the 'bot will try to guess what you mean, based on how you would pronounce the word.
As with the verse lookup, it will return data on multiple lines if necessary - try entering `@votd matt` to see.
Certain words in the concordance would return vast numbers of Tweets if not throttled - the word `of`, for instance, would return the most at over 250 replies - so @votd limits the response to a maximum of approximately 3 messages. It follows these rules to look up and format a response:
1. If the word is found as an exact match, return that word, otherwise determine the closest-sounding words that fit:
  both of these requests ...
  @votd Ruth
  @votd Rooth
  ... will return the following response, containing all the words you would most likely be meaning:
  Ruth={drunk; satisfied }
2. If the response fits into 3 messages, send it:
  @votd matt
  ... will return the following:
  a] Maadai={pleasant; testifying }; Maadiah={pleasantness; the testimony of the Lord }; Madai={a measure; judging; a garment }; b] Matthew={given; a reward }; Media={measure; habit; covering }
3. If not, and the response consists of multiple words, list only the words found, so the user can re-request an exact match.
  @votd Rooth conc
  ... will return the following:
  `Rooth` not found in Concordance. Close sounds: ruth={13/13} wrath={194/198} wreath={1/1} wroth={47/49}
4. Otherwise there's only a single word in the response, so it was already an exact match; send the first 3 messages and warn of trucation.
  @votd after conc
  will return the following:
  a] after={1093/1178= Gen 1:11-12,21,24-26; 4:17; 5:3-4,7,10,13,16,19,22,26,30; 6:4,20; 7:10,14; 8:3,19; 9:9,28; b] 10:1,5,20,31-32; 11:10-11,13,15,17,19,21,23,25; 13:14; 14:17; 15:1; 16:3,13; 17:7-10,19; 18:5,11-12,19,25; 19:6,31; c] 22:1,20; 23:19; 24:55,67; 25:11,26; 26:18; 31:23,30,36; 32:29; 33:2,7; 35:5,12; 36:40 (5174 chars, truncating)
For the concordance, the first 2 numbers inside the braces - i.e.,
a] after={1093/1178= Gen 1:1...
- are the number of verses the word is found in (1093) and the number of actual occurances, including multiple ones inside a verse (1178).
Strong's lookup can be either by word or by number. Searching by number will require a letter ('G' or 'H') in front to tell @votd whether to search the Greek or Hebrew dictionary:
@votd Messias str
will return the following:
Messias(mes-see'-as)={G3323=of Hebrew origin ([H4899]); the Messias (i.e. Mashiach), or Christ:--Messias.};

@votd G3323
will return the following from the Greek dictionary:
(G3323)-Messias (mes-see'-as)={of Hebrew origin ([H4899]); the Messias (i.e. Mashiach), or Christ:--Messias.}

@votd H4886
will return the following from the Hebrew dictionary:
a] (H4886)-mashach (maw-shakh')={a primitive root; to rub with oil, i.e. to anoint; by implication, to b] consecrate; also to paint:--anoint, paint.}

Verse of the Day Prefence Details

There are several choices for the source of the automatic verse of the day:

choice source sent to you at

OFF - none -

ON or PROMISES BLB Promises midnight EST

BYGRACE or HOEKSTRA BLB Hoekstra midnight EST

AM BLB Spurgeon midnight EST

PM BLB Spurgeon noon EST

UTMOST RBC Utmost midnight EST

BREAD RBC Daily Bread midnight EST

PROV Small Group Proverbs midnight EST

Other details about the automatic push:

choice	source	sent to you at
OFF	- none -
ON or PROMISES	BLB Promises	midnight EST
BYGRACE or HOEKSTRA	BLB Hoekstra	midnight EST
AM	BLB Spurgeon	midnight EST
PM	BLB Spurgeon	noon EST
UTMOST	RBC Utmost	midnight EST
BREAD	RBC Daily Bread	midnight EST
PROV	Small Group Proverbs	midnight EST

Multiple choices may be specified, resulting in a seperate tweet for each.
Each time you send a preference request it overwrites all requests you may have made earlier - they are not additive.
A request containing the choice 'OFF' will turn off all automatic tweets, even if you entered other choices in the same request.
The tweet(s) will contain the verse and a link to the commentary at the site.

Other notes of interest

‘@’ vs ‘D’ choice

In general, people assume that 'following' a Twitterbot gets you the automatic service. This can be handy, since you can stop getting the 'bot's messages by unfollowing. It is not a great architecture, however, since it requires a lot of work on the part of the 'bot - repeated calls to find out who's following; possibly auto-following them back; then un-following them when they unfollow the 'bot; and Twitter currently has no method for determining who has stopped following the 'bot, which demands a lot of DB work as volume grows.

For these reasons, @votd was originally implemented as a subscription-only service. This went well with its initial approach, namely (the 'push' component) that the user sends a message to retrieve the text of a Bible verse. To get the daily verse sent automatically by the 'bot each midnight, the user subscribed to the service by sending in a specific message (pref votd=on). It quickly became apparent, however, that people were following without reading this help page - and thus assuming that simply 'following' would get them the verse of the day. So now the architecture has been changed and the user can either follow or subscribe to have @votd return the daily verse.

You can follow @votd, but you might regret it as traffic goes up. The advantages to following are (1) that the whole 140 characters can be used for the response (if your Twitter name is 10 characters long, for instance, that will be 12 more characters for the message); and (2) that the response is private. If you choose to follow, though, you’ll see every reply it makes to those users that don't follow - again, that's how the Twitter architecture works. And while that might be interesting for a while, you’ll probably get fed up fairly quickly. Whether @votd returns messages using the '@' or the 'D' form depends purely on whether you follow it or not.

Response times

@votd currently checks for inbound requests once a minute. Your Twitter client (OutTwit, Twhirl, etc.,) also has a time delay before it looks for Twitters. So the theoretical worst-case time for a response could be your client’s interval plus 1 minute – which is going to feel like a really looooong time.

Outage Response Times

If something goes wrong, I’ll fix it as soon as possible – but notifications from my web host can sometimes be hit-or-miss. Some problems will be Twittered in to me by the ‘bot, but any Twitter-related issues will obviously not.

Being considered

Support context token.
Add incremental movement (next & previous verse or dict entry).
Look for foreign language versions and support their book abbrevs.
(Suggested by Mike Henry) Set a preference such that a request for a long verse (that would otherwise spill over onto a second message) would instead result in a link to that verse on the BLB site.

Known problems

None.

Advanced use

Sending a verse as your status

There are two ways in which @votd can retweet a verse or word:

@votd Matt 1:1 ESV > @tom, @dick, @harry
will return the verse to the originator (@user) and also forward it on to the three other twitterers. They will see something like this:


RT @user Mat 1:1 - The book of the genealogy of Jesus Christ, the son of David, the son of 
Abraham. (ESV)

Sometimes you may want to send a verse as your status (i.e., to everyone following you). If you have logged on to @votd on the (@votd login page), then you can use the 'all' command:

@votd [Shortest verse in the Bible] John 11:35 KJV > all
which will return the verse as your next status (here we're also using the optional comment field):


Shortest verse in the Bible: John 11:35 - Jesus wept. (KJV) (via @votd)

You can also combine the 'all' choice with the regular retweet list, by entering 'all' at the front of the list like this:

@votd John 3:16 > all, @tom
This will send the following 3 pairs of tweets:

a] John 3:16 - For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not

b] perish, but have everlasting life. (KJV)
... will be sent to @user as the originator;

a] John 3:16 - For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not

b] perish, but have everlasting life. (KJV) (via @votd)
... will be sent as @user's regular status, and

RT @user a] John 3:16 - For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him

b] should not perish, but have everlasting life. (KJV)
... will be sent from @votd to @tom as a retweet.

Essentially, using the 'all' feature means that @votd becomes @user's client - like Twhirl or Tweetdeck - in order to send the message. After the message has been sent, @votd returns to it's regular function as a 'bot.
Note that when combining the 'all' and the list format, you MUST place 'all' in front of the list - immediately after the '>' symbol. Otherwise @votd will assume you want to retweet to @tom and @all.
If you try to use the 'all' option and have not logged on to @votd, the 'all' request will be ignored.

Copyright Notices for the Versions Used

Many of these versions are drawn from the Blue Letter Bible's excellent site. This site has a page displaying more detailed copyright information here: Copyright information.

ASV - Thomas Nelson & Sons first published the American Standard Version in 1901. This translation of the Bible is in the public domain.
DBY - J. N. Darby translated the Bible in 1890. This translation of the Bible is in the public domain.
ESV - Scripture quotations marked "ESV" are taken from The Holy Bible, English Standard Version. Copyright ©2001 by Crossway Bibles, a publishing ministry of Good News Publishers. Used by permission. All rights reserved. Text provided by the Crossway Bibles Web Service.
Hitchcock- This dictionary is from "Hitchcock's New and Complete Analysis of the Holy Bible," published by Roswell Hitchcock in 1869. It contains more than 2,500 Bible and Bible-related proper names and their meanings. Some Hebrew words of uncertain meaning have been left out. It is out of copyright, so feel free to copy and distribute it. I pray it will help in your study of God's Word--Brad Haugaard. This work is in the public domain.
HNV - The Hebrew Names Version is based off the World English Bible, an update of the American Standard Version of 1901. This translation of the Bible is in the public domain.
KJV - Outside of the United Kingdom, the KJV is in the public domain. Within the United Kingdom, the rights to the KJV are vested in the Crown.
NASB - Scripture quotations taken from the New American Standard Bible®, Copyright © 1960, 1962, 1963, 1968, 1971, 1972, 1973, 1975, 1977, 1995 by The Lockman Foundation Used by permission. (www.Lockman.org)
NIV - Scripture quotations marked (NIV) are taken from the HOLY BIBLE, NEW INTERNATIONAL VERSION®. NIV®. Copyright© 1973, 1978, 1984 by International Bible Society. Used by permission of Zondervan. All rights reserved.
NKJV - New King James Version®, Copyright © 1982, Thomas Nelson, Inc. All rights reserved. Bible text from the New King James Version® is not to be reproduced in copies or otherwise by any means except as permitted in writing by Thomas Nelson, Inc., Attn: Bible Rights and Permissions, P.O. Box 141000, Nashville, TN 37214-1000
NLT - Scripture quotations marked (NLT) are taken from the Holy Bible, New Living Translation, copyright © 1996. Used by permission of Tyndale House Publishers, Inc., Wheaton, Illinois 60189. All rights reserved.
RSV - Transcribed from: The Holy Bible: Revised Standard Version containing the Old and New Testaments, translated from the original tongues: being the version set forth A.D. 1611, revised A.D. 1881-1885 and A.D. 1901: compared with the most ancient authorities and revised A.D. 1946-52. — 2nd ed. of New Testament A.D. 1971. There should be enough in the rest of the description to identify the text. Freely available for non-commercial use provided that this header is included in its entirety with any copy distributed.
VUL - The Latin Vulgate was translated from the original languages into Latin by Jerome in A.D. 405. For over a millennium, it remained as the preferred translation of the church. This translation of the Bible is in the public domain.
WEB - The World English Bible is an update of the ASV that uses more modern English. This translation of the Bible is in the public domain.
WBST- The Webster Bible was translated by Noah Webster in 1833 in order to bring the language of the Bible up to date. This translation of the Bible is in the public domain.
WNT - WNT verses are from the Woeger New Testament (WNT) translation. Copyright 1996 by Woegersoft, LLC. Used by permission.
YNG - The Young's Literal Translation was translated by Robert Young, who believed in a strictly literal translation of God's word. This translation of the Bible is in the public domain.

Revision History

08-Aug-2009 - Allow the user to choose (via the 'pref' command) from a list of Verse-of-the-Day sites.
13-May-2009 - Added the message option, so users can prepend their comments to a verse
12-May-2009 - Added logons & expanded the RT facility, so @votd can Twitter on the user's behalf
09-Mar-2009 - Added a KJV concordance
08-Mar-2009 - Send daily verse to followers, not just subscribers
24-Feb-2009 - Added the ability to lookup Bible names, using the Hitchcock Dictionary
23-Feb-2009 - Added Hitchcock's Names
21-Feb-2009 - Added the Woeger NT
19-Feb-2009 - Moved the ASV to local storage
18 Feb 2009 - Added the World English Bible
16 Feb 2009 - Added 'rand'
09-Feb-2009 - Retweeting (forwarding) a verse
07-Feb-2009 - Daily verse sent automatically each night
01-Feb-2009 - Initial release

For help, reporting problems or to recommend improvements, Twitter me @swggy.

@VOTD Twitterbot Help