Fixes #2 - Reworked facebook channel setup

channels/facebook.rst

@@ -1,75 +1,146 @@
 Facebook
 ========
 
-.. hint::
+Introduction
+------------
 
-   Please note that this part of our documentation currently is outdated.
-   We currently are working on solutions for this topic.
+You can connect your Facebook account to Zammad, allowing you to
+create tickets from posts and respond as comments.
 
-You can connect Facebook Accounts with Zammad. You need to connect your Zammad
-with Facebook first:
+Please note that you first and foremost should have a look at `Meta's
+documentation <https://developers.facebook.com/docs/>`_ to get the most
+recent and substantial information for the steps on their side.
+Some steps on Meta's side are only mentioned here as prerequisites, as this
+is outside the scope of this documentation.
 
-For this start at: https://developers.facebook.com/apps/
+.. tip:: The setup of the :doc:`WhatsApp channel </channels/whatsapp/index>` has
+   similar prerequisites as the Facebook channel. So, if you managed to set one
+   of them to up, you should have a look at the other one too. It could be a
+   low hanging fruit! 🎉
 
-.. image:: /images/channels/FB_1.png
+Prerequisites
+-------------
 
-.. image:: /images/channels/FB_2.png
+- `Meta business account <https://business.facebook.com/overview>`_
+- `Meta developer account <https://developers.facebook.com/docs/development/register>`_
+- Permission to create an app inside your developer account and needed
+  information for the app (see `here <https://developers.facebook.com/docs/development/create-an-app>`_)
 
-Click on “Create App ID" and enter app name
+Creating an App
+---------------
 
-.. image:: /images/channels/FB_3.png
+Create a new app
+   Go to Meta's `app dashboard <https://developers.facebook.com/apps>`_ and create
+   a new app.
 
-.. image:: /images/channels/FB_4.png
+   .. figure:: /images/channels/facebook/create-app.png
+      :alt: Screenshot of Meta's app dashboard with highlighted "Create App" button
 
-.. image:: /images/channels/FB_5.png
+   If you have more than one business portfolio, select the desired one.
 
-.. image:: /images/channels/FB_6.png
+   In the "Use cases" tab, select "Other" and "Business" app type.
 
-.. image:: /images/channels/FB_7.png
+   .. figure:: /images/channels/facebook/app-use-case.png
+      :alt: Screenshot of Meta's app dashboard with highlighted "Create App" button
 
-.. image:: /images/channels/FB_8.png
+   .. figure:: /images/channels/facebook/app-type.png
+      :alt: Screenshot of app creation with highlighted app type
 
-.. image:: /images/channels/FB_9.png
+   In the next screen, provide a fitting app name, contact email address and
+   select your business portfolio and finally click on "Create app".
 
-.. image:: /images/channels/FB_10.png
+   .. figure:: /images/channels/facebook/app-details.png
+      :alt: Screenshot of app creation on "Details" tab
 
-.. image:: /images/channels/FB_11.png
+Add a product to your app
+   After creating the app, you should see the app overview, where you
+   can add a product to your app.
 
+   Scroll down and select "Facebook Login for Business" by clicking on the
+   "Set up" button.
 
-**Configure Zammad as Facebook app**
+   .. figure:: /images/channels/facebook/add-product-overview.png
+      :alt: Screenshot of product overview with highlighted "Facebook Login for Business"
 
-- Go to “Admin -> Channels -> Facebook”
-- Click on “Connect Facebook App” and enter your “App ID”, “App Secret” and
-  verify the “Callback URL”.
+   In the following screen, go to "Valid OAuth Redirect URIs" and provide the
+   URL of your Zammad instance, followed by
+   ``/api/v1/external_credentials/facebook/callback``. You can copy this URL
+   from Zammad if you click on the "Configure App" button in Zammad's Facebook
+   channel admin screen.
 
-Done, your Zammad is configured as Facebook App now.
+   .. figure:: /images/channels/facebook/oauth-settings.png
+      :alt: Screenshot of app settings with highlighted "OAuth Redirect URIs"
 
+Continue with the next step on Zammad's side by connecting the Facebook with
+Zammad.
 
-**Link your Facebook Page to your Zammad Facebook app**
+Connect Facebook App in Zammad
+------------------------------
 
-Now you need to link your Facebook Page from which you want to get posts and
-send out comments.
+If not already done, go to the Facebook channel section in the admin interface
+in Zammad and click on "Configure App". This will open a dialog where you
+have to provide the app ID as well as the app secret.
 
-Click on “Add Account”, then you will see the authorize app page of Facebook.
-Click on “authorize app”.
+Head over to the Meta app dashboard and switch to "App settings" > "Basic".
+Copy the "App ID" and the the "App secret" (after clicking on the "Show" button)
+and paste both to Zammad in the corresponding fields.
 
-.. image:: /images/channels/FB_20.jpg
+.. figure:: /images/channels/facebook/app-settings-basic.png
+   :alt: Screenshot showing basic settings section of app settings
 
-.. image:: /images/channels/FB_21.jpg
+.. figure:: /images/channels/facebook/zammad-connect-app.png
+   :alt: Screenshot showing "Connect Facebook App" dialog in Zammad
+   :scale: 60%
+   :align: center
 
-You will get redirected back to Zammad. Now you need to configure your search
-keys, where mentions should get routed.
+Confirm it by clicking on "Submit" and continue with the next step.
 
-.. image:: /images/channels/FB_22.jpg
+Add Facebook Account to Zammad
+------------------------------
 
-After you are done, you will get an overview of all linked Facebook Accounts.
+After you successfully connected your app with Zammad, you can now add
+an account by clicking the "Add Account" button in Zammad. This redirects
+you to Facebook and you will see an account selection dialog. Confirm by
+clicking on "Continue as ..." or log in with another account.
 
-.. image:: /images/channels/FB_23.jpg
+.. figure:: /images/channels/facebook/account-login.png
+   :alt: Screenshot showing Account selection from Meta
+   :scale: 60%
+   :align: center
 
+In the next screen you can choose if you want to receive tickets from all pages
+or just selected ones. Choose what fits your needs and confirm by clicking
+"Continue".
 
-**Start using your new channel**
+.. figure:: /images/channels/facebook/pages-selection.png
+   :alt: Screenshot showing pages selection from Meta
+   :scale: 60%
+   :align: center
 
-Start and write a post to your page, short time later you will have a new
-ticket in Zammad.
+Finally, you see an overview about the requested permission. Click on "Save"
+and "Got it" in the next screen.
 
-Just click on the reply button (as you do it for emails) to send a comment.
+.. figure:: /images/channels/facebook/permission-overview.png
+   :alt: Screenshot showing permission overview
+   :scale: 60%
+   :align: center
+
+You are now redirected to Zammad where you can see a configuration dialog.
+Select a group you want to handle the Facebook tickets and click on "Submit".
+
+.. figure:: /images/channels/facebook/group-selection-dialog.png
+   :alt: Screenshot showing group selection dialog in Zammad
+   :scale: 75%
+   :align: center
+
+After that, you are technically ready to go. However, you have to do some
+additional steps, which aren't covered in this documentation:
+
+- Request advanced access for your app (see screenshot below)
+- Request a business review if your business is not already reviewed
+- Switch your app from development to live mode
+
+.. figure:: /images/channels/facebook/request-permissions.png
+   :alt: Screenshot showing permission and features screen in the Facebook developer portal
+   :scale: 60%
+   :align: center