https://github.com/hyperjumptech/whatsapp-chatbot-connector
https://github.com/hyperjumptech/whatsapp-chatbot-connector
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/hyperjumptech/whatsapp-chatbot-connector
- Owner: hyperjumptech
- Created: 2024-06-05T08:09:19.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-09-30T04:13:53.000Z (8 months ago)
- Last Synced: 2025-09-30T04:20:37.267Z (8 months ago)
- Language: TypeScript
- Size: 656 KB
- Stars: 32
- Watchers: 5
- Forks: 18
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://github.com/hyperjumptech/whatsapp-chatbot-connector/actions/workflows/code-quality.yml)
# WhatsApp Chatbot Connector
This project is a WhatsApp Chatbot Connector backend built using Express.js. It is designed to integrate with the WhatsApp Business API and supports various AI platforms such as Dify and Rasa.
Here is the diagram to understand the flow:
## Features
- Webhook endpoint to receive messages from WhatsApp
- Integration with Dify and Rasa for natural language processing and response generation
- Displaying interactive whatsapp message like [List](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/interactive-list-messages), [Reply Buttons](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/interactive-reply-buttons-messages), and [Flow](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/interactive-flow-messages)
## Prerequisites
Ensure you have the following installed:
Node.js (v18.x or later)
npm (v10.x or later)
## Getting Started
### Quick Start
1. Clone the Repository
```bash
git clone https://github.com/hyperjumptech/whatsapp-chatbot-connector.git
cd whatsapp-chatbot-connector
```
2. Install Dependencies
```bash
npm install
```
3. Set Environment Variables
```bash
cp .env.example .env
```
then fill in the appropriate values in the .env file.
Choose to connect to which platform by filling the `CONNECTION_PLATFORM` variable in the .env file.
```
CONNECTION_PLATFORM=dify
```
or
```
CONNECTION_PLATFORM=rasa
```
4. Running the Server
```bash
npm run dev
```
5. Set callback URL in WhatsApp Business API
In the WhatsApp Business API, go to the **Configuration** menu and fine the **Callback URL**. Detail on the [picture below](#whatsapp-business-api-configuration), poin **number 7**
> Note that the url must use https
So if you are running on local, you can use [ngrok](https://ngrok.com/docs/getting-started/) to get a public URL with https for your local server.
6. Send text message to the WhatsApp Business API
Now just use your WhatsApp app to send a text message to the WhatsApp Business number and you will see the response from the chatbot connected.
### Optional Development Dependencies
To start up the optional development dependecies like Redis, you can use Docker .
Go to folder `.dev` then
```
docker compose up -d
```
## Environment Variables
| Variable Name | Description | Example |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| NODE_ENV | Environment variable to set the node environment. | development |
| WEBHOOK_VERIFY_TOKEN | Webhook verification token. The value should be the same as the one you set in the WhatsApp Business API. Detail in picture below, poin **number 3** |
| WEBHOOK_APP_SECRET | WhatsApp App Secret for webhook signature verification. Optional but recommended for security. Get this from your WhatsApp Business API app settings. | your_app_secret_here |
| WEBHOOK_HEADER_VALIDATION | To determine do we need to do header validation. | false |
| GRAPH_API_TOKEN | Graph API token. The value should be the same as the one you set in the WhatsApp Business API. Detail in picture below, poin **number 5** | abacdefghijk |
| BUSINESS_PHONE_NUMBER_ID | Business phone number ID. The value should be obtained from WhatsApp Business API. Detail in picture below, poin **number 6** | 12345678912323 |
| DIFY_BASE_URL | Dify base URL. | https://api.dify.ai/v1 |
| DIFY_API_KEY | Dify API key. | app-Jdasdsdsd98n98787y |
| RASA_BASE_URL | Rasa base URL. | http://localhost:5005/webhooks/rest/webhook |
| CONNECTION_PLATFORM | Platform to connect to. value should be `dify` or `rasa` | dify |
| SESSION_DATABASE | Database to store session. value should be `in-memory` or `redis` | in-memory |
| REDIS_URL | Redis URL. Required if `SESSION_DATABASE` is set to `redis` | redis://localhost:6379 |
## WhatsApp Business API Configuration
## Interactive Message Configuration
### Flow
To create a Flow, you must setup many things like in the [docs](https://developers.facebook.com/docs/whatsapp/flows). I will mention over-simplified version for easy starting point:
1. Create a Flow
2. Setup server endpoint
3. Setup Dify to trigger sending HTTP Request with this [JSON format](https://developers.facebook.com/docs/whatsapp/flows/gettingstarted/sendingaflow). Here is the example request body:
```json
{
"recipient_type": "individual",
"messaging_product": "whatsapp",
"to": "{{#sys.user_id#}}",
"type": "interactive",
"interactive": {
"type": "flow",
"header": {
"type": "text",
"text": "Event Registration"
},
"body": {
"text": "Click button below to authenticate yourself"
},
"action": {
"name": "flow",
"parameters": {
"mode": "draft", // delete this field for production use (when your flow is published)
"flow_message_version": "3",
"flow_token": "auth_flow-{{#sys.user_id#}}.",
"flow_id": "1234567812345678",
"flow_cta": "Start",
"flow_action": "data_exchange"
}
}
}
}
```
4. It will send CTA button to trigger the Flow
5. Fill in, complete, and submit the form
6. Sent status will be displayed
## Deployment
### Vercel
You can deploy this app to any server that runs Node.js. The easiest one is to use Vercel. Just clone this repo and connect it from Vercel Dashboard then you are good to go.
### Docker
Use `Dockerfile` and `docker-compose.yml` file in the root folder.
1. Build docker image
```
docker build -t wa-connector
```
2. Run the docker
```
docker compose up -d
```
## License
This project is licensed under the MIT License. See the LICENSE file for details.