User Guide

This is a guide for Jabber/XMPP end-users. Explanation what Jabber is, what XMPP is and how to use it.

Jabber/XMPP introduction

Jabber/XMPP is instant messaging technology.

All Jabber/XMPP servers are connected in one global communication network so you will be able to send messages to friends who have accounts on other Jabber servers.

This is very much like sending e-mail but the difference between Jabber and e-mail is the same as difference between post a traditional mail and talking on the phone.

All messages send through Jabber are sent instantly and you can also receive response instantly. More over you can see whether you mate is online and available for talking or not.

There also other similar technologies to Jabber like Yahoo, MSN or ICQ. There are, however quite a few differences.

Jabber is an open standard which means everybody can know how it works, everybody can implement own software connecting to the network both client and server side.

And the server side is actually the biggest difference and advantage. Many companies have offices in different location and such instant messaging technology might be very useful for employees for communication. But companies are not so keen to let confidential discusion go outside the company. Especially it is not very secure to leave such information on to third party public servers.

Jabber on the other side allows you to deploy server in your own company network. So employees can talk securely and all information go through company secure network. Of course if offices are located in different places or countries then all messages are transmitted over the public network - Internet. But Jabber supports SSL/TLS - secure connections which helps you protect your discussion.

And then if your employees need to contact customer outside your company whole discussion can go through your server and server located on customer side.

There are many other scenarios and use cases but I hope that brief introduction gives you idea what is the difference and advantage of Jabber technology.

Installing Minichat on your website

We have made Minichat available just to demonstrate new stuff we are working on, to do some tests and collect your opinions. The feedback we have got exceeded our expectations. The most common question was: Can I/how can I install it on my website?

Installing the Minichat on your website is very simple so I am putting here instructions for all of you who want to include the Minichat client on your website and allow visitors to chat with you.

Just to remind you - this code is still under development and will be updated and changed very often. It may even stop working temporarily or permanently. We can even intentionally block certain users or IP addresses if we discover any abuse. If you are ready for this and still want to have it continue reading...

First thing to know: Minichat will work with tigase.org Jabber/XMPP server only right now.
This is not because some limitations in the code or special non-standard implementation. This is to simplify deployment of the service. If you wanted Minichat to connect to a different domain/Jabber server the installation would be much harder, involving Apache proxy_mod installation, configuration and maybe Bosh component/server deployment.

Second thing to know: Minichat connects to the server as anonymous user. To avoid sending spam the anonymous user can only send messages to users within the single Jabber/XMPP server. It means you can configure Minichat to send messages to user@jabber.org but Tigase server won't deliver those messages.

Instructions:

Register an account on the www.tigase.org website. For purpose of this guide let's say the account name is: your-account. The the Jabber ID will be: your-account@tigase.org.
Note! There seems to be confusion about this so let me highlight this. You create an account on the www.tigase.org website but your Jabber account is in domain: tigase.org.
Setup Jabber/XMPP client of your choice to connect to the Tigase server in domain: tigase.org. Note you must allow plain text login. TLS is supported so the connection is secure and your password is still save.
There are a few ways for adding the client to the website but you always put startup parameters as URL query to the client link. Following parameters are possible:
- jid=your-account@tigase.org tells the client who you want website visitors talk to. Normally you put there your own account.
- name=YourName screen name (displayed name) of your account.
- domain=tigase.org domain name you want the Minichat to connect to. At the moment only tigase.org is allowed.
- autologin=true determines whether the Minichat client automatically connects to the server when the page is loaded or waits for the visitor to click on the title bar.
1. The first way described is to put the client in exactly the same way as it is on the www.tigase.org website. The chat window is always visible but the client is not connected to the server until someone clicks on the Minichat title bar. Include in your page following code:
```
<iframe 
  src="http://minichat.tigase.org/MesComp.html?jid=your-account@tigase.org&name=YourName&domain=tigase.org" 
  width="220px" height="250px" frameborder="0"></iframe>
```
2. Very similar to the first option. The only difference is that the client automatically connects to the server and is ready for chatting without need to click on the title bar. Include following code:
```
<iframe 
  src="http://minichat.tigase.org/MesComp.html?jid=your-account@tigase.org&name=YourName&domain=tigase.org&autologin=true"
  width="220px" height="250px" frameborder="0"></iframe>
```
3. The third option is the least intrusive but the most complex to install. It puts a small, clickable image with text on your page: Click to chat with.... When the website visitor clicks the new window pops up with the Minichat which automatically connects to the server. You need to put some code in the web page header:
```
<link rel="stylesheet" type="text/css" 
  href="http://minichat.tigase.org/minichat.css"/>
<link rel="stylesheet" type="text/css" 
  href="http://minichat.tigase.org/mygwt-all.css" />
```
  And similar to other configurations code in the web page body:
```
<iframe
  src="http://minichat.tigase.org/Runner.html?jid=your-account@tigase.org&name=YourName&domain=tigase.org"
  width="220px" height="250px" frameborder="0"></iframe>
```

Enjoy and send us your comments...

How to use Tigase service

This article describes how to use tigase.org service for instant communication.

You have to install and run Jabber client application to use the service.

Short instructions:

Usually you just need to enter Jabber user name of the form: user@tigase.org. Your Jabber client should take care of all other things as our service doesn't need any special settings.

If you don't have account on tigase.org server yet just tick the option to register new account. That's it!

Long instructions:

Good news is that there are many programs to choose from which allow you to communicate through our server. So you can pick up your favorite application or use existing one if it is compatible and start using our service.

All clients presented below support multiple accounts on Jabber servers. What it means is that you can have a few Jabber accounts on different Jabber servers and you can still use just one program to connect to all of them at the same time.

Full list of all known Jabber client is very long you can obviously try them all but below is a selection which is recommended by Tigase team.
The selected programs might not be the best choice for you but these programs have been tested and we can offer help with using them.
Here is a list of recommended instant messaging clients:

Psi: Pure Jabber client. Although it supports only Jabber network it is very user friendly and comfortable program. It works on most popular operating systems like Linux, MS Windows and Apple MacOS X.
Gajim: This is another Jabber only client. Very user friendly works on most of Linux distributions, FreeBSD and MS Windows.
Gaim: This is not just a Jabber client. This kind of applications are called multicommunicator as apart from Jabber it supports also many other instant messagin networks like: AIM/ICQ, MSN, Yahoo, Gadu-Gadu, IRC and a few others. So it is especially convenient if you have friends using other messaging networks. Gaim works on most Linux distributions and on MS Windows.
Kopete: This is KDE component and although it works only on Linux based system it also support many, most popular instant messaging systems apart from Jabber like: AIM, Gadu-Gadu, ICQ, IRC, MSN, Yahoo.

Install Jabber client of your choice and setup it for Tigase account:

Configuration instructions for Psi

Psi - Initial configuration

The first time you run Psi you see screen like this:

To connect to tigase.org server we need to configure the program. Below are step-by-step instructions for novices how to setup Psi.

Note! Click on the image to see it in full size.

Psi can connect to many Jabber servers at the same time so we have to identify each connection somehow. So the first thing to do is to assign name to the connection we just creating. As we are going to define connection to tigase.org server let's name it just: Tigase.

Note! At the moment you can register account through the Web site only. This is single account for both services: Drupal Web site and Jabber in tigase.org domain. If you want to have a Jabber account on tigase.org server go to registration page, un-tick "Register new account" here and go to the point no 5. You can use guide in points 2-4 though to register Jabber account on any other Jabber server.
When you press Add button you will see next window where you can enter your Jabber account details:
Invent your user name for account on Tigase server. Let's assume your user name is: frank. Jabber ID however consists of 2 parts - your user name and server address. Exactly the same as e-mail address. As you are registering account on tigase.org server so you have to enter in this field: frank@tigase.org. Next enter password of your choice and click Register button.
On successful registration you will receive confirmation message and you should see window like this:

It may happen that somebody earlier registered account with the name you selected for yourself. Then you will receive error message. You have to select another user name and try to register again.
After clicking OK button you will see window with your connection and account setup. You can stick with default values for now.

Just click Save button and this window closes.
Now you have your account configured and ready to use but you are still off-line. You can find it out whether you are on-line or off-line looking at the bottom of main Psi window. You can see there Offline text.

Click on this Offline text and you can see list of possible options. Just select Online.

Now you are connected!

Well, you are connected but how to talk to other people? How to add friends to the contact list?

You can send a message to your friends just stright away using Psi menu option New blank message. It is much more convenient however if you could see who of your friends is online and available for chating and if you could start talking to your friend just clicking on his name.

Here is a short instructions how to add your first contact:

Click on Psi menu - the button next to Online text. You will then see something like this:

From all menu options select the top one - Add a contact:
Next window will show where you can enter your contact details:

You have to know Jabber ID of the person you want to add to your contact list. Let's assume for example you want to add Tigase server administrator Jabber ID to your contact list. So after you enter these details the window will look like this:

Click Add button.
Now you can see confirmation window that new person has been added to your contact list:

But there is more behind the scene. Adding contact to your Roster (contact list) usually means you can see whether the person is online and available to talk or not. The person however may not wish you to see his presence. So to make sure the other person accepts you as a friend Psi send request to the address you just entered with question whether he agree to show his presence to you.

You won't be able to see the user availability until he sends confirmation.
Once the other user sends confirmation back you will receive usually 2 system events:
Click on the contact to see window with these messages:
One message just say you have been authorized by the other user:

So you simply click Next to see second message.
The second message is a bit more interesting. It contains question whether you also authorize the other user to see your presence. If you want to accept this request just click Add/Auth.
Finally main Psi window with your new contact:

Well done!

You are ready to start Jabbering. Good luck.

Where to go next? For detailed Psi documentation refer to the program Wiki page: http://psi-im.org/wiki/Main_Page

Tigase service and MSN transport from client side.

MSN transport is a separate module which allows you to connect to your MSN account and contact with other people from MSN network from your Jabber client. We use PyMSN-t application as a MSN transport which is a separate project from Tigase server. Both applications integrate very well and detailed configuration instruction is available in this guide.

At the moment MSN transport installed on tigase.org server is available for local users only.

You also need an account on Hotmail server and a Jabber/XMPP client of your choice:

Psi
Pidgin
Coccinella
Jeti - available also on Tigase Website.
JWChat - available also on Tigase Website.

There are many other clients available...

Here are instructions how to use the MSN transport on tigase.org in different Jabber/XMPP clients.

First and the most important thing to note is you can not register an account on tigase.org server using your Jabber client. You have to create new account using Tigase Website. This is because Tigase Website running on Drupal shares account information with Jabber service and all account management is done via Website interface.

All Jabber/XMPP capable clients can use MSN transport as it needs very basic Jabber/XMPP protocol features. Unfortunately some clients, especially multi-protocols clients like Pidgin don't fully support protocol and can not initialize MSN transport properly. There is a workaround though. Again using what Tigase Website offers you can initialize MSN transport and then switch back to your favorite client.

Let's say we have already refistered test account on Tigase Website with password *** and we also have a MSN account: kobit12@hotmail.com with password: *********.

Jeti

Jeti is described as the first client because it might be needed for users of some other clients to initialize MSN transport for your account.

Due to a number of images used in the Jeti guide it has been moved onto separate page.

Pidgin

As I mentioned earlier Pidgin doesn't support all Jabber extensions needed for registering to MSN transport so unfortunately you have to use different client to add this transport to your roster. Ideally you should use one of native Jabber stand-alone clients like Psi or Coccinella. If you don't want, however to install any other clients you can use Jeti which is available on Tigase website preinstalled and preconfigured for use. Please refer to this guide for details how to use Jeti client to get MSN transport working.

Ok, now as you probably have MSN transport activated for you account you can start using Pidgin to communicate with either Jabber users or MSN users.

First thing to do is basic Pidgin configuration to connect to your Jabber account on tigase.org server. Click Accounts in your main menu and then Add/Edit to get window with your all accounts list. There is a button Add. After you press it you get window as on the right hand side of this text.

Please enter all your login details as on the example screenshot. Your user name Screen name and Password will be different but Domain should be the same: tigase.org. After you fill all fields you don't press Register. You have to press Save.

Ok. Assuming everything was enterred correctly and you have configured Pidgin to login automatically your main window should look like the one on the left hand side. Your buddy list might be empty if you didn't add anybody to your list yet or if you didn't registered to MSN transport yet.

If MSN transport is not activated yet, please disconnect Pidgin from tigase.org server and use different client as described above to do so.

On the other hand if you did everything already and you have an old MSN account with lots of contacts your buddy list may look completely different as all the contacts you have will be automatically pulled into your Jabber roster and should show on the list.

I have created completely new MSN account for the purpose of writing this guide and I don't have any MSN contacts yet. So my list is quite simple - single Jabber contact and MSN transport which shows as a normal contact too. You remember Pidgin can't distinguish between transports and regular accounts.

In such case one of the first things I should do is adding new MSN contact to be able to communicate with somebody and see whether he/she is on-line or not.

Adding new contact is simple as long as Pidgin thinks it is normal Jabber contact. So actually we can not simply put: user_name@hotmail.com in Add buddy window because this is Hotmail account which is not directly available. After @ character you have to put valid Jabber domain, not MSN.

If you look at the windows on the right hand side it should become clear now.

Whole MSN account address is a user name for Jabber identifier and you have to replace @ with %. Then you put @ and MSN transport address. As an Alias you can enter anything. I have put real Hotmail address to make it easier later to see what the account it is.

Enter everything carefuly and press Add.

After you press the Add button the contact you are just adding should receive subscription request as well as subscription request should be also received by yourself. The Pidgin window should look similar to the example on the left hand side.

Of course you press Authorize button on both sides (or your mate in MSN network accepts your subscription request) and now the final window should look like the one on the right hand side. New buddy is on your list and you can click on his/her name and start chatting.

One final funny discovery I made during writing this guide.

I have created new MSN account just for my tests and I have also used my old MSN account for subscribing and adding the account to buddy list on both sides. More over, I access both MSN accounts through MSN transport and in my tests I was communicating from one Jabber client (Psi) through MSN gateway to MSN server and back through my MSN gateway back to other Jabber client (Pidgin) to the other account.

Apparently MSN transport spotted this and knowing how silly is such use case send me one extra message to my chat window. Have a look at the last screenshot and have fun. Remember to not communicate between 2 Jabber accounts using your 2 MSN accounts as this might be discovered by the smart, open source software.

Jeti and MSN transport on tigase.org

Make sure you are not connected to Tigase server with any other Jabber client to the account at the same time as this may affect your transport configuration.

It is available on Tigase Website, preinstalled and preconfigured. You can run it clicking on this link, enter you user name and password to login. In my case this is `test` and `*`. Click Login** and go to next page...
	You are logged in, you may see some contacts on buddy list or empty list if you have no contacts. You can add somebody or just start chatting but in this guide we will focus on MSN transport configuration. Now click Jeti button and select `Manage Services` menu option...
As a result you will get the windows with all tigase.org services. This version of Jeti client doesn't support service browsing yet so you have to enter correct address of MSN transport: `msn.tigase.org`.
Click Change server and you get another window which looks like this one. Now single click on PyMSNt Commands text to get another window where you have to enter you MSN user name and password.
	Make sure you enter full MSN account name here including `hotmail.com` part or any other domain name you use for you MSN account. Click OK now.
Well, you clicked OK and nothing really happened. The main Jeti windows looks as it looked before. The same, possibly emoty buddy list and no track of MSN transport. Unfortunately this Jeti version doesn't refresh transport list properly and you have to re-login to see the transport. Jeti author is aware of this problem and it will be addressed in next release. So please close the Jeti window and start application again entering you Tigase user name and password.
As you can see MSN transport is available now but it is grayed out which means you are not logged in to MSN service.
	To activate (login) to MSN service right click on the MSN Transport to get contect menu. Select Log On...
If everything was entered correctly and if MSN service is available you should be loged in to the transport and it should show in green color. All your MSN contacts should be automatically pulled in to your application. For the Jabber client now there is no difference between MSN contacts and Jabber contacts. So you can simply continue to use Jeti or close it and login with any other Jabber client.

You can now communicate with all people regardless they are available through XMPP or MSN.