The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Bot::Backbone::Service::JabberChat - Connect and chat with a Jabber server

VERSION

version 0.160630

SYNOPSIS

  service jabber_chat => (
      service  => 'JabberChat',
      username => 'bot',
      domain   => 'example.com',
      resource => 'coolbot',
      password => 'secret',
  );

DESCRIPTION

Connects to and chats directly with other users and chat groups using a Jabber (XMPP) server.

ATTRIBUTES

username

This is the username (or localpart in XMPP parlance) to use when connecting to the Jabber server. E.g., if your bot's login name is bot@example.com, the username is "bot".

domain

This is the domain (or domainpart) to use when connecting to the Jabber server. E.g., f your bot's login mame is bot@example.com, the domain is "example.com".

group_domain

This is the domain to contact for group chats. Normally, this is the same as "domain", but with "conference." tacked on at the front.

resource

This is a the resourcepart of your login name. You may not really care what this is set to, but it shows up in some chat clients. By default it will be set to "backbone-bot", but you can set it something else, if you like.

password

This is the password to use when logging in to the Jabber server.

host

This is the host to contact to login. If not set, the "domain" will be used.

If you run your bot on Google Talk, you will probably want this set to talk.google.com.

port

This is the port to connect. If you do not set it to anything, the default of 5222 will be used.

connection_args

These are additional connection arguments to pass to the XMPP connector. See AnyEvent::XMPP::Connection for a list of available options.

debug_client

Set to true if you want to enable debugging. This uses the built-in debug option of AnyEvent::XMPP::Client. If you want more control over how debugging is handled, see "xmpp_debug_recv_callback" and "xmpp_debug_send_callback".

xmpp_debug_send_callback

xmpp_debug_recv_callback

These attributes may be set to a code reference that will be called with every message received from the XMPP server. This could be useful for troubleshooting certain kinds of problems in cases where you'd like more control over the output than you get from "debug".

Each will be called like this:

  $callback->($service, $xmpp_client, $account, $data);

The $service is this object. The $xmpp_client will be the same object as is returned by "xmpp_client". The $account is the AnyEvent::XMPP::Account the bot has connected as (useful for getting the jid). And the $data is the raw XML being sent or received.

xmpp_client

This is the XMPP client object for organizing connections.

xmpp_disco

This is the XMPP discovery extension helper.

xmpp_muc

This is the XMPP multi-user chat extension helper.

session_ready

Once the connection has been made and is ready to start sending and receiving messages, this will be set to true.

group_options

This is a list of multi-user chat groups the bot has joined or intends to join once "session_ready" becomes true.

error_callback

This callback is executed in case of an error. It will receive two arguments like so:

  $callback->($service, $message);

The first argument is the Bot::Backbone::Service::JabberChat object and the second is the error message the server sent. The default handler uses warn to log the message to the console.

METHODS

jid

This assembles a full JID (Jabber ID) using the "username", "domain", and "resource".

group_jid

  my $group_jid = $chat->group_jid('bar');

Given a short group name, returns the bare JID for that group.

xmpp_account

Returns the XMPP account object.

xmpp_connection

Returns teh XMPP connection object.

xmpp_room

  my $xmpp_room = $chat->xmpp_room('qux');

Returns the XMPP room object for the named room.

xmpp_contact

  my $xmpp_contact = $chat->xmpp_contact('user@example.com/blah');

Given a JID, returns the XMPP contact object for that user.

initialize

Connects to the Jabber server and registers the events for receiving messages from it.

join_group

Asks to join the named multi-user chat groups on the Jabber server. If "session_ready" is false, the chat service will only record a desire to join the group. No actual join will take place. Once the session becomes ready, all pending groups will be joined.

If the session is ready already, then the group will be joined immediately.

EVENT HANDLERS

got_direct_message

Whenever someone sends the bot a direct message throught eh Jabber server, this handler is called. It builds a Bot::Backbone::Message and then passes that message on the associated chat consumers and the dispatcher.

is_to_me

  my $bool = $self->is_to_me($user, \$text);

Given the user that identifies the bot in a group chat and text that was just sent to the chat, this detects if the message was directed at the bot. Normally, this includes messages that start with the following:

  nick: ...
  nick, ...
  nick- ...

It also includes suffix references like this:

  ..., nick.
  ..., nick

and infix references like this:

  ..., nick, ...

If you want something different, you may subclass service and override this method.

Note that the text is sent as a reference and can be modified, usually to remove the nick from the message so the bot does not have to worry about that.

got_group_message

Whenever someone posts to a conference room that the bot has joined, this method will be called to create a Bot::Backbone::Message and pass that message on to chat consumers and the dispatcher.

send_message

Sends a message to the Jabber server for a direct chat or group.

AUTHOR

Andrew Sterling Hanenkamp <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Qubling Software LLC.

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