Net::Jabber::Bot(3pm)

💖 NAME 💖

Net::Jabber::Bot — Automated Bot creation with safeties ✨

okay so bestie, this is the manual page for Net::Jabber::Bot (it's a Perl module, it lives at Net::Jabber::Bot(3pm) in the user contributed perl docs). It makes bots. Safely. No cap.

---

🌸 VERSION 🌸

Version 3.01 💅

---

✨ SYNOPSIS ✨

Program design: this is a Moo based Class. 🐮

The whole idea behind this module is that somebody making a bot should not actually have to know a ton about how the Jabber protocol works in order to use it. It also lets us abstract away all the stuff that gets bot makers into trouble. Basically the object is out here protecting coders from their own mistakes. 🛡️

Everything you should have to know and define in your program, outside of the object itself, is:

1. Config — where to connect, how often to do things, timers, etc.
2. A subroutine that the bot object calls when a new message comes in.
3. A subroutine that the bot object calls every so often so you can do background activities (check logs, monitor web pages, etc.).

As of right now, the object has the following enforced safeties, as long as you don't override safety mode:

1. Limits messages per second, configurable at start up, (Max is 5 per second) by requiring a sleep timer in the message sending subroutine each time one is sent. 😴
2. Endless loops of responding to self prevented by now allowing the bot message processing subroutine to know about messages from self.
3. Forum join grace period to prevent bot from reacting to historical messages.
4. Configurable aliases the bot will respond to per forum.
5. Limits maximum message size, preventing messages that are too large from being sent (largest configurable message size limit is 1000).
6. Automatic chunking of messages to split up large messages in message sending subroutine.
7. Limit on messages per hour. (max configurable limit of 125) Messages are visible via log4perl, but not ever be sent once the message limit is reached for that hour.

---

🔥 FUNCTIONS 🔥

🆕 new 🆕

Minimal:

my $bot = Net::Jabber::Bot->new(
    server               => 'host.domain.com', # Name of server when sending messages internally.
    conference_server    => 'conference.host.domain.com',
    port                 => 522,
    username             => 'username',
    password             => 'pasword',
    safety_mode          => 1,
    message_function     => \&new_bot_message,
    background_function  => \&background_checks,
    forums_and_responses => \%forum_list
);

All options:

my $bot = Net::Jabber::Bot->new(
    server                  => 'host.domain.com', # Name of server when sending messages internally.
    conference_server       => 'conference.host.domain.com',
    server_host             => 'talk.domain.com', # used to specify what jabber server to connect to on connect?
    tls                     => 0,                    # set to 1 for google
    ssl_ca_path             => '',  # path to your CA cert bundle
    ssl_verify              => 0,   # for testing and for self-signed certificates
    connection_type         => 'tcpip',
    port                    => 522,
    username                => 'username',
    password                => 'pasword',
    alias                   => 'cpan_bot',
    message_function        => \&new_bot_message,
    background_function     => \&background_checks,
    loop_sleep_time         => 15,
    process_timeout         => 5,
    forums_and_responses    => \%forum_list,
    ignore_server_messages  => 1,
    ignore_self_messages    => 1,
    out_messages_per_second => 4,
    max_message_size        => 1000,
    max_messages_per_hour   => 100
);

Set up the object and connect to the server. Hash values are passed to new as a hash. 🫶

The following initialization variables can be passed. Only marked variables are required (TODO) 🙈

• safety_mode — safety_mode = (1,0)

Determines if the bot safety features are turned on and enforced. This mode is on by default. Many of the safety features are here to assure you do not crash your favorite jabber server with floods, etc. DO NOT turn it off unless you're sure you know what you're doing (not just Sledge Hammer certain).

• server — Jabber server name.
• server_host — Defaults to the same value set for 'server' above. This is where the bot initially connects. For google for instance, you should set this to 'gmail.com'.
• conference_server — Conference server (usually conference.$server_name).
• port — Defaults to 5222.
• gtalk — Boolean value. defaults to 0. Set to 1 for Google Talk connections. This automatically enables TLS and sets server_host to 'gmail.com' (unless you provide your own server_host).
• tls — Boolean value. defaults to 0. for google, it is know that this value must be 1 to work.
• ssl_ca_path — The path to your CA cert bundle. This is passed on to XML::Stream eventually.
• ssl_verify — Enable or disable server certificate validity check when connecting to server. This is passed on to XML::Stream eventually.
• connection_type — defaults to 'tcpip' also takes 'http'.
• username — The user you authenticate with to access the server. Not full name, just the stuff to the left of the @...
• password — password to get into the server.
• alias — This will be your nickname in chat rooms. The XMPP resource (used for login and presence) defaults to "alias_hostname_pid" to ensure uniqueness across multiple bot instances.
• forums_and_responses — A hash ref which lists the forum names to join as the keys and the values are an array reference to a list of strings they are supposed to be responsive to. The array is order sensitive and an empty string means it is going to respond to all messages in this forum. Make sure you list this last. 👑

The found 'response string' is assumed to be at the beginning of the message. The message_funtion function will be called with the modified string.

alias = jbot:, attention:

example1:

message: 'jbot: help'

passed to callback: 'help'

• message_function — The subroutine the bot will call when a new message is received by the bot. Only called if the bot's logic decides it's something you need to know about. 📬
• background_function — The subroutine the bot will call when every so often (loop_sleep_time) to allow you to do background activities outside jabber stuff (check logs, web pages, etc.)
• loop_sleep_time — Frequency background function is called.
• process_timeout — Time Process() will wait if no new activity is received from the server.
• ignore_server_messages — Boolean value as to whether we should ignore messages sent to us from the jabber server (addresses can be a little cryptic and hard to process).
• ignore_self_messages — Boolean value as to whether we should ignore messages sent by us.

BE CAREFUL if you turn this on!!! Turning this on risks potentially endless loops. If you're going to do this, please be sure safety is turned on at least initially. 💀

• auto_subscribe — Boolean value controlling whether the bot automatically accepts presence subscription requests from any JID. Defaults to 1 (enabled) for backward compatibility. Set to 0 to ignore subscription requests, which prevents unknown users from tracking the bot's online status.
• out_messages_per_second — Limits the number of messages per second. Number must be > 0

default: 5

safety: 5

• max_message_size — Specify maximimum size a message can be before it's split and sent in pieces.

default: 1,000,000

safety: 1,000

• max_messages_per_hour — Limits the number of messages per hour before we refuse to send them

default: 125

safety: 166

---

🚪 JoinForum 🚪

Joins a jabber forum and sleeps safety time. Also prevents the object from responding to messages for a grace period in efforts to get it to not respond to historical messages. This has failed sometimes. 😭

NOTE: No error detection for join failure is present at the moment. (TODO)

---

⚙️ Process ⚙️

Mostly calls it's client connection's "Process" call. Also assures a timeout is enforced if not fed to the subroutine. You really should not have to call this very often. You should mostly be calling Start() and just let the Bot kernel handle all this. 🧚

---

🏁 Start 🏁

Primary subroutine save new called by the program. Runs a loop of:

1. Process
2. If Process failed, Reconnect to server over larger and larger timeout
3. run background process fed from new, telling it who I am and how many loops we have been through.
4. Enforce a sleep to prevent server floods.

The loop runs until Stop() is called. Returns the loop iteration count. 🔁

---

🛑 Stop 🛑

$bot->Stop();

Signals the Start() loop to exit after the current iteration completes. Typically called from within the background_function or message_function callback.

---

🔌 ReconnectToServer 🔌

You should not ever need to use this. the Start() kernel usually figures this out and calls it.

Internal process:

1. Disconnects
3. Re-initializes

---

✂️ Disconnect ✂️

Disconnects from server if client object is defined. Assures the client object is deleted.

---

📡 IsConnected 📡

Reports connect state (true/false) based on the status of client_start_time.

---

🙅 _process_jabber_message - DO NOT CALL 🙅

Handles incoming messages.

---

📜 get_responses 📜

$bot->get_responses($forum_name);

Returns the array of messages we are monitoring for in supplied forum or replies with undef.

---

🙅 _jabber_in_iq_message - DO NOT CALL 🙅

Called when the client receives new messages during Process of this type.

---

…and that's only part one bestie — part 2 is loading, stay tuned 💅

_jabber_presence_message — DO NOT CALL 🛑

okay so bestie, this one is literally labelled DO NOT CALL for a reason. It gets called when the client receives new presence messages during Process. Mostly we are just pushing the data down into the client DB for later processing. so don't touch it, mkay? 💅

respond_to_self_messages

$bot->respond_to_self_messages($value = 1);

Tells the bot to start reacting to it's own messages if non-zero is passed. Default is 1.

get_messages_this_hour

$bot->get_messages_this_hour();

Returns the number of messages sent so far this hour. hourly tea ☕✨

get_safety_mode

Validates that we are in safety mode. Returns a bool as long as we are an object, otherwise returns undef.

SendGroupMessage

$bot->SendGroupMessage($name, $message);
$bot->SendGroupMessage($name, $message, $from);

Tells the bot to send a message to the recipient room name.

$from is an optional JID to set as the sender of the message. Note that most XMPP servers will not allow spoofing the from field and may reject the message or disconnect the client.

SendPersonalMessage

$bot->SendPersonalMessage($recipient, $message);
$bot->SendPersonalMessage($recipient, $message, $from);

How to send an individual message to someone.

$recipient must read as user@server/Resource or it will not send. fr fr, no resource no send.

$from is an optional JID to set as the sender of the message. Note that most XMPP servers will not allow spoofing the from field and may reject the message or disconnect the client.

SendJabberMessage

$bot->SendJabberMessage($recipient, $message, $message_type, $subject, $from);

The master subroutine to send a message. Called either by the user, SendPersonalMessage, or SendGroupMessage. Sometimes there is call to call it directly when you do not feel like figuring you messaged you. Assures message size does not exceed a limit and chops it into pieces if need be.

NOTE: non-printable characters (unicode included) will be replaced with a dot before sending to the server. Newlines (LF and CR) are preserved so that multiline messages work correctly.

s/[^\r\n[:print:]]+/./xmsg

SetForumSubject

$bot->SetForumSubject($recipient, $subject);

Sets the subject of a forum. 🎀

ChangeStatus

$bot->ChangeStatus($presence_mode, $status_string);

Sets the Bot's presence status. $presence mode could be something like: (Chat, Available, Away, Ext. Away, Do Not Disturb). $status_string is an optional comment to go with your presence mode. It is not required.

GetRoster

$bot->GetRoster();

Returns a list of the people logged into the server. I suspect we really want to know who is in a particular forum right? In which case we need another sub for this. 👀

GetStatus

my $status = $bot->GetStatus($jid);

Returns the presence status of the given JID. Possible return values are "unavailable" (if not connected or JID not found in the presence database), "available" (if present with no specific show value), or the XMPP show value (e.g. "away", "xa", "dnd", "chat").

AddUser

$bot->AddUser($jid);

Sends a subscription request to the given JID and auto-approves their reciprocal subscription. This adds the user to the bot's roster and allows mutual presence visibility.

RmUser

$bot->RmUser($jid);

Sends an unsubscribe request for the given JID and revokes their subscription to the bot's presence. This effectively removes the user from the bot's roster.

---

👑 AUTHOR 👑

Todd Rinaldo "<toddr@cpan.org>"

🐛 BUGS 🐛

Please report any bugs or feature requests through the GitHub issue tracker at https://github.com/cpan-authors/perl-net-jabber-bot/issues.

🆘 SUPPORT 🆘

You can find documentation for this module with the perldoc command.

perldoc Net::Jabber::Bot

You can also look for information at:

• Metacpan https://metacpan.org/pod/Net::Jabber::Bot
• GitHub https://github.com/cpan-authors/perl-net-jabber-bot

💖 ACKNOWLEDGEMENTS 💖

✨ crickets ✨ — this section is empty in the original, bestie. Just vibes.

📜 COPYRIGHT & LICENSE 📜

Copyright 2007 Todd E Rinaldo, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole entire manpage, bestie! this was Perl v5.40.1, dated 2026-04-05, from Net::Jabber::Bot(3pm). stay sliving 💅✨