WhatsApp Automation is a Spring Boot backend for WhatsApp Business messaging workflows. It receives webhook events from Meta, runs bot-driven conversation logic, and persists booking/state data in PostgreSQL.

About The Project

This project provides automation features around WhatsApp messaging:

Webhook verification and message handling (/webhook)
Chatbot conversation flow
PostgreSQL persistence for appointments, service bookings, test bookings, and user state

The application is a Java 21 Maven service built with Spring Boot.

Tech Stack

Spring Boot 3.3.2
Java 21
Spring Web
Spring Data JPA
PostgreSQL
ngrok (for local webhook tunneling to Meta)

Requirements

Tool	Purpose
Java 21	Runtime for the Spring Boot app
Maven 3.9+	Build and run the project
PostgreSQL	Application database
ngrok	Expose local backend to the public internet so Meta can call your webhook
Meta / WhatsApp Business API access	Access token, webhook configuration, and test messaging

How to Run the Backend (Full Setup)

Follow these steps in order.

1. Clone the repository

git clone <repository-url>
cd "WhatsApp Automation"

Replace <repository-url> with the actual Git remote URL for this project.

2. Install ngrok

ngrok creates a public HTTPS URL that tunnels to your local Spring Boot server so Meta can deliver WhatsApp webhooks.

Go to https://ngrok.com
Sign up or sign in
Install ngrok for your OS (macOS example with Homebrew):

brew install ngrok

Or download the binary from the ngrok dashboard and follow their install instructions.

3. Authenticate ngrok with your access token

After signing in to ngrok, copy your authtoken from the ngrok dashboard, then run:

ngrok config add-authtoken <YOUR_NGROK_AUTHTOKEN>

Without this step, ngrok will not start a usable tunnel.

4. Log in to the WhatsApp Business / Meta developer dashboard

Open the WhatsApp Business API / Meta for Developers dashboard
Log in with the account that has access to this app
Use the project’s WhatsApp / Meta credentials (app ID, business ID, phone number ID, etc.) as configured for your team

Relevant app links used by this project:

API testing / access token:
Generate WhatsApp access token
Webhooks configuration:
Configure webhooks

5. Generate a WhatsApp access token and configure the app

Open the API testing page:
https://developers.facebook.com/apps/1054675710401577/use_cases/customize/api-testing-v2/?product_route=whatsapp-business&business_id=1051413880774512&use_case_enum=WHATSAPP_BUSINESS_MESSAGING&selected_tab=api-testing-v2
Generate a new Access Token
Open the project config file:

src/main/resources/application.properties

Paste the token into the access-token property:

whatsapp.access-token=<YOUR_WHATSAPP_ACCESS_TOKEN>

Note: Temporary tokens from Meta expire. If outbound WhatsApp API calls start failing with auth errors, generate a new token and update this property.

6. Create the PostgreSQL database and set credentials

Ensure PostgreSQL is installed and running locally
Create the database used by this project (default name: rmc_bot):

createdb rmc_bot

Or via psql:

CREATE DATABASE rmc_bot;

Update database settings in src/main/resources/application.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/rmc_bot
spring.datasource.username=<YOUR_POSTGRES_USERNAME>
spring.datasource.password=<YOUR_POSTGRES_PASSWORD>

Default values currently in the file (change these for your machine):

Property	Default / example
`spring.datasource.url`	`jdbc:postgresql://localhost:5432/rmc_bot`
`spring.datasource.username`	`postgres`
`spring.datasource.password`	(your local password)

The app uses:

spring.jpa.hibernate.ddl-auto=update

so tables are created/updated automatically on startup.

7. Start the Spring Boot backend

The server listens on port 8085 (server.port=8085).

From the project root:

mvn spring-boot:run

Confirm the app started successfully (no datasource or port-binding errors). Leave this process running.

You can also run tests with:

mvn test

8. Start ngrok and point it at the backend

Important: Start the Spring Boot backend before configuring Meta webhooks, and keep both the backend and ngrok running while testing.

In a new terminal:

ngrok http 8085

ngrok will print a public HTTPS URL, for example:

https://abcd-1234.ngrok-free.app

Copy that base URL (the https://... forwarding address).

Free ngrok URLs change every time you restart ngrok. When the URL changes, you must update the Callback URL in Meta again.

9. Configure the Meta webhook

Open the webhooks page:
https://developers.facebook.com/apps/1054675710401577/use_cases/customize/webhooks/?product_route=webhooks&business_id=1051413880774512&use_case_enum=WHATSAPP_BUSINESS_MESSAGING&selected_tab=webhooks
Set Callback URL to:

https://<YOUR_NGROK_HOST>/webhook

Example:

https://abcd-1234.ngrok-free.app/webhook

Set Verify Token to exactly:

my_whatsapp_verify_token_123

This must match whatsapp.verify-token in application.properties:

whatsapp.verify-token=my_whatsapp_verify_token_123

Click Verify and Save (or equivalent). Meta will send a GET request to /webhook with hub.mode, hub.verify_token, and hub.challenge. The backend validates the token and returns the challenge.
Subscribe to the webhook fields you need (typically messages for inbound WhatsApp traffic).

Configuration reference

All runtime secrets and connection settings live in:

src/main/resources/application.properties

Property	Description
`server.port`	Backend HTTP port (default `8085`)
`whatsapp.access-token`	Meta WhatsApp Cloud API access token
`whatsapp.verify-token`	Token Meta uses to verify your webhook (`my_whatsapp_verify_token_123`)
`spring.datasource.url`	JDBC URL for PostgreSQL
`spring.datasource.username`	PostgreSQL username
`spring.datasource.password`	PostgreSQL password
`spring.jpa.hibernate.ddl-auto`	Schema mode (`update`)
`spring.jpa.properties.hibernate.dialect`	PostgreSQL dialect
`spring.jpa.show-sql`	Log SQL statements

Webhook endpoint exposed by the app:

Method	Path	Purpose
`GET`	`/webhook`	Meta webhook verification
`POST`	`/webhook`	Inbound WhatsApp events / messages

Quick checklist

Use this when bringing the stack up on a new machine:

Clone the repo
Install and authenticate ngrok
Log in to Meta / WhatsApp Business dashboard
Generate access token → set whatsapp.access-token
Create PostgreSQL DB → set datasource username/password
mvn spring-boot:run (port 8085)
ngrok http 8085
Meta Callback URL = https://<ngrok-host>/webhook
Verify token = my_whatsapp_verify_token_123
Verify webhook + subscribe to message events

Troubleshooting

Problem	What to check
Webhook verification fails	Verify token must be exactly `my_whatsapp_verify_token_123`. Backend must be running. Callback URL must end with `/webhook`.
Meta cannot reach the server	ngrok must be running (`ngrok http 8085`). Use the current ngrok HTTPS URL, not an old one.
Database connection errors	PostgreSQL is running; database `rmc_bot` exists; username/password in `application.properties` are correct.
Cannot send WhatsApp messages	Access token may have expired — generate a new one and update `whatsapp.access-token`.
Port already in use	Something else is bound to `8085`, or change `server.port` and point ngrok at the new port.
Not receiving messages on webhook	Your WhatsApp Business Account (WABA) might not be subscribed to your developer App. Link them via API: `curl -X POST "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" -H "Authorization: Bearer <your_access_token>"`

Project structure (high level)

src/main/java/com/example/whatsappautomation/
  WhatsAppAutomationApplication.java
  controller/WhatsAppWebhookController.java
  service/ChatbotService.java
  entity/          # Appointment, ServiceBooking, TestBooking, UserState
  repository/      # Spring Data JPA repositories
src/main/resources/
  application.properties

License

Internal / project use unless otherwise specified.

README.md Unescape Escape

WhatsApp Automation