The Infobot Protocol ==================== Reverse engineered from infobot 0.45.3 by Ian Hickson. QUERY ----- If a bot is asked something by a user and does not know the answer, it may send queries to all the bots it knows. Queries must be in private messages and should have the following form: :INFOBOT:QUERY subject ...where "target" is the name of the user who sent the query in the first place, and "subject" is the question that was asked. In reality, "target" may be any string of non-whitespace character, so it could be used as an internal ID. A bot receiving a QUERY message must not try to contact the user given by "target" (that string should be treated as opaque) and must not make any assumptions about the "subject" string (it could contain *anything*, including high bit characters and the works). It is an error for the "subject" string to contain either "=is=>" or "=are=>". Receiving bots may ignore this error, however. Bot authors should carefully consider the potential for cascades before writing bots that chain QUERY messages. (As in, send out QUERY messages if they are unable to respond to a QUERY message themselves). In general, this is not a recommended behaviour. Bot authors are urged to write protection into their bots to avoid being affected by poorly written bots that cause cascades. REPLY ----- Upon receiving a QUERY message, a bot may, if it has information on "subject", opt to send a private message back to the originating bot in the form of a REPLY message. Bots must not send unsolicited REPLY messages. The form of the REPLY message is: :INFOBOT:REPLY subject =database=> object ...where "target" is the string of the same name from the original QUERY message, "subject" is the second string from the original QUERY message, "database" is one of "is" or "are" depending on the whether "subject" is determined to be singular or plural respectively, and "object" is the string that should be assumed to be the answer to "subject". The string may contain special formatting codes, these are described below. Upon receiving a REPLY message, bots should first check that they are expecting one. If they are, the user identified by the "target" string should be contacted and given the information represented by the "object" string. (Remember that the "target" string need not actually be the nick of the original user; it could be an internal key that indirectly identifies a user.) Bots should carefully check the integrity and authenticity of the "target" string, and must check that "database" is one of "is" or "are". The "subject" string ends at the first occurance of either "=is=>" or "=are=>". It is *not* an error for the "object" string to contain either of those substrings. Bots may opt to store the information given by a REPLY request so that future questions may be answered without depending on other bots. It is suggested that bots credit which bot actually knew the information when reporting back to the user. DUNNO ----- (This is not part of the original infobot protocol. And is, as of 2002-02-05, only supported by the mozbot2 Infobot module.) Upon receiving a QUERY message, a bot may, if it has no information on the "subject" in question, reply with a DUNNO message. This message has basically the same form as the QUERY message: :INFOBOT:DUNNO subject The DUNNO message indicates that the bot is not aware of the answer to the question, but would like to be informed of the answer, should the first bot ever find out about it. The "target" string should, as with the QUERY string, be considered opaque. Upon receiving a DUNNO message, there are several possible responses. If the bot is aware of the answer to "subject", then it should treat the DUNNO message as if it was a QUERY message (typically resulting in a REPLY message). This can occur if, for example, another bot has sent a REPLY to the original QUERY before this bot has had the chance to send the DUNNO message. If the first bot still doesn't know the answer, however, it may store the DUNNO request internally. If, at a future time, the bot is informed (either directly by a user or through a REPLY message) about the answer to "subject", then it may send a REPLY message to the bot that sent the DUNNO request, informing the bot of the value it learnt. SPECIAL STRINGS --------------- The "object" string in the REPLY message may contain several special flags. $who If the string contains the string "$who" then, when the string is given to the user, it should be replaced by the name of the user. | Multiple alternative replies may be encoded in one reply, those should be separated by a vertical bar. If the string is prefixed by "" then the string should not be prefixed by "subject is" or "subject are" as usual. The string should be returned via a CTCP ACTION. The string should be taken as the name of another entry to look up. EXAMPLES -------- In these examples, A, B and C are bots, and x, y and z are people. The first example shows a simple case of one bots asking two other bots for help, one of which gives a reply and the other of which says it has no idea. +-------- originator of private message | | +--- target of private message | | V V z -> A: what is foo? A -> z: I have no idea. A -> B: :INFOBOT:QUERY foo A -> C: :INFOBOT:QUERY foo B -> A: :INFOBOT:REPLY foo =is=> bar C -> A: :INFOBOT:DUNNO foo A -> x: B knew: foo is bar A -> C: :INFOBOT:REPLY foo =is=> bar Note how the DUNNO in this case comes after the REPLY and thus is immediately answered. The next example uses . One bot knows the answer to the question as an alias to another word, but when the original bot asks about _that_ word, it is the second bot that can help. z -> A: what is foo? A -> z: I have no idea. A -> B: :INFOBOT:QUERY foo A -> C: :INFOBOT:QUERY foo B -> A: :INFOBOT:REPLY foo =is=> bar C -> A: :INFOBOT:DUNNO foo A -> B: :INFOBOT:QUERY bar A -> C: :INFOBOT:QUERY bar A -> C: :INFOBOT:REPLY foo =is=> bar B -> A: :INFOBOT:DUNNO bar C -> A: :INFOBOT:REPLY bar =is=> baz A -> z: C knew: bar is baz A -> B: :INFOBOT:REPLY bar =is=> baz Note how the credit actually goes to the second bot. A better bot might remember all the bots involved and credit all of them. A better bot might also remember what the original question was and reply "foo is baz" instead of "bar is baz". Next we have some examples of special codes. If we have: foo is bar|baz|foo to you too|foos|$who baz is foo ...then the following are valid responses when asked about foo: foo is bar baz is foo foo to you too * A foos foo is z -- end --