RMC chatbot version 1 implemented
This commit is contained in:
310
README.md
Normal file
310
README.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# WhatsApp Automation
|
||||
|
||||
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
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
1. Go to [https://ngrok.com](https://ngrok.com)
|
||||
2. Sign up or sign in
|
||||
3. Install ngrok for your OS (macOS example with Homebrew):
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
1. Open the [WhatsApp Business API / Meta for Developers](https://developers.facebook.com/) dashboard
|
||||
2. Log in with the account that has access to this app
|
||||
3. 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](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)
|
||||
|
||||
- **Webhooks configuration:**
|
||||
[Configure webhooks](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)
|
||||
|
||||
---
|
||||
|
||||
### 5. Generate a WhatsApp access token and configure the app
|
||||
|
||||
1. 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](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)
|
||||
2. Generate a **new Access Token**
|
||||
3. Open the project config file:
|
||||
|
||||
```text
|
||||
src/main/resources/application.properties
|
||||
```
|
||||
|
||||
4. Paste the token into the access-token property:
|
||||
|
||||
```properties
|
||||
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
|
||||
|
||||
1. Ensure PostgreSQL is installed and running locally
|
||||
2. Create the database used by this project (default name: `rmc_bot`):
|
||||
|
||||
```bash
|
||||
createdb rmc_bot
|
||||
```
|
||||
|
||||
Or via `psql`:
|
||||
|
||||
```sql
|
||||
CREATE DATABASE rmc_bot;
|
||||
```
|
||||
|
||||
3. Update database settings in `src/main/resources/application.properties`:
|
||||
|
||||
```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:
|
||||
|
||||
```properties
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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**:
|
||||
|
||||
```bash
|
||||
ngrok http 8085
|
||||
```
|
||||
|
||||
ngrok will print a public HTTPS URL, for example:
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
1. 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](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)
|
||||
|
||||
2. Set **Callback URL** to:
|
||||
|
||||
```text
|
||||
https://<YOUR_NGROK_HOST>/webhook
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
https://abcd-1234.ngrok-free.app/webhook
|
||||
```
|
||||
|
||||
3. Set **Verify Token** to exactly:
|
||||
|
||||
```text
|
||||
my_whatsapp_verify_token_123
|
||||
```
|
||||
|
||||
This must match `whatsapp.verify-token` in `application.properties`:
|
||||
|
||||
```properties
|
||||
whatsapp.verify-token=my_whatsapp_verify_token_123
|
||||
```
|
||||
|
||||
4. 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.
|
||||
|
||||
5. Subscribe to the webhook fields you need (typically **messages** for inbound WhatsApp traffic).
|
||||
|
||||
---
|
||||
|
||||
## Configuration reference
|
||||
|
||||
All runtime secrets and connection settings live in:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
1. [ ] Clone the repo
|
||||
2. [ ] Install and authenticate ngrok
|
||||
3. [ ] Log in to Meta / WhatsApp Business dashboard
|
||||
4. [ ] Generate access token → set `whatsapp.access-token`
|
||||
5. [ ] Create PostgreSQL DB → set datasource username/password
|
||||
6. [ ] `mvn spring-boot:run` (port **8085**)
|
||||
7. [ ] `ngrok http 8085`
|
||||
8. [ ] Meta Callback URL = `https://<ngrok-host>/webhook`
|
||||
9. [ ] Verify token = `my_whatsapp_verify_token_123`
|
||||
10. [ ] 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)
|
||||
|
||||
```text
|
||||
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.
|
||||
Reference in New Issue
Block a user