.. include:: defs.txt
.. include:: images.txt

.. _librem_5_messages:

Sending and Receiving Messages
==============================

.. image:: images/chatty/sm.puri.Chatty.svg
   :width: 128
   :align: right
   :alt: The Chats application icon

The **Chats** application handles different kinds of messages and chats, collecting them together in the same user interface.

.. contents::
   :local:

Locate the icon shown above in the app drawer and press it to launch the application.

Getting Started
---------------

When you start **Chats** for the first time, you will be shown the **Chats** page and prompted to add new contacts and accounts.

.. image:: images/chatty/chatty-choose-contact.png
   :align: center
   :scale: 50%
   :alt: Choose a contact

To start writing SMS messages immediately, press the |add| (add) button at the top-left of the screen to :ref:`start a new chat <librem_5_messages_start_chat>`.

To add chat accounts, open the menu by pressing the |menu| (menu) button at the top-right of the screen and choose the **Preferences** option.

.. image:: images/chatty/chatty-menu.png
   :align: center
   :scale: 50%
   :alt: Opening the application menu

See the :ref:`librem_5_messages_preferences` section for instructions describing how to add and manage new accounts.

.. _librem_5_messages_start_chat:

Start a New Chat
----------------

On the start page, press the |add| (add) button at the top-left of the screen to start a new chat. If you have already started chats, these will be shown below the search bar.

.. image:: images/chatty/chatty-start-chat.png
   :align: center
   :scale: 50%
   :alt: Starting a new chat

Press one of the contacts to continue chatting with them.

Start a New SMS Chat
~~~~~~~~~~~~~~~~~~~~

To start an SMS chat quickly, tap inside the search bar and enter a phone number. An item should appear below the search bar as you type.

.. image:: images/chatty/chatty-start-chat-number.png
   :align: center
   :scale: 50%
   :alt: Starting a new chat with a phone number

When you have entered the phone number, tap the item to start an SMS chat.

To start an SMS chat with a new contact, press the button at the top-right of the screen to add a new contact. This will open a page that lets you input the name and phone number for your contact. Select **SMS** as your chat account if it is not the default option.

.. |new-sms-contact| image:: images/chatty/chatty-new-contact.png
   :scale: 50%
   :alt: Adding a new SMS contact
.. |new-sms-with-xmpp-contact| image:: images/chatty/chatty-new-contact-xmpp.png
   :scale: 50%
   :alt: Adding a new SMS contact with an XMPP option present

.. centered:: |new-sms-contact| |new-sms-with-xmpp-contact|

Press **Add to Contacts** to add the contact -- this will open the **Contacts** application. You can send a message to the new contact from within **Contacts** or return to **Chats** to start a conversation from the **Start Chat** screen.

When a new conversation has started, it will be shown in a layout like the image below, with incoming messages on the left and outgoing ones on the right.

.. image:: images/chatty/chatty-sms-conversation.png
   :align: center
   :scale: 50%
   :alt: Composing an SMS message

To return to the main **Chats** page, press the back button at the top-left of the screen.

Start a New XMPP Chat
~~~~~~~~~~~~~~~~~~~~~

Before starting an XMPP chat you need to add an XMPP account to **Chats** -- see the :ref:`librem_5_messages_adding_account` section below.

To start an SMS chat with a new contact, press the button at the top-right of the screen to add a new contact. This will open a page that lets you input the ID of your contact. Select your Jabber/XMPP ID as your chat account if it is not the default option.

.. |new-xmpp-contact| image:: images/chatty/chatty-start-chat-new-xmpp-contact.png
   :scale: 50%
   :alt: Adding a new XMPP contact
.. |new-xmpp-contact-filled| image:: images/chatty/chatty-start-chat-new-xmpp-contact-filled.png
   :scale: 50%
   :alt: Adding a new XMPP contact with details filled in

.. centered:: |new-xmpp-contact| |new-xmpp-contact-filled|

When you have entered the Jabber ID and an optional name for your new contact, press **Add Contact** to add the contact and start composing a new message. If the contact's ID is already known, the **Add Contact** button will be disabled.

When your contact sends a message, you will be asked to authorize them -- to accept or reject them as a contact. Press either the **Reject** button or the **Accept** button to do this.

.. image:: images/chatty/chatty-authorize-contact.png
   :align: center
   :scale: 50%
   :alt: Authorizing a new XMPP contact

If you accepted the contact, you should be able to continue the chat with them.

.. image:: images/chatty/chatty-chat-xmpp.png
   :align: center
   :scale: 50%
   :alt: Continuing an XMPP chat

Individual conversations can be configured by accessing the **Chat Details** page via the menu at the top-right of the screen.

.. |xmpp-chat-menu| image:: images/chatty/chatty-chat-xmpp-menu.png
   :scale: 50%
   :alt: Opening the XMPP chat menu
.. |xmpp-chat-details| image:: images/chatty/chatty-chat-xmpp-details.png
   :scale: 50%
   :alt: Viewing the XMPP chat details

.. centered:: |xmpp-chat-menu| |xmpp-chat-details|

As well as details about the connection, you can enable and disable notifications for newly received messages specifically in this conversation.

You can return to the **Chats** list by pressing the back button at the top-left of the screen.

Leaving a Chat
--------------

To leave a chat, press the |menu| (menu) button at the top-right of the screen and choose **Leave Chat**.

.. image:: images/chatty/chatty-chat-menu.png
   :align: center
   :alt: Opening the chat menu

This will close the chat and return you to the **Chats** page. The chat will have been removed from the list.

You can :ref:`start a new chat <librem_5_messages_start_chat>` with the same contact to recover the chat history.

Deleting a Chat
---------------

To delete a chat, press the |menu| (menu) button at the top-right of the screen and choose **Delete Chat**.

.. image:: images/chatty/chatty-chat-menu.png
   :align: center
   :alt: Opening the chat menu

You will be asked to confirm that you want to delete the chat and the conversation history.

.. image:: images/chatty/chatty-delete-chat.png
   :align: center
   :scale: 50%
   :alt: Confirming chat deletion

Pressing **Delete** will close the chat and return you to the **Chats** page. The chat will have been removed from the list. The contact will also have been deleted from the **Start Chat** page.

.. _librem_5_messages_preferences:

Preferences
-----------

The **Preferences** page lets you customize how the application behaves. It is also where you can add chat accounts.

.. image:: images/chatty/chatty-preferences-top.png
   :align: center
   :scale: 50%
   :alt: Application preferences

To add a new account to those managed by the application, press the **Add new account...** label in the **Accounts** section.

.. _librem_5_messages_adding_account:

Adding an Account
~~~~~~~~~~~~~~~~~

The **Add Account** page lets you add accounts on XMPP servers.

.. image:: images/chatty/chatty-add-xmpp-account.png
   :align: center
   :alt: Adding an XMPP account

Enter your user ID and password for the XMPP chat service and press the **Add** button to add the account and return to the **Preferences** page.

.. image:: images/chatty/chatty-preferences-xmpp-account-added.png
   :align: center
   :alt: The new XMPP account

The new account should now be shown in the list. By default, the account is active -- the switch next to the account details will be blue when it is in the on position.

An animation may be shown to indicate that the server is being contacted.

If you wish to disable the connection to the server for the account, slide the switch left into the off position.

Editing and Deleting an Account
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To edit an account, press the label with the account details. This will open the **Edit Account** page.

.. image:: images/chatty/chatty-edit-xmpp-account.png
   :align: center
   :alt: Editing an XMPP account

You can press the pencil icon to update the password, if required. This can be useful if you accidentally entered the wrong password when adding the account.

If you want to delete information about the account on the phone, press the **Delete Account** button. Note that this does not delete the account on the server.
