[ADD] productivity: whatsapp configuration doc
Dev PR https://github.com/odoo/enterprise/pull/45601#pullrequestreview-1608996613
Task [3495962](https://www.odoo.com/web#cids=3&model=project.task&view_type=form&id=3495962)
closes odoo/documentation#5890
X-original-commit: d4af79185e
Signed-off-by: Zachary Straub (zst) <zst@odoo.com>
Co-authored-by: larm-odoo <larm@odoo.com>
Co-authored-by: jero-odoo <jero@odoo.com>
Co-authored-by: StraubCreative <zst@odoo.com>
Co-authored-by: samueljlieber <sali@odoo.com>
Co-authored-by: fpodoo <fp@odoo.com>
@ -2,22 +2,887 @@
|
||||
WhatsApp
|
||||
========
|
||||
|
||||
**WhatsApp** is a messaging mobile app that allows users to send messages, make calls, and share
|
||||
content. Businesses can use `WhatsApp Business
|
||||
**WhatsApp** is an instant messaging and voice-over-IP app that allows users to send messages, make
|
||||
calls, and share content. Businesses can use `WhatsApp Business
|
||||
<https://developers.facebook.com/products/whatsapp/>`_ to communicate with their customers by text,
|
||||
send documents and provide support.
|
||||
|
||||
With the **Odoo WhatsApp** app, you can connect your WhatsApp Business Account (WABA) to your Odoo
|
||||
database, which allows you to:
|
||||
With the **Odoo WhatsApp** app, a company can connect a WhatsApp Business Account (WABA) to an Odoo
|
||||
database, which allows for the following:
|
||||
|
||||
- Receive and reply to WhatsApp messages directly from your Odoo database
|
||||
- Send pre-approved templates that use dynamic values, such as:
|
||||
- Receive and reply to WhatsApp messages directly from an Odoo database
|
||||
- Create new templates with dynamic placeholders/variables
|
||||
- Send pre-approved templates that use dynamic variables, such as:
|
||||
|
||||
- Quotations from the Sales app
|
||||
- Receipts and invoices from the Point of Sale app
|
||||
- Tickets from the Events app
|
||||
|
||||
.. seealso::
|
||||
- `Meta Business: create message templates for your WhatsApp Business account <https://www.facebook.com/business/help/2055875911147364>`_
|
||||
- `Meta Business: connect your phone number to your WhatsApp Business account <https://www.facebook.com/business/help/456220311516626>`_
|
||||
- `Meta Business: change your WhatsApp Business display name <https://www.facebook.com/business/help/378834799515077>`_
|
||||
- `Meta Business: create message templates for the WhatsApp Business account
|
||||
<https://www.facebook.com/business/help/2055875911147364>`_.
|
||||
- `Meta Business: connect a phone number to the WhatsApp Business account
|
||||
<https://www.facebook.com/business/help/456220311516626>`_.
|
||||
- `Meta Business: change the WhatsApp Business display name
|
||||
<https://www.facebook.com/business/help/378834799515077>`_.
|
||||
|
||||
WhatsApp is a messaging service operated by Meta, which is the parent company of Facebook. WhatsApp
|
||||
is commonly used as a communication tool in many countries and by many businesses. This
|
||||
documentation will cover the integration of a WhatsApp Business Account with Odoo. The company's
|
||||
Meta account is configured in Odoo via an :abbr:`API (Application Programming Interface)`
|
||||
connection.
|
||||
|
||||
The WhatsApp connector supports two flows: company initiated, and customer initiated. A company can
|
||||
initiate a discussion by sending a template to one or more people. Once the template is sent, the
|
||||
recipient can answer in order to trigger a discussion between the sender and the receiver (a
|
||||
*Discuss* chat window will pop up if the customer answers within 15 days).
|
||||
|
||||
If the discussion is initiated by the client (e.g. by sending to the company's public WhatsApp
|
||||
number), then Odoo will open a group chat with all operators responsible for this WhatsApp channel.
|
||||
|
||||
.. tip::
|
||||
It is recommended to set up multiple WhatsApp accounts for different departments. For example,
|
||||
the help desk team and sales teams can chat on different channels.
|
||||
|
||||
WhatsApp configuration in a Meta
|
||||
================================
|
||||
|
||||
A WhatsApp integration with Odoo uses a standard :abbr:`API (Application Programming Interface)`
|
||||
connection, and is configured on Meta in the following steps:
|
||||
|
||||
#. Create a Meta business account
|
||||
#. Create a Meta developer account
|
||||
#. Setup an *app* and WhatsApp *product* on Meta's developer console
|
||||
#. Test the API connection.
|
||||
|
||||
Once connected, messages are then sent and received through Odoo's *Discuss* application using the
|
||||
WhatsApp :abbr:`API (Application Programming Interface)`.
|
||||
|
||||
Meta business account setup
|
||||
---------------------------
|
||||
|
||||
To create a Business account with Meta (owner of Facebook) navigate to: `Facebook Business Manager
|
||||
<https://business.facebook.com/overview>`_. Begin by clicking :guilabel:`Create account` and then
|
||||
enter the business name, the administrator's name, and a work email address. Then click
|
||||
:guilabel:`Next`, and a pop-up window will appear prompting to confirm the email address. After
|
||||
confirming, click :guilabel:`Done` to close the window.
|
||||
|
||||
Next, follow the instructions in the email sent by Facebook to confirm the creation of the business
|
||||
account and to complete the setup process.
|
||||
|
||||
.. seealso::
|
||||
`Set up a Meta business account
|
||||
<https://www.facebook.com/business/help/1710077379203657?id=180505742745347>`_.
|
||||
|
||||
.. important::
|
||||
If the business account is linked to a personal Facebook account then the administrator must
|
||||
toggle between the personal account to the business account for the remainder of the
|
||||
configuration.
|
||||
|
||||
To toggle to the business account navigate to the `Facebook Developer Console
|
||||
<https://developers.facebook.com>`_ and click on the *account name* in the upper right corner.
|
||||
Under the :guilabel:`Business Accounts` heading, click on the desired business that the WhatsApp
|
||||
configuration should take place in. This will be the account for which Odoo will send and receive
|
||||
WhatsApp messages.
|
||||
|
||||
.. image:: whatsapp/toggle.png
|
||||
:align: center
|
||||
:alt: Toggle between Meta personal and business accounts.
|
||||
|
||||
.. important::
|
||||
In order to create a Meta business account, the user must already have a personal Facebook
|
||||
account that has existed for a minimum of one hour prior to setting up the Facebook Business
|
||||
account. Trying to create the business account prior to this time will result in an error.
|
||||
|
||||
App creation
|
||||
------------
|
||||
|
||||
On the `Meta for Developers <https://developers.facebook.com>`_ dashboard, sign in with the Meta
|
||||
developer account. If no account is configured yet, link a Facebook account to create a Meta
|
||||
developer account.
|
||||
|
||||
.. note::
|
||||
A Facebook *developer* account is different than a Facebook *business* account. While developer
|
||||
accounts are made up of personal Facebook accounts, business accounts are **not** as they
|
||||
represent a business and manage all of the business's assets in Meta, such as apps.
|
||||
|
||||
.. seealso::
|
||||
`Set up the WhatsApp Business Platform
|
||||
<https://www.facebookblueprint.com/student/collection/409587/path/360218>`_.
|
||||
|
||||
Click on :guilabel:`My Apps` in the top right corner after successfully signing in to the Meta
|
||||
developer account. This will redirect the administrator to all the apps the developer has configured
|
||||
in this specific developer account. Click on :guilabel:`Create App` to begin the process of
|
||||
configuring a new Meta application.
|
||||
|
||||
App type
|
||||
--------
|
||||
|
||||
On the :menuselection:`Create an app` page, select :guilabel:`Other` under the section labeled,
|
||||
:guilabel:`Looking for something else?`, and then click :guilabel:`Next` to be directed to another
|
||||
page in order to select the app type. Then, click on the first option listed under the
|
||||
:guilabel:`Select an app type` label, titled :guilabel:`Business`. This selection allows for the
|
||||
creation and management of the WhatsApp :abbr:`API (Application Programming Interface)`.
|
||||
|
||||
Now, click :guilabel:`Next` to configure the app, as desired. When the app *type* has been
|
||||
configured, the administrator will move onto the app *details* section.
|
||||
|
||||
App details
|
||||
-----------
|
||||
|
||||
On the :guilabel:`Details` section of the :guilabel:`Create an app` process, enter `Odoo` in the
|
||||
field under the :guilabel:`Add an app name` label.
|
||||
|
||||
.. note::
|
||||
The app name can be changed at a later time in the settings, if necessary.
|
||||
|
||||
.. warning::
|
||||
Trademarks and branded elements may not be used in this text section. These include the Meta
|
||||
group of companies. Do not include the word: `WhatsApp` or the system will flag this in error.
|
||||
|
||||
Next, enter the developer email address in the field under the :guilabel:`App contact email` label.
|
||||
|
||||
Lastly, set the :guilabel:`Business Account - Optional` field to the Meta business account profile,
|
||||
using the drop-down menu. To finish, click :guilabel:`Create app`. This action will create the app
|
||||
and prompts the *Meta Platform Terms* and *Developer Policies* agreements.
|
||||
|
||||
To accept the agreements, enter the Facebook password for security purposes, and click
|
||||
:guilabel:`Submit` to finalize the app creation. The browser will then direct to the :guilabel:`Meta
|
||||
for Developers` dashboard.
|
||||
|
||||
.. note::
|
||||
If the Meta business account is prohibited from advertising, claiming an app won't be allowed. To
|
||||
resolve this issue navigate to `<https://business.facebook.com/business>`_ for assistance.
|
||||
|
||||
For more information, see `Meta's documentation on advertising restrictions
|
||||
<https://www.facebook.com/business/help/975570072950669>`_.
|
||||
|
||||
Add a WhatsApp product to the app
|
||||
---------------------------------
|
||||
|
||||
Now that the basic structure of the app has been created, a product will need to be added to the
|
||||
app. Begin by accessing the Meta app dashboard by navigating to
|
||||
`<https://developers.facebook.com/apps>`_, and clicking on the app that is being configured.
|
||||
|
||||
On the next page: since WhatsApp will be used, click :guilabel:`Set up` next to the box containing
|
||||
WhatsApp, located towards the bottom of the page.
|
||||
|
||||
.. seealso::
|
||||
`Meta's WhatsApp developer documentation <https://developers.facebook.com/docs/whatsapp/>`_.
|
||||
|
||||
The page then directs to the configuration page for the :guilabel:`WhatsApp Business Platform API`.
|
||||
Use the drop-down menu to select the Meta business to be configured for the :guilabel:`Select a Meta
|
||||
Business Account` option, and then click :guilabel:`Continue` to confirm the selection.
|
||||
|
||||
.. note::
|
||||
When :guilabel:`Continue` is clicked, the administrator agrees to Meta's terms and conditions as
|
||||
linked on the :guilabel:`Meta App Dashboard`.
|
||||
|
||||
.. note::
|
||||
Once the WhatsApp product is added to the app, Meta will provide a WhatsApp test phone number
|
||||
with 5 test messages.
|
||||
|
||||
Start using the WhatsApp API
|
||||
----------------------------
|
||||
|
||||
After finishing the previous WhatsApp product wizard, and clicking :guilabel:`Continue`, the browser
|
||||
should have directed to the WhatsApp :guilabel:`Quickstart` page; this :guilabel:`Quickstart` page
|
||||
is where to begin configuring the WhatsApp API by adding a phone number and then sending an initial
|
||||
test message.
|
||||
|
||||
.. image:: whatsapp/quickstart.png
|
||||
:align: center
|
||||
:alt: Navigating to the WhatsApp quickstart wizard in Meta for Developer dashboard.
|
||||
|
||||
.. note::
|
||||
If the browser isn't on the :guilabel:`Quickstart` page for WhatsApp, navigate to
|
||||
`<https://developers.facebook.com/apps>`_ and click on the app that is being configured, (the
|
||||
app name is `Odoo` if the instructions above were followed).
|
||||
|
||||
Then, in the menu on the left-hand side of the page, click the :guilabel:`v (menu toggle)` icon
|
||||
next to the :guilabel:`WhatsApp` section heading. A small menu will open, containing the
|
||||
following options:
|
||||
|
||||
- :guilabel:`Quickstart`
|
||||
- :guilabel:`API Setup`
|
||||
- :guilabel:`Configuration`
|
||||
|
||||
Click the :guilabel:`Quickstart` option, and then click :guilabel:`Start using the API`.
|
||||
|
||||
API Setup
|
||||
~~~~~~~~~
|
||||
|
||||
After clicking on :guilabel:`Start using the API`, the page navigates to the :guilabel:`API Setup`.
|
||||
Now that the test number has been created, a test message can be sent to confirm that WhatsApp is
|
||||
working properly. To begin, navigate to the section on the page labeled :guilabel:`Send and receive
|
||||
messages` and click the drop-down menu next to :guilabel:`To`, under :guilabel:`Step 1 Select phone
|
||||
numbers`.
|
||||
|
||||
Now, select the only option available: :guilabel:`Manage phone number list`. Follow the steps and
|
||||
add up to five numbers to send the free test messages to. After entering the appropriate country
|
||||
code and phone number, click on :guilabel:`Next`.
|
||||
|
||||
.. important::
|
||||
Adding a phone number to send to in this step will allow for a successful test to be sent by the
|
||||
terminal. This is critical to ensure the WhatsApp :abbr:`API (Application Programming Interface)`
|
||||
is working.
|
||||
|
||||
A verification code from WhatsApp Business is then sent to the phone number, which needs to be input
|
||||
on the next screen to verify ownership of the number. Enter the verification code and click
|
||||
:guilabel:`Next` to verify the number.
|
||||
|
||||
Send a test message via terminal
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Next, send a test message via the terminal. Under the section labeled :guilabel:`Step 2 Send
|
||||
messages with the API`, click :guilabel:`Send Message`. A test message will then be sent to the
|
||||
phone number that was set in the previous section.
|
||||
|
||||
Upon successfully receiving the message to the number, move onto the next section to produce and
|
||||
configure webhooks.
|
||||
|
||||
.. _productivity/whatsapp/webhooks:
|
||||
|
||||
WhatsApp configuration in Odoo
|
||||
==============================
|
||||
|
||||
The next steps configured in this section are all within the Odoo database. A few different values
|
||||
for a token, phone number, and account IDs all need to be configured in Odoo; these values are
|
||||
necessary in order to create a :guilabel:`Callback URL` and :guilabel:`Webhook Verify Token`, which
|
||||
are then used to configure the webhooks (in order to receive messages back into the database).
|
||||
|
||||
In Odoo, navigate to :menuselection:`WhatsApp app --> Configuration --> WhatsApp Business Accounts`.
|
||||
Then click :guilabel:`New` to configure the WhatsApp business account in Odoo.
|
||||
|
||||
In another browser tab, navigate to :menuselection:`https://developers.facebook.com --> My Apps -->
|
||||
WhatsApp --> API Configuration`, and then copy the following values from the Meta developer console
|
||||
into the corresponding fields in Odoo:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:stub-columns: 1
|
||||
|
||||
* - Name
|
||||
- Meta Console
|
||||
- Odoo Interface
|
||||
* - Phone
|
||||
- :guilabel:`Phone number ID`
|
||||
- :guilabel:`Phone Number ID`
|
||||
* - Token
|
||||
- :guilabel:`Temporary access token`
|
||||
- :guilabel:`Access Token`
|
||||
* - App ID
|
||||
- :guilabel:`App ID`
|
||||
- :guilabel:`App ID`
|
||||
* - Account ID
|
||||
- :guilabel:`WhatsApp Business Account ID`
|
||||
- :guilabel:`Account ID`
|
||||
|
||||
To retrieve the :guilabel:`App Secret`, navigate to the Meta developer console,
|
||||
`<https://developers.facebook.com/apps>`_ and select the app that Odoo is being configured in. Then
|
||||
in the left-side menu, under :guilabel:`App settings`, select :guilabel:`Basic`.
|
||||
|
||||
Next, click :guilabel:`Show` next to the field :guilabel:`App secret`, and enter the account
|
||||
password to verify ownership. Copy the :guilabel:`App secret` and then paste that copied value into
|
||||
the :guilabel:`App Secret` field on the Odoo :guilabel:`WhatsApp Business Account` configuration
|
||||
dashboard.
|
||||
|
||||
To complete the setup of the WhatsApp business account in Odoo, click :guilabel:`Test Connection`. A
|
||||
successful message in green will populate in the upper-right corner of the dashboard if the
|
||||
configuration is set correctly.
|
||||
|
||||
Configuring webhooks
|
||||
--------------------
|
||||
|
||||
To configure the webhooks for WhatsApp in Odoo, navigate to
|
||||
`<https://developers.facebook.com/apps>`_ and select the app that Odoo is being configured in. Next
|
||||
under the :guilabel:`WhatsApp` menu heading on the left side of the screen, click on the
|
||||
:guilabel:`API Setup` menu item. Finally go to the section marked :guilabel:`Step 3: Configure
|
||||
webhooks to receive messages` and click on :guilabel:`Configure webhooks`.
|
||||
|
||||
.. tip::
|
||||
Another way to configure *Webhooks* is to navigate to `<https://developers.facebook.com/apps>`_
|
||||
and select the app that Odoo is being configured in. Then select :guilabel:`Webhooks` in the left
|
||||
hand menu.
|
||||
|
||||
.. image:: whatsapp/webhooks.png
|
||||
:align: center
|
||||
:alt: Manually navigating to the Whatsapp webhooks configuration.
|
||||
|
||||
On the :menuselection:`Webhook configuration` page, click on :guilabel:`Edit`, where both the
|
||||
:guilabel:`Callback URL` and :guilabel:`Webhook Verify Token` values from the Odoo will be added.
|
||||
|
||||
.. note::
|
||||
Both the :guilabel:`Callback URL` and :guilabel:`Webhook Verify Token` values were automatically
|
||||
populated after clicking on :guilabel:`Test Connection` in the previous step.
|
||||
|
||||
In a separate browser window, retrieve the necessary values in Odoo by navigating to
|
||||
:menuselection:`WhatsApp app --> Configuration --> WhatsApp Business Accounts` and select the
|
||||
account that is being configured. Locate the values under the section labeled :guilabel:`Receiving
|
||||
Messages`.
|
||||
|
||||
Copy and paste the :guilabel:`Callback URL` from Odoo into the :guilabel:`Callback URL` field in
|
||||
Meta. Similarly, copy and paste the :guilabel:`Webhook Verify Token` into the :guilabel:`Verify
|
||||
Token` field on the Meta developer console, as well.
|
||||
|
||||
Finally, click :guilabel:`Verify and save` to record the values in the Meta developer console.
|
||||
|
||||
Webhook fields
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Now input individual webhook fields into Meta's developer console, under the :guilabel:`Webhook
|
||||
fields` section. Click :guilabel:`Manage` and when the pop-up window appears, check the boxes in the
|
||||
:guilabel:`Subscribe` column for the following *field names*:
|
||||
|
||||
- account_update
|
||||
- message_template_quality_update
|
||||
- message_template_status_update
|
||||
- messages
|
||||
- template_category_update
|
||||
|
||||
After making the selections, click :guilabel:`Done`.
|
||||
|
||||
The finished :guilabel:`Webhooks` configuration will appear like this in the Meta developer console:
|
||||
|
||||
.. image:: whatsapp/webhooks-done.png
|
||||
:align: center
|
||||
:alt: WhatsApp webhooks set in the Meta developer console.
|
||||
|
||||
.. important::
|
||||
The :guilabel:`Webhook fields` will only appear once the subscription is confirmed using the
|
||||
:guilabel:`Callback URL` and :guilabel:`Webhook Verify Token`.
|
||||
|
||||
.. seealso::
|
||||
`Meta's WhatsApp documentation on setting webhooks
|
||||
<https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks>`_.
|
||||
|
||||
Add phone number
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
To configure the phone number to use for WhatsApp in Odoo, navigate back to the Meta developer
|
||||
console (`<https://developers.facebook.com/apps>`_) and again select the app that Odoo is being
|
||||
configured in. Under the :guilabel:`WhatsApp` menu heading on the left side of the screen, click on
|
||||
the :guilabel:`API Setup` menu item. From there, go to the section marked: :guilabel:`Step 5: Add a
|
||||
phone number`, and click on :guilabel:`Add phone number`.
|
||||
|
||||
In the fields, enter a :guilabel:`Business name` as well as a :guilabel:`Business website or profile
|
||||
page`.
|
||||
|
||||
.. tip::
|
||||
The :guilabel:`Business website or profile page` field can be a social media page's :abbr:`URL
|
||||
(Uniform Resource Locator)`.
|
||||
|
||||
Complete filling out the business information by next selecting the country that the company does
|
||||
business in from the drop-down menu in the :guilabel:`Country` section. Add an address if desired,
|
||||
however, this information is optional. After adding the location, click :guilabel:`Next` to
|
||||
continue.
|
||||
|
||||
The following page contains information for the :guilabel:`WhatsApp Business profile`. Complete the
|
||||
following sections, accordingly:
|
||||
|
||||
- :guilabel:`WhatsApp Business Profile Display Name`
|
||||
- :guilabel:`Timezone`
|
||||
- :guilabel:`Category`
|
||||
- :guilabel:`Business description` (optional)
|
||||
|
||||
Once these sections are complete, click :guilabel:`Next`. The page refreshes and then prompts the
|
||||
administrator to :guilabel:`Add a phone number for WhatsApp` in the respective field. Here, enter
|
||||
the phone number to configure in WhatsApp.
|
||||
|
||||
.. seealso::
|
||||
`Migrate an Existing WhatsApp Number to a Business Account
|
||||
<https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/migrate-existing-whatsapp-
|
||||
number-to-a-business-account>`_.
|
||||
|
||||
Next, choose a verification method for the phone number. Select either :guilabel:`Text message` or
|
||||
:guilabel:`Phone call`, and then click :guilabel:`Next` proceed.
|
||||
|
||||
The phone number entered will receive either a text or a phone call by WhatsApp with a code,
|
||||
depending on the verification method chosen. Enter that verification code into the
|
||||
:guilabel:`Verification code` field and click :guilabel:`Next` to finish.
|
||||
|
||||
.. warning::
|
||||
If a payment method hasn't been added this will be necessary to proceed. `Visit Meta's
|
||||
documentation on how to add a payment method in Meta's Business Manager
|
||||
<https://www.facebook.com/business/help/915454841921082?id=180505742745347>`_. This is part of
|
||||
Meta's fraud detection system, in order to ensure that the account/company are real a payment
|
||||
method is required to proceed.
|
||||
|
||||
.. seealso::
|
||||
`Meta for Developers: Add a Phone Number
|
||||
<https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/add-a-phone-number>`_.
|
||||
|
||||
.. _productivity/whatsapp/token:
|
||||
|
||||
Permanent token
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
After configuration and testing are complete, a permanent token should be created to replace the
|
||||
:guilabel:`Temporary token`.
|
||||
|
||||
.. seealso::
|
||||
`Meta for Developers: System User Access Tokens
|
||||
<https://developers.facebook.com/docs/whatsapp/business-management-api/get-started#system-user-
|
||||
access-tokens>`_.
|
||||
|
||||
Begin by navigating to `<https://business.facebook.com/>`_ and then go to :menuselection:`Business
|
||||
settings --> User --> System Users`. Select an existing system user or create a new system user by
|
||||
clicking on :guilabel:`Add`.
|
||||
|
||||
Assets now must be added to the system user and then a permanent token can be generated.
|
||||
|
||||
Click on :guilabel:`Add assets`, and when the pop-up window appears select :guilabel:`Apps` under
|
||||
the :guilabel:`Select asset type`. Then, select the Odoo app and toggle the permissions to *On*
|
||||
under the :guilabel:`Full control` option. Set this new permission setting by clicking
|
||||
:guilabel:`Save Changes`, to which a confirmation window will appear, acknowledging the addition of
|
||||
the asset to the system user. Finish by clicking :guilabel:`Done`.
|
||||
|
||||
Next, the permanent token will be generated. Click on :guilabel:`Generate new token`, and a pop-up
|
||||
window will appear asking which app this token should be generated for. Select the :guilabel:`App`
|
||||
that this token is for. Then determine the expiration date of either :guilabel:`60 days` or
|
||||
:guilabel:`Never`.
|
||||
|
||||
Finally, when Meta asks which permissions should the system user allow, add all of the following
|
||||
permissions:
|
||||
|
||||
- WhatsApp_business_messaging
|
||||
- WhatsApp_business_management
|
||||
|
||||
When permissions are set, click :guilabel:`Generate token`. Copy the token value that populates on
|
||||
the screen that follows.
|
||||
|
||||
With that token value, update the :guilabel:`Access Token` field in the WhatsApp business account in
|
||||
Odoo by navigating to :menuselection:`WhatsApp app --> Configuration --> WhatsApp Business
|
||||
Accounts`.
|
||||
|
||||
Go live with the Meta app
|
||||
=========================
|
||||
|
||||
Finally, to launch the app, the Meta app must be set to :guilabel:`Live` in the Meta developer
|
||||
console. Navigate to `<https://developers.facebook.com/apps>`_ and click on the app that is being
|
||||
configured. In the top menu, toggle the :guilabel:`App Mode` field from :guilabel:`Development` to
|
||||
:guilabel:`Live`.
|
||||
|
||||
.. important::
|
||||
If the app status is not set to *live*, then the database will only be able to contact the test
|
||||
numbers specified in the developer console.
|
||||
|
||||
.. warning::
|
||||
A privacy policy URL must be set in order for the app to be set to live. Go to the Meta developer
|
||||
console, `<https://developers.facebook.com/apps>`_ and select the app that Odoo is being
|
||||
configured in. Then, using the menu on the left side of the screen, go to :menuselection:`App
|
||||
Settings --> Basic`. Then, enter the privacy policy hyperlink address under the
|
||||
:guilabel:`Privacy Policy URL` field of the form. Click :guilabel:`Save changes` to apply the
|
||||
privacy policy to the app.
|
||||
|
||||
Once the app has gone live in the Meta developer console, a confirmation email is sent to the
|
||||
administrator.
|
||||
|
||||
.. _productivity/whatsapp/templates:
|
||||
|
||||
WhatsApp templates
|
||||
==================
|
||||
|
||||
WhatsApp templates are saved messages that are used repeatedly to send messages from the database.
|
||||
They allow users to send quality communications, without having to compose the same text repeatedly.
|
||||
|
||||
Creating different templates that are tailored to specific situations lets users choose the right
|
||||
message for the right audience. This increases the quality of the message and the overall
|
||||
engagement rate with the customer.
|
||||
|
||||
WhatsApp templates can be created on both the Odoo and Meta consoles. The following process will
|
||||
overview the process for creating templates in Odoo and then afterward in Meta.
|
||||
|
||||
.. important::
|
||||
WhatsApp has an approval process that must be completed before the template can be used.
|
||||
:ref:`productivity/whatsapp/approval`.
|
||||
|
||||
.. _WhatsApp/templates:
|
||||
|
||||
Creating templates in Odoo
|
||||
--------------------------
|
||||
|
||||
To access and create WhatsApp templates, begin by navigating to the :menuselection:`WhatsApp app -->
|
||||
Templates` dashboard.
|
||||
|
||||
At the bottom of an individual template's form, there are three tabs: :guilabel:`Body`,
|
||||
:guilabel:`Buttons`, and :guilabel:`Variables`; these three tabs combined create the WhatsApp
|
||||
template.
|
||||
|
||||
The text is entered into the :guilabel:`Body` tab, and dynamic content that is called out in the
|
||||
:guilabel:`Body` tab is specified in the :guilabel:`Variables` tab. Every piece of dynamic content
|
||||
(e.g., placeholders) in the message (body) is specifically called out and specified in the
|
||||
:guilabel:`Variables` tab.
|
||||
|
||||
Templates are prefabricated layouts that allow users to send professional looking messages to
|
||||
customers. These templates are capable of containing dynamic data that will populate in the end
|
||||
message using variables that are set in the template configuration. For example, messages can
|
||||
contain the end user's name, call out specific products, or reference a sales order, to name a few
|
||||
convenient and impactful variables.
|
||||
|
||||
To create a WhatsApp template, go to the :menuselection:`WhatsApp app --> Templates` dashboard and
|
||||
click :guilabel:`New`. On the form, enter a :guilabel:`Name` for the template, and select a
|
||||
:guilabel:`Language`.
|
||||
|
||||
.. important::
|
||||
In order to complete this next task, administrator access rights are needed to edit the
|
||||
:guilabel:`Applies to` field. See this :doc:`access rights documentation
|
||||
<../general/users/access_rights>` for more information.
|
||||
|
||||
In the :guilabel:`Account` drop-down menu, select the *WhatsApp business account* in Odoo that this
|
||||
template should link to. Next, under the :guilabel:`Applies to` field select the *model* the server
|
||||
action will apply to for this template.
|
||||
|
||||
.. tip::
|
||||
These models can also be accessed in :ref:`developer mode <developer-mode>`. On a contact form
|
||||
(or similar relevant form in Odoo), navigate to the model that will be referenced, and hover over
|
||||
any field name. A box of backend information will reveal itself with the specific Odoo
|
||||
:guilabel:`Model` name in the backend. Search (using the front-end name) for this model in the
|
||||
:guilabel:`Applies to` drop-down menu in the WhatsApp template.
|
||||
|
||||
.. warning::
|
||||
Often when changing the model or :guilabel:`Applies to` field, the :guilabel:`Phone Field` may
|
||||
produce an error The :guilabel:`Phone Field` should always be set to the `Phone` or `Mobile`
|
||||
model.
|
||||
|
||||
To search available fields, type in the front-end name in the :guilabel:`Search...` box. This will
|
||||
find a result from all of the available fields for the model (:guilabel:`Applies to`) that the
|
||||
template is created for.
|
||||
|
||||
.. note::
|
||||
In order to find specific fields, multiple levels may need to be navigated in the search results
|
||||
box. Use the :guilabel:`> (right chevron)` and :guilabel:`⬅️ (left arrow)` icons to navigate
|
||||
between the menu levels.
|
||||
|
||||
.. image:: whatsapp/phone-field.png
|
||||
:align: center
|
||||
:alt: Searching for the phone field in the search bar.
|
||||
|
||||
Change the :guilabel:`Category` to fit either a :guilabel:`Marketing`, :guilabel:`Utility`, or
|
||||
:guilabel:`Authentication` category. In most instances the first two options will be used, unless
|
||||
the user would like to send a password reset or something security related. Set to
|
||||
:guilabel:`Marketing` should there be anything promotional being sent and set to :guilabel:`Utility`
|
||||
should there be general transactional messages being sent (i.e., sales order, event ticket, etc).
|
||||
|
||||
.. important::
|
||||
Specifying an incorrect category can cause a flag/rejected status from Meta during the approval
|
||||
process.
|
||||
|
||||
Add any :guilabel:`Users` that are allowed to use this template. In the right-side column, a
|
||||
:guilabel:`Header type` can be configured along with a :guilabel:`Header message`, as well.
|
||||
|
||||
The available :guilabel:`Header types` are as follows:
|
||||
|
||||
- Text
|
||||
- Image
|
||||
- Video
|
||||
- Document
|
||||
- Location (variables need to be set)
|
||||
|
||||
Navigate to the :guilabel:`Body` tab to configure the main message of the template.
|
||||
|
||||
When all the necessary changes are made to the template, click on the :guilabel:`Submit for
|
||||
approval` button in the upper-left corner. This will cause the status of the template to change to
|
||||
:guilabel:`Pending`.
|
||||
|
||||
The status will remain in :guilabel:`Pending` until a decision has been made by Meta, whereby a
|
||||
confirmation email will then be sent indicating that the template has been approved (or rejected).
|
||||
The templates will then need to be synced from the Odoo database.
|
||||
|
||||
See this section for more information on :ref:`syncing templates <productivity/whatsapp/sync>`.
|
||||
|
||||
.. tip::
|
||||
There are pre-configured demo data templates available in Odoo to use or modify. These templates
|
||||
can be used as-is or modified to suit a specific business need.
|
||||
|
||||
To use these templates, navigate to :menuselection:`WhatsApp app --> Templates` and select a
|
||||
pre-configured template. Click :guilabel:`Submit for Approval` to start the approval process. An
|
||||
email will be sent to the administrator of the Meta account when the template has been approved.
|
||||
|
||||
Buttons
|
||||
~~~~~~~
|
||||
|
||||
Buttons can be added into the message from the :guilabel:`Buttons` tab. Enter the :guilabel:`Type`
|
||||
(either :guilabel:`Visit Website`, :guilabel:`Call Number`, or :guilabel:`Quick Reply`), and then
|
||||
specify the :guilabel:`Button Text`, :guilabel:`Call Number` or :guilabel:`Website URL` (including
|
||||
:guilabel:`Url Type`), depending on the :guilabel:`Type` of button.
|
||||
|
||||
.. note::
|
||||
Buttons can also be added on the Meta business console. See Meta's WhatsApp template dashboard by
|
||||
navigating to `<https://business.facebook.com/wa/manage/home>`_. Then go to
|
||||
:menuselection:`Account tools --> Message templates`.
|
||||
|
||||
Using placeholders and variables
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Dynamic variables reference certain fields within the Odoo database to produce unique data in the
|
||||
WhatsApp message when using a template. Dynamic variables are encoded to display fields from within
|
||||
the database, referencing fields from within a model.
|
||||
|
||||
.. example::
|
||||
Many companies like to customize their WhatsApp messages with a personalized piece of customer
|
||||
information to grab attention. This can be accomplished in Odoo by referencing a field within a
|
||||
model by setting a dynamic variable. For example, a customer's name can be referenced in the
|
||||
email from the :guilabel:`Customer` field on the :guilabel:`Sales Order` model.
|
||||
|
||||
.. image:: whatsapp/message.png
|
||||
:align: center
|
||||
:alt: WhatsApp message with dynamic variables highlighted.
|
||||
|
||||
Dynamic variables can be added in to the :guilabel:`Body` by adding :guilabel:`placeholders` in the
|
||||
*text*. To add a placeholder in the *message body* enter the following text `{{1}}`. For the second
|
||||
placeholder enter `{{2}}` and increase incrementally as more placeholders are added to the text.
|
||||
|
||||
.. example::
|
||||
*The following is the text from payment receipt template body:*
|
||||
|
||||
Dear {{1}},
|
||||
|
||||
| Here is your invoice *{{2}}* from *{{3}}* for a total of *{{4}}{{5}}*.
|
||||
| To review your invoice or pay online: {{6}}
|
||||
|
||||
Thank you
|
||||
|
||||
.. seealso::
|
||||
:ref:`productivity/whatsapp/templates`.
|
||||
|
||||
These placeholders must be configured on the :guilabel:`Variables` tab of the template before
|
||||
submitting for approval from Meta. To edit the dynamic variables on a template, first change the
|
||||
:guilabel:`Type` to :guilabel:`Field of Model`. This allows Odoo to reference a field within a model
|
||||
to produce unique data in the message being sent.
|
||||
|
||||
Next, edit the :guilabel:`Field` of the dynamic variables. The :guilabel:`Applies to` field in the
|
||||
template should be edited prior to ensure the correct model and field are referenced.
|
||||
|
||||
To search the available fields, type in the front-end name of the field in the search box. This will
|
||||
find a result from all of the available fields for the model (:guilabel:`Applies to`) that the
|
||||
template is created for. There may be multiple levels that need to be configured.
|
||||
|
||||
.. example::
|
||||
The following is an example of the variables set for the above placeholders in the payment
|
||||
receipt noted above:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:stub-columns: 1
|
||||
|
||||
* - Name
|
||||
- Sample Value
|
||||
- Type
|
||||
- Field
|
||||
* - body - {{1}}
|
||||
- Azure Interior
|
||||
- Field of Model
|
||||
- `Partner`
|
||||
* - body - {{2}}
|
||||
- INV/2022/00001
|
||||
- Field of Model
|
||||
- `Number`
|
||||
* - body - {{3}}
|
||||
- My Company
|
||||
- Field of Model
|
||||
- `Company`
|
||||
* - body - {{4}}
|
||||
- $
|
||||
- Field of Model
|
||||
- `Currency > Symbol`
|
||||
* - body - {{5}}
|
||||
- 4000
|
||||
- Field of Model
|
||||
- `Amount`
|
||||
* - body - {{6}}
|
||||
- \https://..
|
||||
- Portal link
|
||||
-
|
||||
|
||||
.. example::
|
||||
For example, in the :guilabel:`Body` tab, if the following is typed, "Hello {{1}},", then `{{1}}`
|
||||
must be set in the :guilabel:`Variables` tab. For this specific case, the message should greet
|
||||
the customer by name, so the `{{1}}` should be configured to populate the `{{1}}`
|
||||
:guilabel:`Field` with the :guilabel:`Customer` name.
|
||||
|
||||
.. warning::
|
||||
Customizing WhatsApp templates is out of the scope of Odoo Support.
|
||||
|
||||
.. _productivity/whatsapp/approval:
|
||||
|
||||
Meta template approval
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
After updating the dynamic variables on the template, the template needs to be submitted to Meta for
|
||||
approval again. Click :guilabel:`Submit for Approval` to start the approval process. An email will
|
||||
be sent to the administrator of the Meta account when the template has been approved.
|
||||
|
||||
Following the approval from Meta, sync the templates again in the Odoo database. See this
|
||||
documentation: :ref:`productivity/whatsapp/sync`.
|
||||
|
||||
.. tip::
|
||||
To see the status to Meta's WhatsApp template dashboard by navigating to
|
||||
`<https://business.facebook.com/wa/manage/home>`_. Then go to :menuselection:`Account tools -->
|
||||
Message templates`.
|
||||
|
||||
.. _productivity/whatsapp/sync:
|
||||
|
||||
Syncing templates
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Templates must be synced on the Odoo database once they are approved by the Meta team. To do so,
|
||||
begin by navigating to :menuselection:`WhatsApp app --> Configuration --> WhatsApp Business
|
||||
Accounts` and select the configuration that should be synced. Under the section marked
|
||||
:menuselection:`Sending messages`, towards the bottom, click on :guilabel:`Sync Templates`. Meta
|
||||
will update the templates that are approved so that they can be utilized with various apps in the
|
||||
database.
|
||||
|
||||
.. image:: whatsapp/sync-template.png
|
||||
:align: center
|
||||
:alt: Syncing Meta WhatsApp templates to the Odoo database, with the 'Sync Templates'
|
||||
highlighted.
|
||||
|
||||
A successful message in green appears in the upper-right corner with the number of templates
|
||||
updated.
|
||||
|
||||
.. tip::
|
||||
Templates can also be synced individually from the template itself. Navigate to the
|
||||
:menuselection:`WhatsApp app --> Templates` dashboard and select the template to sync. Then,
|
||||
click on the :guilabel:`Sync Template` button located in the top menu of the template's form.
|
||||
|
||||
Creating templates in Meta
|
||||
--------------------------
|
||||
|
||||
First, navigate to `Meta's WhatsApp template dashboard
|
||||
<https://business.facebook.com/wa/manage/home>`_, and then go to :menuselection:`Account tools -->
|
||||
Message templates`.
|
||||
|
||||
.. image:: whatsapp/account-tools.png
|
||||
:align: center
|
||||
:alt: Account tools highlighted in business manager with the manage templates link highlighted.
|
||||
|
||||
To create a WhatsApp template, click on the blue :guilabel:`Create template` button, and then select
|
||||
the :guilabel:`Category`. The options listed include: :guilabel:`Marketing`, :guilabel:`Utility`,
|
||||
and :guilabel:`Authentication`. In most instances the first two options will be used, unless the
|
||||
user would like to send a password reset or something security related.
|
||||
|
||||
Enter the :guilabel:`Name` of the template and then select the :guilabel:`Language` for the
|
||||
template.
|
||||
|
||||
.. note::
|
||||
Multiple languages can be selected by typing the language name(s) and selecting the other
|
||||
languages as needed.
|
||||
|
||||
.. image:: whatsapp/template-config.png
|
||||
:align: center
|
||||
:alt: Template configuration options listed, with Marketing, Utility, Name and Language
|
||||
highlighted.
|
||||
|
||||
After making the appropriate selections, click on :guilabel:`Continue` in the upper-right corner.
|
||||
The page redirects to the :guilabel:`Edit template` page. Here the :guilabel:`Header`,
|
||||
:guilabel:`Body`, :guilabel:`Footer` and :guilabel:`Buttons` are configured. To the right of the
|
||||
template is a preview of what the template will look like in production.
|
||||
|
||||
.. image:: whatsapp/edit-template.png
|
||||
:align: center
|
||||
:alt: Edit the template using a header, body, footer and buttons.
|
||||
|
||||
When all the necessary changes are made to the template, click on the :guilabel:`Submit` button in
|
||||
the upper-right corner. A confirmation window appears to confirm the language— click
|
||||
:guilabel:`Confirm` to approve and then another window appears stating that the template will be
|
||||
submitted to Meta for review and approval.
|
||||
|
||||
The :guilabel:`Status` of the template will remain in :guilabel:`In review` until a decision has
|
||||
been made by Meta. Once an email confirmation is received approving the template, the templates will
|
||||
need to be synced from within the Odoo database.
|
||||
|
||||
.. seealso::
|
||||
For more information on configuring templates on the Meta developer console visit `Meta's
|
||||
WhatsApp template documentation
|
||||
<https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/>`_.
|
||||
|
||||
Notifications
|
||||
=============
|
||||
|
||||
Notifications in WhatsApp are handled similar to a message conversation in Odoo. A pop-up window
|
||||
appears with the received conversation from the customer. By default, notifications are set in the
|
||||
WhatsApp business account configuration in Odoo.
|
||||
|
||||
Notification settings can be adjusted by navigating to :menuselection:`WhatsApp app -->
|
||||
Configuration --> WhatsApp Business Accounts`. From there, select the account and scroll down to the
|
||||
:menuselection:`Control` section where notifications are handled. Under the :guilabel:`Notify users`
|
||||
heading, type in the field which user(s) should be notified for this particular WhatsApp channel.
|
||||
|
||||
.. note::
|
||||
Once a conversation is initiated between a user and a customer, notifications to all the users
|
||||
specified in the WhatsApp business account configuration won't occur. Only notifications to the
|
||||
user(s) in the conversation will occur. Should the user not respond within 15 days, the
|
||||
customer's reply after the 15 days will populate once again to all the users specified in the
|
||||
WhatsApp configuration.
|
||||
|
||||
Adding users to chat
|
||||
====================
|
||||
|
||||
Users can be added to a WhatsApp chat by expanding the WhatsApp pop-up window. WhatsApp
|
||||
conversations are located in the *Discuss* app. Click on the :guilabel:`👤+ (add user)` icon next to
|
||||
it, and a window appears to invite users to the conversation.
|
||||
|
||||
.. image:: whatsapp/add-users.png
|
||||
:align: center
|
||||
:alt: Adding users to a WhatsApp conversation, with the add user icon highlighted.
|
||||
|
||||
WhatsApp API FAQ
|
||||
================
|
||||
|
||||
Verification
|
||||
------------
|
||||
|
||||
As of February 1, 2023, if the Meta app requires advanced level access to permissions, a complete
|
||||
business verification may need to be completed. This includes submitting office business documents
|
||||
to Meta. `See this documentation
|
||||
<https://developers.facebook.com/docs/development/release/business-verification>`_.
|
||||
|
||||
.. seealso::
|
||||
`Meta's WhatsApp access verification documentation
|
||||
<https://developers.facebook.com/docs/development/release/access-verification/>`_.
|
||||
|
||||
Template errors
|
||||
---------------
|
||||
|
||||
Editing templates can cause tracebacks and errors unless the exact process is followed above, here:
|
||||
(:ref:`productivity/whatsapp/templates`).
|
||||
|
||||
Duplicate validation error
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When syncing the templates there may be an instance when there are multiple templates with the same
|
||||
name on Meta's business manager and in Odoo. This causes a duplicate validation error. To correct
|
||||
this issue, rename the duplicate template name on Odoo and sync the templates once again by
|
||||
following the steps here: :ref:`productivity/whatsapp/sync`.
|
||||
|
||||
.. image:: whatsapp/validation-error-2.png
|
||||
:align: center
|
||||
:alt: User error populated in Odoo when a duplicate template exists.
|
||||
|
||||
Token errors
|
||||
------------
|
||||
|
||||
User error
|
||||
~~~~~~~~~~
|
||||
|
||||
Should the temporary token not be replaced with a permanent token a user error will populate in Odoo
|
||||
when testing the connection after sending fails. To correct this issues see
|
||||
:ref:`productivity/whatsapp/token`.
|
||||
|
||||
.. image:: whatsapp/user-error.png
|
||||
:align: center
|
||||
:alt: User error populated in Odoo when token expires.
|
||||
|
||||
System user error 100
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Should the system user be an :guilabel:`Employee` when setting up the permanent token, a user error
|
||||
100 will populate.
|
||||
|
||||
To correct this error, create an :guilabel:`Admin` system user, following the process outlined here:
|
||||
:ref:`productivity/whatsapp/token`.
|
||||
|
||||
.. image:: whatsapp/user-error-2.png
|
||||
:align: center
|
||||
:alt: User error populated in Odoo when an employee token is generated instead of a Admin user.
|
||||
|
BIN
content/applications/productivity/whatsapp/account-tools.png
Normal file
After Width: | Height: | Size: 10 KiB |
BIN
content/applications/productivity/whatsapp/add-users.png
Normal file
After Width: | Height: | Size: 20 KiB |
BIN
content/applications/productivity/whatsapp/edit-template.png
Normal file
After Width: | Height: | Size: 28 KiB |
BIN
content/applications/productivity/whatsapp/message.png
Normal file
After Width: | Height: | Size: 131 KiB |
BIN
content/applications/productivity/whatsapp/phone-field.png
Normal file
After Width: | Height: | Size: 19 KiB |
BIN
content/applications/productivity/whatsapp/quickstart.png
Normal file
After Width: | Height: | Size: 12 KiB |
BIN
content/applications/productivity/whatsapp/sync-template.png
Normal file
After Width: | Height: | Size: 14 KiB |
BIN
content/applications/productivity/whatsapp/template-config.png
Normal file
After Width: | Height: | Size: 23 KiB |
BIN
content/applications/productivity/whatsapp/toggle.png
Normal file
After Width: | Height: | Size: 10 KiB |
BIN
content/applications/productivity/whatsapp/user-error-2.png
Normal file
After Width: | Height: | Size: 9.8 KiB |
BIN
content/applications/productivity/whatsapp/user-error.png
Normal file
After Width: | Height: | Size: 7.4 KiB |
After Width: | Height: | Size: 6.6 KiB |
BIN
content/applications/productivity/whatsapp/webhooks-done.png
Normal file
After Width: | Height: | Size: 32 KiB |
BIN
content/applications/productivity/whatsapp/webhooks.png
Normal file
After Width: | Height: | Size: 13 KiB |