Scroll to navigation

JABBER-QUERYBOT(1p) User Contributed Perl Documentation JABBER-QUERYBOT(1p)

NAME

jabber-querybot - a modular perl jabber bot

DESCRIPTION

jabber-querybot connects a jabber account and wait for messages. If a message comes in, it forward it to your self programmend modul. The return string of your module, jabber-querybot send it back to the jabber sender.

It is designed to be re-usable and to make it easy to write small Jabber bots that do one thing and do it well. A simple concept with a lot of examples and experiences are implemented.

1. Create a jabber account on a jabber-server around

2. Create a bot application:

 cd examples
 cp Querymodule.pm /etc/jabber-querybot/Mybot.pm
 cd /etc/jabber-querybot
 ln -s Mybot.pm Querymodule.pm

Modify login parameters to your jabber-bot-account

vim Mybot.pm

  our $hostname        = "swissjabber.ch";
  our $user            = "";
  our $password        = "";
  our $ident           = "Testbot";
  our $bot_admin       = "\@swissjabber.ch";
  our $port            = "5222";
  our $timeout         = "5";
  our $service_name    = "$user\@$hostname";
  our $bot_description = "Bot help title
  Bot description";

For each jabber message, jabber-querybot will execute sub run_query, that you can write here your application.

You can control how your jabber response will be:

  • error = error message stanza
  • presence = error as presence stanza
  • ignore = ignore message

OPTIONS

jabber-querybot has a lot of variables which you can easy modify for what you need:

querystatus

$querystatus = [ 0 | 1 ]

  • 0 = Bot will not proceed any incoming jabber messages.
  • 1 = Bot will proceed incoming messages.

penalty_status

If the bot has too much workload, it goes to penalty status and wait some time until his status change back to normal.

$timer_reconnect_default = 21600

Every 21600 seconds (6 hours) the bot will shutdown automatically, wait 10 seconds and starting up again.

$timer_auto_query = 0

If you set in your module this variable to 60, the bot will every 60 seconds call the function run_auto_query() which you may use for several things.

System load

If your systems load is >=6, this bot will shutdown the jabber connection and check every 10 seconds systems load. If load <=2, bot will start over.

EXAMPLES

/usr/share/doc/jabber-querybot/examples/Testbot.pm

FILES

/etc/jabber-querybot/Querymodule.pm

/usr/bin/jabber-querybot

RESOURCES

http://github.com/micressor/jabber-querybot/

METHODS

InMessage()

An incoming jabber message to the bot will hook this function.

Read parameters of incoming stanza

Decode utf8 string

increment timer overload and do not process message if bot is overloaded.

Ignore message if it is from myself

Be sure, that it is not a message from another transport

Check any systemcommands for the bot

If the bot has sleeping status, change it to work

We process only normal text or chat type jabber messages

  • And now we give the real text string which was incoming to the bot via run_query().
  • If run_query() say us 'ignore` we do a log entry and do not answer via jabber to the user.

If run_query() says 'error` we send a jabber error stanza wiht the status message from run_query() back to the user.

If there was no error, we update the statistic vars and send the answer from run_query() back to the jabber user.

connect_server()

This function connects to the jabber server with the given credentials from Querymodule.pm.

Set the call back functions. This functions will be executed if a message of the types <message/> <iq/> or <presence/> are incoming.

Stop()

Shutdown jabber connection and exit main program

disconnect_server()

Only disconnect from the jabber-server.

reconnect_server()

Reconnect and create a log entry.

InIQ()

We do not proceed any iq (information query), this is only for statisic.

InPresence()

  • Increment timer overload
  • Do not process message if we are overloaded penalty_handler().

We have a problem in Net::Jabber. An incoming message with a ` in resource blocks the bot. We will hotfix that for the moment.

A subscription type `subscribe` is incoming. Send `subscribed` tho the user and say hello ;)

Send presence to user

Remove subscription if a user remove this bot from his roster

sendPresence()

Send presence information to user

systemcommands()

If user type '!help` send a help instruction to the user

Send statistic information to the user if he types '!status`

  • Is it a bot command?
  • Is the bot command from the bot admin? If not, send "not allowed"
  • '!shutdown` will shutdown your bot via jabber invoke.
  • '!query off` turn off queries
  • '!query on` turn on queries

get_barejid()

Remove resource id from a jabber id.

calcualte_stats()

Calculate message statistics

jabber_set_presence()

Set new presence if we have another presence status or we have set the force flag (for transport presence).

jabber_send_message()

This function send all jabber messages which are outgoing from the jabber-querybot.

set_wakeup_mode()

Set jabber presence via jabber_set_presence()

penalty_handler()

This function checks if the bot is overloaded with incoming mesages and reject if it is. Two times that's ok so 2:1 because while in main.

Bot admin got everytime an answer.

jabber_add_footer()

Add footer to the processed message.

calcualte_elapsed_time()

Calculate elapsed worktime for a query

sendError()

sendError($message, $from, $to, 404, "text");

system_load_check()

  • Calculate system load
  • If load is too high shutdown bot.
  • If load is ok, starting up bot

connect_bot()

Connect bot and initialize all timers.

check_before_start()

Check configuration variables in Querybotmodule.pm and give answer if anything does not match or is missing.

COPYRIGHT AND LICENSE

Copyright (C) 2009-2012 Marco Balmer <marco@balmer.name>

The Debian packaging is licensed under the GPL, see `/usr/share/common-licenses/GPL-3'.

2021-01-09 perl v5.32.0