1. Introduction
This document describes the process required for an end user of i24 Use Cases to integrate with WhatsApp Business API and therefore, it is possible to receive and send messages via WhatsApp to end-users.
You can also download this document in .pdf here: i24 User Guide WhatsApp integration EN
| Information |
| Before proceeding, ensure you have an active Facebook account which can be promoted into a developer account to be used later for WhatsApp Business. |
2. Facebook Configuration
2.1. Configure your Facebook Developer App
First of all, it is required to create and configure Facebook (Meta) developer app, with WhatsApp Product.
There are 3 different ways to enable WhatsApp Business
- Cloud API – for direct usage with i24
- Through external provider:
- Through Tech providers
- Through Solution partners
The steps described below refer to the WhatsApp Business through Cloud API, where you are basically configuring WhatsApp Business for your own company or organization.
2.1.1. Facebook (Meta) developer account
This section explains how to register as a Meta developer. Once you have registered, you will have access to the App Dashboard and all of Meta products, SDKs, APIs development tools, and development documentation.
| Information |
| Instructions extracted from https://developers.facebook.com/docs/development/register |
Step 1: Start the registration process
While logged into your Facebook account, go to Facebook developers registration .
Alternatively, you can go to the Meta for Developers website and click Get Started.
Figure 1. Login into Facebook page and Facebook developers
As displayed in Figure 1, it is required to login first into Facebook and later login into Facebook developers registry.
Step 2: Agree to Facebook’s developers Terms and Policies
Figure 2. Agree on Meta for Developers Terms and Policies
As displayed in Figure 2, click Next to agree to Facebook’s developers Platform Terms and Developer Policies.
Step 3: Verify your account
Next, as shown in Figure 3, it is required to verify the Facebook account.
Figure 3. Verify Facebook account via SMS
A confirmation code will be sent to the phone number (Figure 4) and email address that you have provided in order to confirm that you have access to them (Figure 5). Your number and email will be used for important developer notifications of any changes that may impact your app.
Figure 4. Introduce code received by SMS
Figure 5. Verification of primary email account
Step 4: Select your occupation
Select an occupation that most closely describes what you do for a living, as displayed in Figure 6.
Figure 6. Occupation selection
Step 5: App Dashboard
Once the registration is completed, the App dashboard will be presented as displayed in Figure 7.
Figure 7. App dashboard for the new created Meta Developer account
2.1.2. Create an App
The app creation flow is defined to gather the minimum amount of information needed to generate a unique ID for your app. Once the flow is completed, you will end up on the Apps Dashboard where you can provide additional information about your app.
| Information |
| Instructions from https://developers.facebook.com/docs/development/create-an-app/ |
Prerequisites ( ⚠️ to be confirmed ⚠️)
You will need the following to create an app:
- A unique icon image for your app.
- Files must be between 512 x 512 and 1024 x 1024 pixels and in JPEG, GIF or PNG format. File size limit 5 MB.
- Contact information for a Data Protection Officer, if you are doing business in the European Union
- A URL to your Privacy Policy URL for your app
- A URL to instructions or a callback that allows a user to delete their data from your app
The type of Use Case to be selected for the App is Other App Types ( Explore other products and data permissions such as ads management, WhatsApp and more. You’ll be asked to select an app type and then you can add the permissions and products you need. )
Step 1. Start the app creation process
There are a number of ways to create an app, as shown in Figure 7.
- If you just came from the registration flow, click the Create First App button
- If you are on the App Dashboard, click Create App in the upper right
- If you are on the dashboard for an existing app and want to create a new app, select the dropdown menu in the upper left, and click the Create New App button
Step 2. Select a use case
Select Other and click the Next button, as displayed on Figure 8. You will be able to customize your use case later on the app Dashboard.
Figure 8. Create Other use case App
Step 3: Select an app type
Your selection regarding app type determines which products and APIs are available to your app.
The list of App Types is displayed below
| App Type | Description |
| Academic research | Connect to Facebook data and tooling to perform research on Facebook. |
| Business | Create or manage business assets like Pages, Events, Groups, Ads, Messenger, WhatsApp, and Instagram Graph API using the available business permissions, features, and products. |
| Consumer | Connect consumer products and permissions, like Facebook Login and Instagram Basic Display to your app. |
| Data transfer | Enable data transfer directly from Meta to other apps and services. |
| Gaming | Connect an off-platform game to Facebook Login. |
| Instant Games | Create an HTML5 game hosted on Facebook. |
| None | Create an app with combinations of consumer and business permissions and products. |
| Workplace | Create enterprise tools for Workplace from Meta. |
For i24 integration with WhatsApp Business, it is required to select Business App Type, as shown in Figure 9. Click on Next.
Figure 9. Business App Type selection
Step 4: App details
In this step you will add:
- A name for your app
- The email address to be used to contact you about this particular app
- Optionally, you can link this app to an existing Business Account using the dropdown menu, or you can add this later.
Figure 10. Provide app’s details
Click Create App to save your app’s details, as shown in Figure 10.
Once you have completed the app creation flow your app will be loaded in the app Dashboard and you will be able to select the products, permissions, and features you need to build your app, as shown in Figure 11.
Figure 11. Add products to your app
2.1.3. Configure your App with WhatsApp Cloud API.
At this point, if you created a new app, you’ll be prompted to Add products to your app. Scroll down, and under WhatsApp, select Set up, as displayed in Figure 12.
Figure 12. Set up WhatsApp into App
Otherwise, select your app from the My Apps screen, and you can follow the same instructions again to add WhatsApp to your app.
If you have a Meta Business Account (MBA), you will be prompted to attach it when adding the WhatsApp product to your app. If you don’t have an MBA, you’ll be taken through some prompts that will help you create one. Once your MBA is attached to your application, you’ll be ready to start testing.
Adding the WhatsApp product to your app does a few things for you:
- Step 1: Prompts you to create a Meta Business Account if you don’t have one.
- Step 2: Creates a test WhatsApp Business Account for you, automatically. This account has limitations and should be used for testing and development purposes since you don’t pay for messages.
- Step 3: Creates a test business phone number associated with your WhatsApp Business Account. With this number, you can send free messages to up to 5 recipient phone numbers.
- Step 4: Creates a set of pre-approved message templates.
Step 1: Create a Meta Business Account
If you do not already have a Meta Business Account, it is requested to create a new one.
Figure 13. Create WhatsApp Business Account – Step 1
Figure 14. Create WhatsApp Business Account – Step 2
Click on Create an account. The required inputs, as displayed in Figure 15, will be requested.
Figure 15. Create business account in Meta Business Manager
Once the required information is submitted to Meta to create the account in the Business Manager, a message is displayed to confirm the email address.
Figure 16. Message to request email confirmation from the user
After the email address is confirmed, then the account is created and it is displayed in the business settings page, as displayed in
Figure 17. Business settings page after email confirmation
Step 2: WhatsApp API Setup
Once the Meta Business account is created ( Figure 13 ), it is required to select the Meta Business account, as displayed on Figure 18.
Figure 18. Selection of account for WhatsApp API configuration
The API Setup is available, as displayed in Figure 19, where some key parameters are displayed:
- temporary access token
- Test number
- Phone number ID
- WhatsApp Business Account ID
Figure 19. WhatsApp API Setup
As it is provided with a test number, then it is required to define the numbers which will be able to receive messages for testing purposes. The process to add a new recipient number is described in Figure 20.
Figure 20. Process to add new recipient number for a testing number
Once the To numbers are configured, then it is highly recommended to test the number and the API configuration with the Send message button available, as displayed on Figure 21.
Figure 21. Test to send messages with the API
Figure 22. Result of send message test through WhatsApp Cloud API
Next step is to configure a Permanent Token which can be used in any 3rd party service serving the WhatsApp communication with this WhatsApp Business Account.
Go to Meta Business settings webpage and go to option Users > People. There, it should be displayed the Meta user and the corresponding settings for the new defined app, as displayed in Figure 23.
Figure 23. Meta Business settings to configure users
Then, it is required to go to option System Users. Click on Add button and create an admin user, as described in Figure 24.
Figure 24. Create a new system user with Admin role
The new system users should be listed in the corresponding list, as displayed on Figure 25.
Figure 25. System user settings once generated
Then, it is required to generate a Permanent Token, which will be the required one to send/receive messages to/from i24 and WhatsApp.
To do so, click on the “Generate new token” button. Then, as shown in Figure 26, select the App to generate the new permanent token. Select Never for Token Expiration. Select the corresponding required Permissions:
- whatsapp_business_management
- whatsapp_business_messaging
Click on the “Generate token” button.
Figure 26. Permanent token generation settings
When the token is generated, it is displayed on a dialog. Copy and save this token immediately, since it is not going to be visible again in the Meta Business Settings page for security reasons.
It will be possible to revoke the token in case it should be canceled for any of the apps using it.
Next step is to configure webhooks to receive events with the corresponding messages into i24. In the App Dashboard of Meta for Developers, go to the Configuration section within WhatsApp option, as displayed on Figure 27.
Figure 27. WhatsApp configuration within Meta for Developers App Dashboard
Click on the “Edit” button within the Webhook section and the dialog displayed in Figure 28 will be presented.
Figure 28. Webhook’s Callback URL configuration
⚠️lewis.falcon.80@gmail.com: Required callback URL and Verify Token to connect with channels-service in DO deployments
Once the webhook is enabled, then, it is required to configure the events to subscribe, or, in other words, to be notified by WhatsApp Cloud API. In Figure 29, the list of available fields is presented. It is required to, at least, subscribe to the event messages.
Figure 29. Webhooks fields configuration
When the webhook is configured, it is possible to test it with the following guide provided by Meta ( https://developers.facebook.com/docs/whatsapp/sample-app-endpoints ). From this guide, in the messages test, the following JSON response is received in the webhook with a test message.
| { “object”: “whatsapp_business_account”, “entry”: [ { “id”: “0”, “changes”: [ { “field”: “messages”, “value”: { “messaging_product”: “whatsapp”, “metadata”: { “display_phone_number”: “16505551111”, “phone_number_id”: “123456123” }, “contacts”: [ { “profile”: { “name”: “test user name” }, “wa_id”: “16315551181” } ], “messages”: [ { “from”: “16315551181”, “id”: “ABGGFlA5Fpa”, “timestamp”: “1504902988”, “type”: “text”, “text”: { “body”: “this is a text message” } } ] } } ] } ] } |
Once the webhook is configured, then it is required to assign a real number to the app instead of the testing number provided when the app is created for validation purposes. Therefore, it is required to click on the “Manage phone numbers” button, as shown in Figure 30.
Figure 30. Configuration of webhooks completed
It switches to the overview section within the WhatsApp Manager, as displayed in Figure 31.
Figure 31. Overview section in WhatsApp Manager
Then, to assign a real number to the WhatsApp Business account, click on the “Increase limits” button to launch the business verification process with Meta, as displayed in Figure 32.
Figure 32. Start business verification process with Meta
Click on the “Start verification” button. It will open the Security Center for the WhatsApp settings, as displayed in Figure 33.
Figure 33. Security Center for WhatsApp Manager – Business verification
Click on the “Start verification” button. It will open another dialog to start the business verification process, as shown in Figure 34. Click on the “Get started” button.
Figure 34. Start business verification process
First question is to select the country where the business is located, as requested in Figure 35.
Figure 35. Business location
Click on Next to continue the verification process. Then, it is required to add additional business details for the business verification, as requested in Figure 36.
Figure 36. Business details for verification
The required information for business verification:
- Business name
- Business address ( street, city, province, postal code)
- Phone number ( where it is possible to receive confirmation numbers by SMS or WhatsApp)
- Business website
Once the required information is provided, then it should be reviewed and approved by Meta