Maintenance: add token generation via system user for WhatsApp

Author: ralf401

channels/whatsapp/preparation.rst

@@ -91,7 +91,7 @@ In the app dashboard, first re-open the configuration:
 
 Now go to **API Setup** and choose or add a phone number.
 
-.. note::
+.. warning::
     - 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

channels/whatsapp/setup.rst

@@ -31,13 +31,19 @@ WhatsApp Business Account ID
      :align: center
 
 Access Token
-   On the same **API Setup** page, you can generate a token. Follow the steps
-   and confirm it so you finally see the token. Make sure to copy it directly
-   because it gets displayed only once.
-
-   .. figure:: /images/channels/whatsapp/config-use-case-api-setup.png
-      :alt: App dashboard shows API configuration and highlighted token generation.
-      :align: center
+   Enter the access token of a system user with the permission to manage the
+   app. You can create it in the
+   `business settings <https://business.facebook.com/settings/system-users>`_
+   under *Users > System users*. Make sure to assign the created app to the
+   system user ("Assign assets") and to grant admin access by enabling the
+   **Manage app** toggle. After clicking the **Generate token** button, choose
+   your created app, an expiration date of the token (we recommend "Never") and
+   the permissions ``whatsapp_business_management`` and
+   ``whatsapp_business_messaging``.
+   Be aware that you have to copy the token, it is just displayed once!
+
+   .. figure:: /images/channels/whatsapp/system-user-token-generation.png
+      :alt: System user access token generation
 
 App Secret
    Enter your app secret. You can find it in your app configuration under

images/channels/whatsapp/config-use-case-api-setup.png

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Zammad Admin Documentation pre-release\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2026-01-16 08:30+0100\n"
+"POT-Creation-Date: 2026-02-03 11:15+0100\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -5536,130 +5536,130 @@ msgstr ""
 msgid "App dashboard with business account ID"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:40
+#: ../channels/whatsapp/setup.rst:46
 msgid "Access Token"
 msgstr ""
 
 #: ../channels/whatsapp/setup.rst:34
-msgid "On the same **API Setup** page, you can generate a token. Follow the steps and confirm it so you finally see the token. Make sure to copy it directly because it gets displayed only once."
+msgid "Enter the access token of a system user with the permission to manage the app. You can create it in the `business settings <https://business.facebook.com/settings/system-users>`_ under *Users > System users*. Make sure to assign the created app to the system user (\"Assign assets\") and to grant admin access by enabling the **Manage app** toggle. After clicking the **Generate token** button, choose your created app, an expiration date of the token (we recommend \"Never\") and the permissions ``whatsapp_business_management`` and ``whatsapp_business_messaging``. Be aware that you have to copy the token, it is just displayed once!"
 msgstr ""
 
 #: ../channels/whatsapp/setup.rst:0
-msgid "App dashboard shows API configuration and highlighted token generation."
+msgid "System user access token generation"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:47
+#: ../channels/whatsapp/setup.rst:53
 msgid "App Secret"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:43
+#: ../channels/whatsapp/setup.rst:49
 msgid "Enter your app secret. You can find it in your app configuration under *App settings > Basic*. Click the **Show** button to be able to copy it."
 msgstr ""
 
 #: ../channels/whatsapp/setup.rst:0
 msgid "App dashboard with app secret"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:49
+#: ../channels/whatsapp/setup.rst:55
 msgid "After providing these three values, click on **Next** in Zammad. This performs a check and fetches your assigned phone number. If everything is fine, the dialog switches to the next step."
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:54
+#: ../channels/whatsapp/setup.rst:60
 msgid "Step 2"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:56
+#: ../channels/whatsapp/setup.rst:62
 msgid "The second step is about your phone number and messaging details:"
 msgstr ""
 
 #: ../channels/whatsapp/setup.rst:None
 msgid "Step 2 of adding a WhatsApp account"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:66
+#: ../channels/whatsapp/setup.rst:72
 msgid "Phone Number"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:64
+#: ../channels/whatsapp/setup.rst:70
 msgid "Choose the phone number you want to use for the channel. Zammad should have fetched the number which is assigned to your app. If not, your credentials from step 1 may be wrong."
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:70
+#: ../channels/whatsapp/setup.rst:76
 msgid "Welcome Message"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:69
+#: ../channels/whatsapp/setup.rst:75
 msgid "Here you can define an optional text message which is automatically sent to your customers when the initial message is received."
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:79
+#: ../channels/whatsapp/setup.rst:85
 msgid "Automatic Reminders"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:73
+#: ../channels/whatsapp/setup.rst:79
 msgid "Here you can control whether the automatic reminders about the customer service window are sent to the customer when the window is about to expire."
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:76
+#: ../channels/whatsapp/setup.rst:82
 msgid "For more information on 24-hour customer service windows, take a look at Meta's `conversation description <https://developers.facebook.com/docs/whatsapp/pricing#customer-service-windows>`_ under \"Customer Service Windows\"."
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:84
+#: ../channels/whatsapp/setup.rst:90
 msgid "Reminder Message"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:82
+#: ../channels/whatsapp/setup.rst:88
 msgid "If you want to use a custom reminder message before the 24-hour customer service window closes, you can insert it here. Leave it empty to stay with the default message."
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:88
+#: ../channels/whatsapp/setup.rst:94
 #: ../misc/object-conditions/basics.rst:28
 #: ../misc/object-conditions/basics.rst:139
 #: ../system/integrations/checkmk/admin-panel-reference.rst:15
 msgid "Group"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:87
+#: ../channels/whatsapp/setup.rst:93
 msgid "Here you can define the :doc:`group </manage/groups/index>` in which the ticket should be created."
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:90
+#: ../channels/whatsapp/setup.rst:96
 msgid "After you are configured everything, click on **Submit**. Now the WhatsApp channel is technically created on Zammad side. However, you need to take another important step to make it work."
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:95
+#: ../channels/whatsapp/setup.rst:101
 msgid "Step 3"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:97
+#: ../channels/whatsapp/setup.rst:103
 msgid "This third step is about telling WhatsApp where, how and what data to send."
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:99
+#: ../channels/whatsapp/setup.rst:105
 msgid "If you don't follow the instructions properly, your account shows up but you aren't able to receive messages (because Meta/WhatsApp doesn't know where to send them)!"
 msgstr ""
 
 #: ../channels/whatsapp/setup.rst:None
 msgid "Step 3 of adding a WhatsApp account"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:108
+#: ../channels/whatsapp/setup.rst:114
 msgid "Go to *Use cases > Configuration* and copy/paste the values from **Callback URL** as well as **Verify Token** from Zammad. Confirm with **Verify and save**."
 msgstr ""
 
 #: ../channels/whatsapp/setup.rst:None
 msgid "Configuration section in WhatsApp app dashboard"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:115
+#: ../channels/whatsapp/setup.rst:121
 msgid "Scroll down and switch on the toggle for ``messages`` under **Webhook fields**."
 msgstr ""
 
 #: ../channels/whatsapp/setup.rst:None
 msgid "Select \"message\" as webhook field"
 msgstr ""
 
-#: ../channels/whatsapp/setup.rst:121
+#: ../channels/whatsapp/setup.rst:127
 msgid "After finishing this step, you can click on the **Finish** button in Zammad and you should now be ready to receive tickets from your WhatsApp channel!"
 msgstr ""