# The &kopete; Handbook

&Will.Stephenson; &Will.Stephenson.mail;
&FDLNotice;
2003-10-05
0.8
2003

&kopete; is &kde;'s multi-protocol instant messenger client.

KDE
IM
Instant
Messaging
Jabber
IRC
MSN
ICQ
AIM
Yahoo
Gadu-Gadu
WinPopup
SMS

## Introduction

### Introduction

&kopete; is the &kde; instant messaging (&im;) client. It allows you to communicate using various instant messaging services. A single program is easy to learn and use if your friends or colleagues use more than one &im; service.

If you've used Instant Messaging before, you'll want to skip to Getting Started, otherwise, take a quick look at the following section.

### Introduction to Instant Messaging

What is Instant Messaging (&im;)? &im; is a way for you to communicate instantly with your friends over the Internet. That might not sound so different to email. Have you ever noticed how cumbersome it is to have a brief conversation via email? You have to click Reply to each message, then find the right spot in the message to type something new, then send it. Then you have to wait for the next message to arrive! &im; lets you to have a conversation almost as naturally as on the phone or face to face, by typing messages into a window shared between you and your friend's screens.

Another difference between &im; and email is that with &im; you can see your friends' presence, that is, whether they are actually on-line at the same time as you. This lets you send messages truly instantly, instead of sending off a mail and having to wait for your friend to check their mailbox. An &im; message pops up on the other person's screen as soon as you send it. Of course, if you'd rather not be interrupted, you can change your own presence so others will know not to disturb you.

There are lots of other fun and useful &im; features you can explore with &kopete;, like group chats, file transfers and emoticons that reflect your mood. Read on to find out more!

## Getting Started

To use &kopete; you need to set up one or more accounts for the instant messaging services you wish to use.

You've probably already chosen a messaging service, either because you already use &im;, or you need to use the same service as your friends. If you don't fit into either of these categories, please consider using a messaging service based on open standards, because these are designed for use by Free Software. Other messaging services are prone to changing the underlying technology without making the details freely available, making them harder for Free Software developers to support.

The messaging services that &kopete; supports that are based on open standards are Jabber and IRC.

The following section assumes you are registered with an &im; service already. If not, you can register with Gadu-Gadu, Jabber, and MSN from inside &kopete;; for other services, you'll have to register using their respective web site before creating an account in &kopete;.

### Creating Accounts

To create an account, use Settings Configure &kopete;... to display the Configure window.

The Configure window is the main way to set up and customise &kopete;. On the left a column of icons control which aspect of &kopete; is being configured. Click the Accounts icon. The main pane will change to display the account management pane. This is currently empty, but will soon list your &im; accounts. Click New to display the Account Wizard.

The Account Wizard helps you create an &im; account. After the Welcome page, you are asked to select the messaging service that you'd like to use. Click one of the services shown and then click Next. On the following page, you should enter your registration details for that instant messaging service.

Most services just require you to enter a username or unique identifying number (UIN) and password. The special purpose services Winpopup and SMS work slightly differently, so please see their specific sections. There are a couple of other options that apply to most services that you should look at:

Remember password

  When this is checked, &kopete; will store the password for you, so you don't have to enter it every time you connect to the &im; service. If you are security-conscious or want to limit access to the &im; account you can leave this unchecked.

Connect at startup

  When this is checked, &kopete; will try to connect to the &im; service as when it starts. If you use a LAN, DSLor other always-on connection, this is appropriate; dial-up modem users should turn this off and connect manually when you have dialed up.

Once you've entered your &im; details, you can proceed to the Finish page and then dismiss the wizard and the Configure window.

### Go Online and Start Chatting!

Now you'll notice that an icon representing the account has appeared in the status bar at the bottom of the &kopete; Contact List window. This represents your current presence for this account. Right click on it and you can go online from the menu that appears. The status bar icon will animate while &kopete; connects to the &im; service.

Once you're online, if you've used this &im; service before, your contacts will be fetched from the server and displayed in the Contact List. To start a chat with a contact, just click their name and a Chat window will appear. The upper part of the window is where the conversation appears - to say something, type into the bottom part of the window and click Send.

If you've just created a new account you won't have any contacts. See Adding Contacts for details on how to add contacts.

The shortcut for Send is set to &Ctrl;&Enter; by default; you can change it in the Chat window using Settings Configure Shortcuts....

## Using &kopete;

This chapter gives an overview of &kopete;'s basic features. We will look first at the contact list, where your contacts are displayed, and then at the Chat window, where you carry out a conversation.

### The Contact List

The Contact List appears when you start &kopete;. It's the main window where you can set your presence, start a chat, organise your contacts, configure &kopete; and quit.

#### Layout of the Contact List window

##### Menu

You will usually find the menu bar at the top of the contact list. If it's not there, you might have turned it off; you can re-enable it with &Ctrl;M. Details on each menu item can be found in the chapter on menu structure.

##### Tool bar

The toolbar holds the most frequently used &kopete; actions. You can customise it with Settings Configure Toolbars.... Notice the Show Offline Users and Show Empty Groups buttons. With these you can hide contacts and groups that are offline.

##### Contact List

The Contact List takes up the main part of the window. All your contacts are listed here, in the groups you have chosen for them. You can open or close groups by clicking the plus symbol adjacent to the group. You can reverse the order the groups are sorted in by clicking the Contacts label above the list.

The context menu in the Contact List changes depending on the item under the mouse. Groups, Metacontacts and &im; system specific contacts have their own options. The context menu in empty areas of the Contact List allows you to add contacts or groups, or change the viewing options for the list.

##### Status bar

The status bar shows an icon for each &im; account you have created. The icons represent the current presence of each account, which can be changed by right-clicking the account icon.

#### Setting Your Presence

We introduced you to setting presence in the previous chapter. 'Presence' determines how visible you are on the &im; network. To use the network at all, you have to connect to the network, so you can send and receive messages and see others' presence. Once you are connected, most &im; systems allow you to indicate what you're doing and whether you want to chat by setting special types of presence such as 'Away' or 'Free For Chat'. The difference presence settings are particular to each away system; but &kopete; allows you some control all your &im; systems at once by setting them to 'Away' or 'Available' at the same time.

You set your presence for individual &im; accounts by right clicking the account's icon in the status bar at the bottom of the Contact List. The context menu for each account lets you choose the possible presence settings for each &im; system.

To change all your accounts' presence together, click the Status, or use the File Status menu.

#### Start A Chat From The Contact List

To start a chat from the Contact List, simply click a contact. A Chat window will appear.

You can also right click a contact and select either Send Message or Start Chat. Send Message works differently in that it just sends a single message without opening the Chat window, using a simple dialog. Use it for fire-and-forget messages.

#### Organising Contacts

##### A Word about Metacontacts

One of the principles behind &kopete; is that it offers a standardised way to use &im; systems. Differences between &im; systems are smoothed over, making it easier to communicate. We follow this principle in the way contacts are organised. When you use &kopete; you just find contacts by name; the actual &im; system used is less important. Some people have more than one &im; account - &kopete; puts the person using the account first.

To support this, &kopete; introduced Metacontacts, which represent the person you want to chat with. One Metacontact contains all the different &im; IDs they may have, making it easy to see with a glance at the Metacontact whether someone is available, regardless of which &im; system they are using right now.

##### A Word about Grouping Contacts

&kopete; lets you create groups to sort your contacts. A contact may be in more than one group. Where possible, groupings are saved on server side contact lists, so if you use other &im; programs, group memberships are kept in sync.

##### Adding Contacts

To add a contact, either select File Add Contact... or click the Add Contact button on the toolbar. This brings up the Add Contact Wizard.

The Add Contact Wizard creates a new Metacontact using one or more &im; systems, byleads you through the following pages:

1. Welcome Page. Here you can choose whether you want to use the KDE Address Book for this contact. Storing &im; information in the KDE Address Book will enable other &kde; &im; programs to share contact information with &kopete; and in future &kde; applications may use &kopete; to send information via &im;. If you prefer to keep your &im; contacts separated, clear the checkbox here.

2. Choose KDE Address Book entry. By choosing an entry from your KDE Address Book, you can use its name as a Display Name in &kopete;. You can also create a new entry here. This page doesn't show if you chose not to use the KDE Address Book.

3. Select Display Name and Group. Here you can enter a Display Name (the name used for this person inside &kopete;), and choose the groups they are a member of.

4. Select &im; Accounts. Here you can choose which accounts you want to use to chat to the new contact. If you only have one &im; account yourself, you won't see this screen.

5. Account-specific Add Contact Pages. For each account, you'll get one page where you can enter the UIN, buddy name or E-mail address, depending on the &im; system in use.

6. Finish Screen. All done. Except if the &im; system requires authorisation (such as ICQ) to add a contact to your list - in which case, you'll be prompted after the wizard exits.

You can add contacts to an existing Metacontact using its context menu.

##### Removing Contacts

If you no longer want a contact to be in the contact list, you can remove a Metacontact and all the contacts under it with Metacontact context menu Remove Contact.

##### Moving Contacts between Metacontacts

You can change the metacontact a contact belongs to. In practice, you only have to do this when you have just added multiple accounts to &kopete;, and you know that HotDog76 and mikejones@hotmail.com are both the same person.

There are two ways to do this:

Drag and Drop

  The contact icon to the right of the Metacontact name may be dragged from one Metacontact to another.

Contact Context Menu

  The context menu for contacts (Right-click the contact icon) allows you to choose the new Metacontact from a dialog.

If the move would leave a Metacontact empty (with no contacts), you'll be asked if you want to delete this contact.

##### Removing Contacts from Metacontacts

To remove a contact from a Metacontact, choose Contact context menu Delete Contact.

#### Configure &kopete;

You can configure &kopete; using Settings Configure &kopete;.... See the next chapter for details.

#### Exiting &kopete;

To exit &kopete; you should use File Quit, &Ctrl;Q, or the &kopete; System Tray icon's context menu. If you just close the Contact List window, &kopete; will continue to run in the KDE System Tray.

#### Keyboard shortcuts

The following keyboard shortcuts are supported in the Contact List window:

Keyboard Shortcut | Action
--- | ---
Up Arrow | Select the previous item in the contact list.
Down Arrow | Select the next item in the contact list.
Left Arrow | Close the current group.
Right Arrow | Open the current group.
Enter | Start a chat with the selected contact.
&Ctrl;M | Show/Hide the menu bar.
&Ctrl;U | Show/Hide offline users.
&Ctrl;G | Show/Hide empty groups.

### The Chat Window

#### Layout of the Chat Window

##### The Chat View

The Chat View usually takes up most of the Chat window and is where the conversation between you and your contacts takes place. Messages appear in the order they are received, with the earliest messages at the top of the view.

You can control the appearance of the Chat View, making it look like other &im; clients or create a completely individual look.

##### Chat Members List

Since some &im; systems allow you to chat as a group, it's useful to see who's chatting at the moment. The Chat Members List appears to the left or the right of the Chat View. You can change this using Settings Chat Members List. The contact context menu is available in the Chat Members List.

##### Input Area

The Input Area is below the Chat View. This is where you type messages before sending them. You can change the font and colour of the message using the usual tools on the toolbar. If the &im; system supports this, your messages will appear in colour when your contacts read them.

By default, the keyboard shortcut to send messages is &Ctrl;&Enter;.

##### Status Bar

The Status Bar contains temporary messages, such as notification that someone else is typing, as well as the Send button.

##### Tabbing

&kopete; lets you carry on multiple conversations in one window, by putting each one in its own tab within the window. The tab titles change colour to show when a new message has been received:

Red

  Someone typed a message.

Blue

  Someone typed a message containing your nickname.

There are several different ways to control grouping. To configure this behaviour, go to the Chat tab of the Behaviour page of the Configure &kopete; dialog. You can also move chats between windows using the Tabs menu, and control the placement of the tabs in the window.

#### Group Chats in &kopete;

You can use &kopete; to chat one to one, or in a group, where the &im; system supports this.

MSN lets you invite others into a chat using Chat Invite<contact name>.

#### File Transfers

Some &im; systems allow you to send and receive files. You can access this function from the contact's context menu. If you're already chatting, and want to send a file, select the recipient from the Chat Contacts menu.

#### Keyboard Shortcuts

The following keyboard shortcuts are supported in the Chat window:

Keyboard Shortcut | Action
--- | ---
&Ctrl;&Enter; | Send the message in the Input Area.
&Ctrl;P | Print the contents of the Chat View.
&Ctrl;S | Save the contents of the Chat View.
&Ctrl;W | Close the current Chat View. The Chat window will close unless there is more than one tab in the window.
&Alt;Left Arrow | Change to the previous tab.
&Alt;Right Arrow | Change to the next tab.
&Ctrl;&Shift;B | Detach a tabbed chat into a separate window.
Tab | Complete a partially typed nickname belonging to someone you're chatting with.

## Configuring &kopete;

To configure &kopete;...

### Global Shortcuts

&kopete; defines some shortcuts which are valid in any KDE application.

### Adding and Editing Accounts

We briefly showed you how to add an account in Getting Started. To change an account's setting later...

### Behaviour and Notifications

Behaviour and Notifications covers the way &kopete; integrates with your desktop, Away settings, and chat user interface options.

### Appearance

Appearance governs the style of the Chat window, its colours and fonts, and lets you choose your preferred emoticons.

### Loading Plugins

You can customise &kopete; with special functions that may be useful or just a bit of fun.

## &kopete;'s plugins

&kopete; is designed to make it easy to create plugins that give &kopete; more functions.

### Auto Replace

Auto Replace allows you to correct frequently misspelled words or save typing certain words using abbreviations.

### Connection Status

Connection Status is useful for modem users or others who don't have a permanent Internet connection. It watches for an active Internet connection and sets your accounts online when it detects you have dialed up.

### Contact Notes

Contact Notes allows you to note down any useful bits of information on a metacontact.

### Cryptography

Cryptography lets you use GPG to encrypt conversations. Note that this is not the same as an SSL secured chat session - this kind of encryption not only ensures the message cannot be tampered with, it also guarantees that only the intended recipient can read the messages.

### Highlight

Highlight works a little like e-mail filters, in that it allows you to make things happen in response to particular messages. As well as highlighting the text, you can play sounds.

### History

The History plugin, when activated, records conversations using any &im; system and allows you to view old conversations later. A History item appears in each Metacontact's context menu, to view the message history for that metacontact.

### Motion Auto-Away

In conjunction with a webcam and the Video4Linux package, this lets you detect when you're no longer at your computer and have &kopete; automatically become Away.

### Now Listening

With the Now Listening plugin, let people you're chatting with know what you're listening to, by typing `/media` in a chat, or from the File Actions menu.

### Text Effect

Text Effect applies funny effects to your messages before sending them, like colouring them or changing the case of the words. Just don't forget you have activated it - we've had bug reports from forgetful Text Effect users!

### Translator

The Translator plugin lets you define a preferred language for each Metacontact, and then translates messages to or from them using web based translation services such as Google and Babelfish.

### Web Presence

Web Presence allows you to publicise your &im; presence on the Web. Give it the path to a file on an FTP server, (for example), and it will upload a short piece of HTML to that file, which you can include in your homepage. Good for bloggers to make friends with, or you could use it to use &im; in your business.

## Menu Structure

File Menu

## Frequently Asked Questions

Question:

Answer:

## Specialised Actions

Command line parameters

## Credits and Licenses

&kopete; copyright 2003, &kopete; Developers

Documentation copyright 2003, Will Stephenson

&underFDL; &underGPL;

&documentation.index;