Fixes #1031 - Overhaul WhatsApp configuration and align it to the new flow from Meta

Author: ralf401

channels/whatsapp/index.rst

@@ -1,38 +1,33 @@
 WhatsApp
 ========
 
-With the release of Zammad 6.3, you can now connect your Zammad with a
-WhatsApp Business account, allowing your customers to reach out to you through
-WhatsApp. 🎉
-
-If you already dived deep into this topic, you can head to the setup guide.
-If not, we strongly encourage you to read the prerequisites and limitations
-of this channel carefully and to follow our tutorial for preparing your
-setup.
-
-We tried to keep it clear and created a separate sub-page for the necessary
-steps on Meta/WhatsApp side.
+Connect Zammad with a WhatsApp Business account so your customers can
+reach out to you through WhatsApp. 🎉
 
 .. warning::
-   Please be aware that the usage of **WhatsApp Cloud API** is mandatory to
-   connect WhatsApp to Zammad. You won't be able
-   to connect to WhatsApp in Zammad if you just use the WhatsApp Business *App*.
-   Have a look
-   `here <https://developers.facebook.com/docs/whatsapp/cloud-api>`_
-   for further information about the Cloud API.
-
-   There may be additional costs for you from Meta/WhatsApp side. Have a look
-   at their
-   `pricing page <https://developers.facebook.com/docs/whatsapp/pricing>`_ to
-   be safe from surprises.
 
-   Be aware that if you go through the whole process, it is very time consuming.
-   You should have some time to follow our preparation guide.
+   - The usage of **WhatsApp Cloud API** is mandatory to connect WhatsApp to
+     Zammad. You won't be able to connect to WhatsApp in Zammad if you just use
+     the WhatsApp Business *App*. Have a look
+     `here <https://developers.facebook.com/docs/whatsapp/cloud-api>`_
+     for further information about the Cloud API.
+   - There may be additional costs for you from Meta/WhatsApp side. Have a look
+     at their
+     `pricing page <https://developers.facebook.com/docs/whatsapp/pricing>`_ to
+     be safe from surprises.
+   - This setup process can be very time consuming. You should have some time to
+     follow this guide.
+
+If you are already familiar with Meta's app creation process and their developer
+console, you can directly jump to the setup page.
+In all other cases, we strongly encourage you to read about the limitations
+of this channel carefully and to follow the preparation steps first.
+
+This guide is separated in 3 sub-pages:
 
 .. toctree::
-   :hidden:
+   :maxdepth: 1
 
-   preparation
-   prerequisites
    limitations
-   setup
+   preparation
+   setup

channels/whatsapp/preparation.rst

@@ -3,30 +3,32 @@ Preparation
 
 Here you can find instructions for the required steps you need to take before
 you can use the WhatsApp channel in Zammad.
-
 Please note that these steps may change in the future, depending on changes on
 Meta's side. You should also consider to read their docs if you have issues:
 
 - `WhatsApp Cloud API <https://developers.facebook.com/docs/whatsapp/cloud-api>`_
 - `WhatsApp Business Platform <https://developers.facebook.com/docs/whatsapp>`_
 
+Prerequisites
+-------------
+
+- Make sure your system is accessible from the internet because WhatsApp sends
+  messages via webhooks to your system.
+- Make sure to have properly set up your
+  :doc:`FQDN in Settings > System </settings/system/base>` (for the callback
+  URL Meta will use to deliver new messages).
+
 .. _create-meta-business-account:
 
 Create a Meta Business Account
 ------------------------------
 
 If you don't already have a business account, visit
-https://business.facebook.com/overview and click on "Create an account":
-
-.. figure:: /images/channels/whatsapp/create-meta-business-account.png
-    :alt: Meta business account starting page
-    :align: center
-
+https://business.facebook.com/overview and click on "Create an account".
 Have a look at
 `Meta's documentation <https://www.facebook.com/business/help/1710077379203657?id=180505742745347>`_
 if you have problems.
 
-
 Create a Meta Developer Account
 -------------------------------
 
@@ -38,109 +40,69 @@ Create a Meta Developer App
 ---------------------------
 
 While already logged in with your developer account, go to
-https://developers.facebook.com/apps/.
-
-You will see a screen like the following screenshot. Click on "Create App" and
-follow the steps below.
+https://developers.facebook.com/apps/. Click on **Create App** and follow the
+steps below.
 
 .. figure:: /images/channels/whatsapp/meta-create-app.png
     :alt: Meta developer app overview
     :align: center
 
-Choose "Other" when you are asked what you want to do with your app:
+Enter a fitting name and provide a contact email address for your app:
 
 .. figure:: /images/channels/whatsapp/meta-create-app-step1.png
     :alt: Meta app creation step 1
     :align: center
-    :scale: 50%
 
-Choose "Business" as app type:
+Choose **Connect with customers through WhatsApp** as use case:
 
 .. figure:: /images/channels/whatsapp/meta-create-app-step2.png
     :alt: Meta app creation step 2
     :align: center
-    :scale: 50%
 
-Enter a name for the app, a contact email address and a business account.
-Please note that the name may not contain specific product names from Meta, as
-you can see in the screenshot below.
+Choose a business portfolio, in case you have more than one:
 
 .. figure:: /images/channels/whatsapp/meta-create-app-step3.png
-    :alt: Meta app creation step 2
-    :align: center
-    :scale: 50%
-
-If you already have a business account, you should assign it. In this step, this
-is optional, but later it is required anyway. Click on "Create App" to finish
-this step.
-
-Add WhatsApp Product to Your App
---------------------------------
-
-Now you have to add a product to your app. In our case, this is WhatsApp.
-Search for it and click on "Set up":
-
-.. figure:: /images/channels/whatsapp/meta-add-product.png
-    :alt: Add a product to your app
+    :alt: Meta app creation step 3
     :align: center
 
-In the next step, you have to add a "Meta Business Account". This guide assumes
-that you already have one. If not, go to the
-:ref:`instructions above <create-meta-business-account>` and create one.
+Check if additional steps are required and follow them. In case everything is
+fine, you should see a screen like this:
 
-.. figure:: /images/channels/whatsapp/meta-add-product-step1.png
-    :alt: Add the product WhatsApp to your app
+.. figure:: /images/channels/whatsapp/meta-create-app-step4.png
+    :alt: Meta app creation step 4
     :align: center
-    :scale: 70%
-
-Create a System User
---------------------
-Go to `Users > System users <https://business.facebook.com/settings/system-users/>`_
-and add a system user. This is required to get a permanent API token. Make sure
-the user has admin permissions.
 
-After creating a system user, you should see a screen similar to the one below.
-Here you can assign assets and (re-)generate an access token.
+After that, you will see a summary of your configuration. Check if everything is
+correct and go back to the dashboard via the button:
 
-For now we just assign assets to this user. The creation of the token is
-covered in the :doc:`Zammad setup section </channels/whatsapp/index>` because
-the token is only displayed once and then you can copy and paste it directly.
-
-.. figure:: /images/channels/whatsapp/created-system-user.png
-    :alt: System user overview
+.. figure:: /images/channels/whatsapp/meta-create-app-step5.png
+    :alt: Meta app creation step 5
     :align: center
 
-You now have to assign assets to this user. Choose your app
-and "Manage app" permissions:
-
-.. figure:: /images/channels/whatsapp/system-user-assign-assets.png
-    :alt: Assign assets to system user
-    :align: center
-    :scale: 70%
 
-Configure Your WhatsApp Business Platform
------------------------------------------
+Assign a Phone Number
+---------------------
 
-After adding a "Meta Business Account" to your app, the "App Dashboard" is
-presented to you. Click on "Start using the API":
+In the app dashboard, first re-open the configuration:
 
-.. figure:: /images/channels/whatsapp/meta-app-dashboard-overview.png
-    :alt: App dashboard overview
+.. figure:: /images/channels/whatsapp/meta-app-dashboard.png
+    :alt: Meta app dashboard configuration option.
     :align: center
 
-Assign an Unused Phone Number
------------------------------
+Now go to **API Setup** and choose or add a phone number.
 
-Please note: this number may not be used in a WhatsApp app already!
+.. note::
+    - This number may not be used in a WhatsApp app already, not even in a
+      WhatsApp Business app.
+    - In case you want to test it with a provided test number, additional
+      steps might be required (see
+      `Reddit thread <https://www.reddit.com/r/WhatsappBusinessAPI/comments/1oa4ftw/comment/nk7sxtq/>`_).
 
 .. figure:: /images/channels/whatsapp/add-phone-number.png
     :align: center
     :alt: Adding a new phone number to your app
 
 Click through the steps adding your information. You have to verify your number
 by receiving a security code and repeating it when asked.
-
 After you successfully performed these steps, you are now good to go with
-the :doc:`setup on Zammad side <index>`. 🎉
-
-We promise it will become easier! 🤓
+the :doc:`channel setup on Zammad side <setup>`.