Full XMPP chat support for ejabberd

Last modification: 2015-10-16 20:05:59

Extension can be found at https://github.com/LiveHelperChat/xmpp-chat

Few short notices

  • Standalone and Automated hosting enviroments are supported
  • This enviroment is not for amateurs and requires some ejabberd, nodejs [Optional] and linux administration skills. Read more to find out :)

Basic extension features

  • Online operators monitoring. They do not have to be logged in LHC web interface. Just ejabberd extension can be used to monitor operators status. "mod_lhcping" It can used as standalone ejabberd module.
  • Invitation sending to online site visitor. 
  • Option to see online site visitors. Can be turned off in setttings file.
  • Receive request to chat from site visitors. All online operator resposible for chat department get's message from visitor. The first one who replies becames chat owner. If other operator tries to reply to operator is send message that chat was already accepted by other operator.
  • Support's popup chat also.
  • Support's commands
  • XMPP accounts can be managed from LHC interface.
  • With full XMPP support you can use any standard XMPP client either on desktop/table/mobile

Required configuration for ejabberd in standalone enviroment.

  • One working virtual host. You have to define in ejabberd configuration one virtual host which you will use for your own purposes.
  • Two shared roaster groups 
    • operators
    • visitors
  • "operators" shared roaster group "Displayed Groups" should have 
    • visitors
    • operators
  • "visitors" shared roaster group "Displayed Groups" should be empty

About possible XMPP clients handler from visitors perspective

There is two ways to have it working. Either use nodejs as client and API server or use RPC and strophejs as client from visitors. Personally i suggest do not use nodejs and let visitors connect directly to ejabberd. This way it's just easier to maintaint all the services. Like the only required thing is ejabberd and LHC itself. If you are using RPC also make sure that only LHC can make RPC request. E.g using firewall, or setting listening IP to localhost if ejabberd is on the same server as LHC itself.

Ejabberd required configuration changes for standalone and automated hosting enviroments

  • Disable "mod_offline" (this is required because otherwise if visitor xmpp accound is disconneted it still receives messages from operators). This will avoid duplicate messages.
  • Disable "mod_carboncopy" [Optional] this module it self takes care of you have multiple devices logged under same XMPP account, that operator message sent from one device would be delivered to other devices logged under same XMPP account. This feature particullary couses issue in Monal application on Iphone and duplicates operators messages. So if you experience this issue you can just disable it. Just have in mind that only visitor will receive this message but not other devices logged under same account. But visitor message will be delivered to all logged devices under same XMPP account.
  • Enable "mod_admin_extra" module. ejabberd configuration file may be missing it completely. So under "modules" just add "mod_admin_extra: []"
  • copy "mod_lhc.beam" and "mod_lhcping.beam" to "/opt/ejabberd-15.04/lib/ejabberd-15.04/ebin"
  • In ejabberd.yml add. Don't forget to change URL address
  • If you are using rpc handler make sure you have enabled this module.
  •   - 
         port: 4560
         module: ejabberd_xmlrpc

    ## For security reasons you can force to listen only on localhost also
    ## if you are made it public you can setup auth method for this service
    ## ip: "127.0.0.1"
    ## access_commands:
    ##   xmlrpc_access:
    ##     commands: all
    ##     options: {}

  • If you are using access_commands part you also have to edit "access" by adding 
    xmlrpc_access:
      admin: allow
      all: deny

Standalone enviroment ejabberd configuration example

  mod_lhc: 
   ## Used in automated hosting enviroment
   ahenviroment: false
   basedomain: "example.com"
   ahprotocol: "http://"
   ## Used in standalone enviroment    
   message_address: "http://example.com/xmppservice/processmessage"
    login_address: "http://example.com/xmppservice/operatorstatus"
    logout_address: "http://example.com/xmppservice/operatorstatus"
  mod_lhcping:
    send_pings: true
    ping_interval: 180
    timeout_action: kill
   ## Used in automated hosting enviroment
    ahenviroment: false
    basedomain: "livehelperchat.com"
    ahprotocol: "http://"
    ## Used in standalone enviroment
    ping_address: "http://example.com/xmppservice/operatorstatus"

Automated hosting enviroment ejabberd configuration example

  mod_lhc: 
   ## Used in automated hosting enviroment
   ahenviroment: true
   basedomain: "example.com"
   ahprotocol: "http://"
   ## Used in standalone enviroment    
   message_address: "http://example.com/xmppservice/processmessage"
    login_address: "http://example.com/xmppservice/operatorstatus"
    logout_address: "http://example.com/xmppservice/operatorstatus"
  mod_lhcping:
    send_pings: true
    ping_interval: 180
    timeout_action: kill
   ## Used in automated hosting enviroment
    ahenviroment: true
    basedomain: "livehelperchat.com"
    ahprotocol: "http://"
    ## Used in standalone enviroment
    ping_address: "http://example.com/xmppservice/operatorstatus"

That's all with ejabberd part.

Live Helper Chat XMPP Service extension installation

  • Make sure your PHP version has XML-RPC extension. http://php.net/manual/en/book.xmlrpc.php
  • copy "xmppservice" to extension folder
  • execute install.sql from doc folder
  • copy settings/settings.ini.default.php to  settings/settings.ini.php
  • edit settings in settings/settings.ini.php file
  • active extension in main settings.ini.php file E.g 'extensions' => array ('xmppservice')
  • Clear cache from back office. There should be new item in top menu "Extra modules"
  • In automated hosting enviroment you have to activate extension in both manager and client instances
  • Example configuration for standalone enviroment if handler is nodejs

<?php 

return array(
    'ahosting' => false,                                                           // Is it automated hosting enviroment? At the moment keep it false untill automated hosting will be supported
    'secret_key' => ''<secret_key>",                                   // Secret key, node will accept commands only if this key is provided. It must match in nodejs settings defined secret key.
    'subdomain' => '',                                                             // Just keep it empty. It get's filled automatically in automated hosting enviroment
    'enabled' => true,                                                              // Is this module enabled
    'online_visitors_tracking' => true,                              // Should each online visitor get it's own xmpp account?
    'xmpp_host' => 'xmpp.livehelperchat.com',               // E.g xmpp.livehelperchat.com
    'node_api_server' => 'http://127.0.0.1:4567',          // E.g http://127.0.0.1:4567', Address where nodejs server is running
    'host_login' => 'localhost',                                             // Host where node server should login as user
    'debug' => false,                                                                // Write exceptions in cache/default.log use it for debuging purposes
    'handler' => 'node',
    'rpc_server' => '', 
    'bosh_service' => '',
   'use_notification' => "false",
   'prebind_host' => ''
);

?>

  • Example configuration for automated hosting enviroment if nodejs as handler is used

<?php 

return array(
    'ahosting' => true,                                                           // Is it automated hosting enviroment? At the moment keep it false untill automated hosting will be supported
    'secret_key' => ''<secret_key>",                                   // Secret key, node will accept commands only if this key is provided. It must match in nodejs settings defined secret key.
    'subdomain' => '',                                                              // Just keep it empty. It get's filled automatically in automated hosting enviroment
    'enabled' => true,                                                               // Is this module enabled
    'online_visitors_tracking' => true,                               // Should each online visitor get it's own xmpp account?
    'xmpp_host' => 'xmpp.livehelperchat.com',               // E.g xmpp.livehelperchat.com
    'node_api_server' => 'http://127.0.0.1:4567',          // E.g http://127.0.0.1:4567', Address where nodejs server is running
    'host_login' => 'localhost',                                             // Host where node server should login as user
    'debug' => false,                                                                // Write exceptions in cache/default.log use it for debuging purposes   
    'handler' => 'node',
    'rpc_server' => ''
    'bosh_service' => ''',
   'use_notification' => "false",
   'prebind_host' => ''
);

?>

  • Example configuration for standalone enviroment if handler is rpc

<?php 

return array(
    'ahosting' => false,                                                           // Is it automated hosting enviroment? At the moment keep it false untill automated hosting will be supported
    'secret_key' => ''<secret_key>",                                   // Secret key, node will accept commands only if this key is provided. It must match in nodejs settings defined secret key.
    'subdomain' => '',                                                             // Just keep it empty. It get's filled automatically in automated hosting enviroment
    'enabled' => true,                                                              // Is this module enabled
    'online_visitors_tracking' => true,                              // Should each online visitor get it's own xmpp account?
    'xmpp_host' => 'xmpp.livehelperchat.com',               // E.g xmpp.livehelperchat.com
    'node_api_server' => 'http://127.0.0.1:4567',          // E.g http://127.0.0.1:4567', Address where nodejs server is running
    'host_login' => 'localhost',                                             // Host where node server should login as user
    'debug' => false,                                                                // Write exceptions in cache/default.log use it for debuging purposes
    'handler' => 'rpc',
    'rpc_server' => 'http://example.com:4560', 
    'bosh_service' => ''ws://'.$_SERVER['HTTP_HOST'].'/websocket'',
   'use_notification' => "false",
   'prebind_host' => ''
);

?>

  • Example configuration for automated hosting enviroment if rpc as handler is used

<?php 

return array(
    'ahosting' => true,                                                           // Is it automated hosting enviroment? At the moment keep it false untill automated hosting will be supported
    'secret_key' => ''<secret_key>",                                   // Secret key, node will accept commands only if this key is provided. It must match in nodejs settings defined secret key.
    'subdomain' => '',                                                              // Just keep it empty. It get's filled automatically in automated hosting enviroment
    'enabled' => true,                                                               // Is this module enabled
    'online_visitors_tracking' => true,                               // Should each online visitor get it's own xmpp account?
    'xmpp_host' => 'xmpp.livehelperchat.com',               // E.g xmpp.livehelperchat.com
    'node_api_server' => '',                                                  // E.g http://127.0.0.1:4567', Address where nodejs server is running
    'host_login' => 'localhost',                                             // Host where node server should login as user
    'debug' => false,                                                                // Write exceptions in cache/default.log use it for debuging purposes
    'handler' => 'rpc',
    'rpc_server' => '', 
    'bosh_service' => '',
   'use_notification' => "false",
   'prebind_host' => ''
);

?>

In automated hosting enviroment you have to do the following things also. Make sure that nodejs server for ejabberd is running.

  • Update to recent version of automated hosting 
  • Being in manager lhc_web folder execute
    • php cron.php -s site_admin -e instance -c cron/update_structure | Updates instrance main table structure
    • php cron.php -s site_admin -e instance -c cron/update_instances | Updates instances tables
    • php cron.php -s site_admin -e instance -c cron/extensions_update | Installs required tables from extensions and creates shared roaster for each instance

NodeJS server installation and configuration [Optional if node handler is used]

This is the final part of installation and NodeJS is required to act as gateway between ejabberd and XMPP Service extension. I suggest to have it running on the same server where ejabberd is running. It uses "ejabberdctl" to manage accounts. And also act's on behalf of online visitors as client to XMPP.

  • edit settings in settings.js file
  • run server by issueing node server.js
  • You may also want to write some service for systemctl to have it running in the background.
  • If it throws that it's missing some nodejs module just do npm install

Configuration in LHC back office interface

  • To enable module itself is not enough just activate it in extension settings. You have to enable module itself in XMPP module options. Just check "XMPP Enabled". Without this option enable you won't receive any visitors request.
  • Also to be able to see online visitors you have to enable it also in the same configuraiton window by checking "Track online visitors"

Configuration in LHC in automated hosting enviroment

There is few things you have to do in fresh instance.

  • You have to enable XMPP itself in XMPP module settings option
  • Next you have to create an XMPP account. Each XMPP account consists of <username>.<instance address>@xmpp.<maindomain>.com
  • E.g remdex.demo@xmpp.livehelperchat.com
  • During account creation process it has to be associated with operator
  • Everything else will work just flawlesly. Port 5228 for XMPP

Additional information

I also recommend to read https://github.com/LiveHelperChat/xmpp-chat/blob/master/README.md

 

How to debug?

  • enable debug in nodejs server settings.js file is option to enable debut output
  • enable debug in extension settings file. All exceptions will be written to cache/default.log file.
  • Enable general LHC debug output and disable cache.

FAQ/Tips?

  • do not set in ejabberd config address where to send operators statueses to https, seems ejabberd cannot send https request, so just use http

Have fun. Please let me know how it goes :)

 

 

Support project

Developing application takes a lot of time. You can support application by donating. There is no company behind this application and it takes away my free time. Every donation matters and does not matter how small it is!


Paypal, one time donation
Monthly donation
Bitcoin
Skrill
remdex@gmail.com


comments powered by Disqus