WhatsApp Business API Integration Service

Praneeth Bilakanti

14 min readJul 5, 2023

1. Introduction

Purpose of the document: This document provides a comprehensive guide to integrating the WhatsApp Business API with a Spring Boot application, enabling businesses to communicate with their customers through WhatsApp.
Overview of the WhatsApp Business API integration: This section explains the benefits of integrating with the WhatsApp Business API, such as enhanced customer engagement and automated messaging capabilities.
Target audience: This documentation is intended for developers familiar with Spring Boot and Java who are responsible for implementing the integration.

2. Prerequisites

Required hardware and software: List the hardware and software requirements for setting up the integration, including the supported operating systems, JDK version, and any additional dependencies.
Access to the WhatsApp Business API: Provide instructions for obtaining access to the WhatsApp Business API, including any registration or approval processes required.
Knowledge of Spring Boot and Java: Mention the expected familiarity with Spring Boot and Java programming to successfully follow the integration guide.

3. Architecture Overview

High-level architecture diagram: Present a diagram illustrating the overall architecture of the WhatsApp Business API integration, including the relevant components and their interactions.

Components involved in the integration: Describe each component’s role in the integration, such as the Spring Boot application, WhatsApp Business API client, and any additional services or databases used.
Communication flow between the components: Explain the flow of data and messages between the Spring Boot application and the WhatsApp Business API, including the request/response structure and any callbacks or event notifications.

Step 1: Technical overview and architecture

The WhatsApp Cloud API is built on a RESTful architecture, leveraging standard HTTP methods (GET, POST, PUT, DELETE) to facilitate communication between your application and the WhatsApp platform. This architecture allows for a straightforward and universal language of communication, making it easier to integrate and interact with the API.

Step 2: Integration with WhatsApp Business

To begin using the WhatsApp Cloud API, you will need a WhatsApp Business account. This account serves as your business’s gateway to the WhatsApp ecosystem. It enables you to send and receive messages, create a business profile, and access various features offered by the WhatsApp Business platform. Once you have a WhatsApp Business account, you can proceed with integrating the API into your application.

Step 3: API endpoints and methods

The WhatsApp Cloud API consists of several endpoints, each designed to serve a specific purpose and functionality. These endpoints provide the necessary tools for building and managing your WhatsApp-powered communication infrastructure. Here are some key endpoints commonly used in the WhatsApp Cloud API:

Sending messages: This endpoint allows you to send messages to your customers or recipients on WhatsApp. You can send various types of messages, such as text messages, images, documents, and multimedia content.
Receiving messages: This endpoint enables your application to receive incoming messages from users or customers on WhatsApp. It allows you to process and respond to messages in real-time, creating interactive and engaging conversational experiences.
Managing contacts: This endpoint allows you to manage your contacts and address book on WhatsApp. You can add new contacts, update existing contacts, and retrieve contact information as needed.
Message templates: WhatsApp supports pre-defined message templates for specific use cases, such as order confirmations, shipping updates, and appointment reminders. This endpoint enables you to create and manage these templates, making it easier to send standardized and structured messages to your customers.
Media storage: WhatsApp Cloud API provides endpoints for managing media files, such as images, videos, and audio. You can upload media files to WhatsApp’s cloud storage and associate them with your messages or templates.

By leveraging these endpoints and their corresponding HTTP methods, your application can interact with the WhatsApp platform seamlessly, sending and receiving messages, managing contacts, and utilizing various features provided by the WhatsApp Business platform.

It’s important to refer to the official documentation and guidelines provided by WhatsApp for detailed information on each endpoint, including the request and response formats, required parameters, and any limitations or restrictions that apply.

Remember to handle API authentication, rate limiting, error handling, and other best practices to ensure a secure and reliable integration with the WhatsApp Cloud API.

4. Setup and Configuration

Step 1: Prerequisites and requirements

Before you can start using the WhatsApp Cloud API, you need to ensure you have the following prerequisites and requirements in place:

WhatsApp Business account: You’ll need a WhatsApp Business account to access the WhatsApp Cloud API. This involves downloading the WhatsApp Business app, signing up with your business phone number, and creating a business profile.
Phone number association: Make sure your WhatsApp Business account is associated with a phone number. This number will be used for sending and receiving messages through the API.
Verified Facebook Business Manager account: You’ll need a verified Facebook Business Manager account to access the WhatsApp Cloud API. If you don’t have one, create a Facebook Business Manager account and complete the verification process.
API access and credentials: To access the WhatsApp Cloud API, you need to apply for API access through the Facebook Business Manager. Once your application is approved, you’ll receive API credentials. These credentials serve as secret keys that grant access to the features and capabilities of the WhatsApp Cloud API.

Step 2: Creating a WhatsApp Business account

To create a WhatsApp Business account, follow these steps:

Download the WhatsApp Business app from the respective app store (iOS or Android).
Launch the app and sign up using your business phone number. Make sure it’s a dedicated phone number for your business.
Complete the verification process by entering the verification code sent to your phone number.
Set up your business profile by providing relevant information, such as your business name, logo, description, and contact details.

Step 3: Obtaining API access and credentials

To obtain API access and credentials, follow these steps:

Log in to your Facebook Business Manager account. If you don’t have an account, create one.
Navigate to the WhatsApp Business API section within the Business Manager interface.
Apply for API access by providing the necessary information, such as your business details, phone number, and use case for using the WhatsApp Cloud API.
Wait for your application to be reviewed and approved by WhatsApp. This process may take some time, as WhatsApp reviews applications to ensure compliance with their guidelines and policies.
Once your application is approved, you’ll receive API credentials, including a client ID and client secret. These credentials will be used to authenticate your requests to the WhatsApp Cloud API.

Keep your API credentials secure and ensure that only authorized personnel have access to them. These credentials unlock the potential of the WhatsApp Cloud API and should be treated with utmost care.

With API access and credentials in hand, you’re now ready to start integrating and utilizing the features of the WhatsApp Cloud API within your application.

https://developers.facebook.com/docs/whatsapp/cloud-api/get-started#configure-webhooks

5.Why Use the WhatsApp Cloud API?

Simplified Integration

Using the WhatsApp Cloud API makes it easier for businesses to integrate WhatsApp messaging, eliminating the need for self-hosting and reducing setup complexity.

Cost-Effectiveness

By offering a cloud-hosted solution, the WhatsApp Cloud API helps businesses save on server costs and maintenance, making it an affordable communication option.

Enhanced Customer Experience

With the WhatsApp Cloud API, businesses can provide real-time, personalized support, and updates to customers, improving overall customer satisfaction and experience.

Global Reach

WhatsApp has a massive user base, and the Cloud API enables businesses to tap into this audience, expanding their reach and connecting with customers worldwide.

Secure Messaging

The WhatsApp Cloud API ensures end-to-end encryption for all messages, protecting sensitive data and maintaining privacy for both businesses and customers.

6. API Reference

Detailed explanation of the available WhatsApp Business API endpoints: Document each API endpoint exposed by the WhatsApp Business API, including the purpose of the endpoint and the expected request and response formats.
Request and response examples for each endpoint: Provide code examples illustrating the structure of API requests and the corresponding response payloads.
Parameter descriptions and data formats: Explain the parameters accepted by each API endpoint, including their data types, required fields, and any validation rules or limitations.

7. Pricing

In the WhatsApp Business API, conversations are categorized based on how they are initiated and have different pricing models. Here are the main categories and pricing details:

User-initiated conversations:
User-initiated conversations are those that start in response to a user’s message.
When a business replies to a user within the 24-hour customer service window, it is considered a user-initiated conversation.
Businesses can send free-form messages within this 24-hour window without additional charges.
The pricing for user-initiated conversations may vary by market (country or region) and is based on the country code of the recipient/user.
Business-initiated conversations:
Business-initiated conversations are initiated by the business, typically by sending a message to a user outside the 24-hour customer service window.
Messages that initiate a business-initiated conversation require the use of message templates.
The pricing for business-initiated conversations may vary by market (country or region) and is based on the country code of the recipient/user.
Free tier conversations:
The first 1,000 conversations each month for your WhatsApp Business account are free of charge.
Free tier conversations can be either business-initiated or user-initiated.
If you don’t use all 1,000 free conversations in a month, the remaining conversations do not carry over to the following month.
Free entry-point conversations:
Conversations that are initiated when users message businesses using call-to-action buttons on ads that click to WhatsApp or Facebook Pages are not charged.
Free entry-point conversations can only be user-initiated.
The initial conversation that starts from these entry points is free of charge for three days.
Subsequent conversations with the same user from the entry point will be charged according to the pricing model.

It’s important to note that while the conversation-based pricing model applies to the conversations themselves, standard pricing may still apply for ads that click to WhatsApp. The initial conversation that starts from the ad is free, but the ad itself is not free.

For specific pricing details and examples of conversational flows, you can refer to the conversation-based pricing rate card provided by WhatsApp.

8. Verify your business in Business settings

Before you begin:

Make sure your business needs to be verified. The verification process is typically required for accessing specific Meta technologies or developer features.
If you don’t see the “Start verification” button in the Security Centre of your Business settings, confirm whether the product or feature you’re trying to access requires business verification. Check any notification you received for instructions on how to get started.
Ensure you have full control of your business account.
Provide accurate information during the verification process. Providing false or misleading information, attempting to claim and verify a business without authorization, or trying to circumvent the verification review systems may result in your business being prevented from verification or additional actions taken on the account.

2. How to verify your business:

Go to the Security Centre in your Business settings. You may also receive a verification notification in other Meta products like Ads Manager or Commerce Manager.
Provide your business details, including your legal business name, business address, phone number, and website. Ensure that the details you submit exactly match your legal business entity.
Confirm your business details. If necessary, provide supporting documents that are accepted for verification. Refer to the official guidelines for the list of official documents you can provide.
Choose a contact method to confirm your connection:
Email address: Meta will send a confirmation code to your business’s email address. The domain of your email address must match your website’s domain. Ensure you have access to the email inbox you provide.
Phone: Meta will call your business phone number with a confirmation code. Upload a document, such as a utility bill, to confirm your business phone number. Ensure you have access to the registered phone.
Text message: Meta will send a confirmation code via SMS to your business’s phone number. Upload a document, such as a utility bill, to confirm your business phone number. Ensure you have access to the registered phone.
Once you’ve provided the necessary information and completed the verification steps, click “Done”.

Verification decision:

The time to receive a decision on your verification can range from as little as 10 minutes up to 14 working days.
You will receive a notification when the review is complete.
If your business is verified, no further action is required.

10.Get Started

Set up Developer Assets and Platform Access:

a. Register as a Meta Developer.
b. Enable two-factor authentication for your account.
c. Create a Meta App: Go to developers.facebook.com > My Apps > Create App. Choose the Business type and follow the on-screen prompts. If asked to select a Use Case, choose “Other” and select “Business”.
d. From the App Dashboard, select the app you want to connect to WhatsApp. Scroll down to the “WhatsApp” product and click “Set up”.
e. Choose an existing Business Manager or have one created automatically for you.
f. This will associate your app with the selected Business Manager and generate a WhatsApp Business Account along with a test business phone number.
Send a Test Message: a. In the WhatsApp > API Setup panel:
Select your test phone number in the “From” field.
Enter the recipient phone number you want to message in the “To” field. Verify your access to the number as prompted.
The code sample on the page will show an API call that sends a pre-approved message template to the recipient number. b. Click “Send message” or copy the code sample to execute it using tools like Terminal or Postman. c. You have now sent a test message.

Configure a Webhook:

a. Set up a Webhooks endpoint for your app. You can create a custom URL or use services like Glitch.
b. Go to your App Dashboard > WhatsApp > Configuration > Edit.
c. Provide the Callback URL where Meta will send events.
d. Set a Verify Token for your webhook endpoint.
e. Click “Verify and Save”.
f. In the Configuration panel, click “Manage” and subscribe to the desired webhook fields, especially “messages”.
Receive a Test Message:
Send a message to the test number you used in Step 2.
You should receive a Webhooks notification with the content of your message.

Next Steps:

Phone Number: When you’re ready for production use, use your own phone number to send messages. Consider migrating an existing number to the business platform or choose a new number following the platform’s rules.
Opt-In: Obtain user opt-in before opening marketing, utility, and authentication conversations with customers.
Pricing & Payment Methods: Businesses are charged per conversation, with the first 1,000 conversations per month being free. To send more than 1,000 conversations, add a credit card as a payment method in your WhatsApp Business account.

Please note that the steps provided here are a summary, and you should refer to Meta’s official documentation for more detailed instructions and the most up-to-date information.

10.Add a Phone Number

Navigate to the Meta App that is set-up for WhatsApp by going to developers.facebook.com > My Apps > Select your App.

If your phone number is currently registered with WhatsApp Messenger or the WhatsApp Business App, you need to first delete it. See Migrate an Existing WhatsApp Number to a Business Account.

Use left menu to navigate to the WhatsApp > API Setup panel.
On the right pane select Add phone number button under Step 5: Add a phone number.
Use the display name guidelines to enter a display name for your phone number. This is the name that will show for your business phone number once approved.
Select your Timezone. This will be used for WhatsApp Billing and analytics.
Select a Category for your business and enter a Business description.
Select Next to begin the phone number verification process.
Select your country code from the drop down and enter the phone number you would like to register.
Select how you would like to receive your verification code, either by Text Message or Phone and click Next to continue. You will need access to the phone number before selecting Next to receive the verification code.
Enter the verification code once received and click Next to continue.
The phone number will appear in the From drop down menu of the Send and receive messages section of the panel.
Select the newly added phone number to begin sending messages.

https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/migrate-existing-whatsapp-number-to-a-business-account

Verify basic information in settings

Meta App Review

When submitting your app for App Review, there are some important things to keep in mind:

Accessibility for Testing: Ensure that the App Review team can access and test your app. If they are unable to access your app, the entire submission will be rejected. Make sure your app is in Development mode or is of the Business app type.
Screen Recordings: As part of the submission process, you’ll need to upload screen recordings that demonstrate how to use your app to test each permission and feature you’re requesting. These screen recordings should show the actions that require the specific permissions and features. Any requested permission or feature without a corresponding screen recording may not be approved.
App Review Panel: The App Review process starts in the App Dashboard’s App Review panel. You can find the panel under “App Review > Permissions and Features” in the left-hand menu. Follow the “Submitting For Review” guide in the App Dashboard after completing app development.
Testing Permissions and Features: The App Review team will attempt to test your app by following the steps you performed in your screen recordings. If they can’t test a specific permission or feature you’ve requested, you may not be approved for that permission or feature.
Developer Notifications: After submitting an App Review request, you’ll receive periodic developer notifications regarding the status of your submission. These notifications will appear in the Alert > Inbox panel. You can also check your submission status in the App Review > Requests panel.
Processing Time: Typically, the App Review process takes less than a week, often 2–3 days. However, it may take longer during peak periods.

App Review for Live Apps:

If your app is already in Live mode and you want to introduce new functionality that requires App Review or change how your app uses Facebook data, create a test app from your live app for new development.
Conduct all new development and testing using the test app.
Capture screen recordings demonstrating how your test app uses the new permissions and features.
Switch back to your parent live app in the App Dashboard and start a new App Review submission using the recorded screen captures.
Provide clear instructions on how the test app can be tested, including any necessary credentials or network access.
Submit the new App Review submission.

Re-Review:

Any changes made to your app’s basic or advanced settings after submitting for App Review may require re-review before taking effect.

It’s important to follow the guidelines and instructions provided by Meta during the App Review process to ensure a smooth and successful review.

https://developers.facebook.com/docs/app-review/introduction