Skip to content

Commit 2a01553

Browse files
committed
Update WhatsApp Chat Agent README and tools documentation
- Revised README to reflect the new AI agent functionality and improved setup instructions. - Added detailed steps for obtaining WhatsApp credentials and configuring the environment. - Enhanced error handling and troubleshooting sections for better user guidance. - Updated `whatsapp_tools.py` to include links for easier navigation and clarified environment variable setup.
1 parent 237245f commit 2a01553

File tree

2 files changed

+132
-73
lines changed

2 files changed

+132
-73
lines changed
Original file line numberDiff line numberDiff line change
@@ -1,96 +1,158 @@
1-
# WhatsApp Chat Agent with Stock Market Insights
1+
# WhatsApp Business API Integration with AI Agent
22

3-
This is a WhatsApp chatbot that provides stock market insights and financial advice using the WhatsApp Business API. The bot is built using FastAPI and can be run locally using ngrok for development and testing.
3+
This is a WhatsApp chatbot that automatically responds to incoming messages using an AI agent. The bot runs on FastAPI and uses the WhatsApp Business API to handle message interactions.
4+
5+
## Features
6+
7+
- Automatically responds to any incoming WhatsApp messages
8+
- Uses AI to generate contextual responses
9+
- Handles webhook verification for WhatsApp Business API
10+
- Supports secure HTTPS communication
11+
- Logs all interactions for monitoring
412

513
## Prerequisites
614

715
- Python 3.7+
8-
- ngrok account (free tier works fine)
16+
- ngrok account (for development/testing)
917
- WhatsApp Business API access
1018
- Meta Developer account
1119
- OpenAI API key
1220

13-
## Setup Instructions
21+
## Getting WhatsApp Credentials
1422

15-
1. **Install Dependencies**
23+
1. **Create Meta Developer Account**:
1624

17-
```bash
18-
pip install -r requirements.txt
19-
```
25+
- Go to [Meta Developer Portal](https://developers.facebook.com/) and create an account
26+
- Create a new app at [Meta Apps Dashboard](https://developers.facebook.com/apps/)
27+
- Enable WhatsApp integration for your app
2028

21-
2. **Set up ngrok (for development testing only)**
29+
2. **Set Up WhatsApp Business API**:
2230

23-
- Download and install ngrok from https://ngrok.com/download
24-
- Sign up for a free account and get your auth-token
25-
- Authenticate ngrok with your token:
26-
```bash
27-
ngrok config add-authtoken YOUR_AUTH_TOKEN
28-
```
31+
- Go to your app's WhatsApp Setup page
32+
- Find your WhatsApp Business Account ID in Business Settings
33+
- Get your Phone Number ID from the WhatsApp > Getting Started page
34+
- Generate a permanent access token in App Dashboard > WhatsApp > API Setup
2935

30-
3. **Create a Meta Developer Account**
36+
3. **Test Environment Setup**:
37+
- Note: Initially, you can only send messages to numbers registered in your test environment
38+
- For production, you'll need to submit your app for review
3139

32-
- Go to https://developers.facebook.com/
33-
- Create a new app
34-
- Set up WhatsApp in your app
35-
- Get your WhatsApp Business Account ID and Phone Number ID
40+
## Environment Setup
3641

37-
4. **Environment Variables**
38-
Create a `.envrc` file in the project root with the following variables:
42+
Create a `.envrc` file in the project root with these variables:
3943

4044
```bash
41-
export WHATSAPP_ACCESS_TOKEN=your_whatsapp_access_token
42-
export WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
43-
export WHATSAPP_RECIPIENT_WAID=phone_number_with_country_code # e.g. +1234567890
44-
export WHATSAPP_WEBHOOK_URL=your_webhook_url
45-
export WHATSAPP_VERIFY_TOKEN=your_custom_verify_token # Can be any string you choose
45+
# From Meta Developer Portal
46+
export WHATSAPP_ACCESS_TOKEN=your_whatsapp_access_token # From App Dashboard > WhatsApp > API Setup
47+
export WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id # From WhatsApp > Getting Started
48+
export WHATSAPP_WEBHOOK_URL=your_webhook_url # Your ngrok URL + /webhook
49+
export WHATSAPP_VERIFY_TOKEN=your_verify_token # Any secure string you choose
50+
51+
# For OpenAI integration
4652
export OPENAI_API_KEY=your_openai_api_key
4753
```
4854

55+
## Installation
56+
57+
1. Install dependencies:
58+
59+
```bash
60+
pip install -r requirements.txt
61+
```
62+
63+
2. Set up your environment variables in `.envrc`:
64+
65+
```bash
66+
source .envrc
67+
```
68+
4969
## Running the Application
5070

51-
1. **Start the FastAPI server**
71+
You need to run two components:
72+
73+
1. **The ngrok tunnel** (in one terminal):
5274

5375
```bash
54-
python app.py
76+
ngrok http --domain=your-domain.ngrok-free.app 8000
5577
```
5678

57-
2. **Start ngrok**
58-
In a new terminal window:
79+
2. **The FastAPI server** (in another terminal):
5980

6081
```bash
61-
ngrok http 8000
82+
python app.py
6283
```
6384

64-
3. **Configure Webhook**
65-
- Copy the HTTPS URL provided by ngrok (e.g., https://xxxx-xx-xx-xxx-xx.ngrok.io)
66-
- Go to your Meta Developer Portal
67-
- Set up Webhooks for your WhatsApp Business Account
68-
- Use the ngrok URL + "/webhook" as your Callback URL
69-
- Use your WHATSAPP_VERIFY_TOKEN as the Verify Token
70-
- Subscribe to the `messages` webhook
71-
72-
## Testing the Bot
73-
74-
1. Send a message to your WhatsApp Business number
75-
2. The bot should respond with stock market insights based on your query
76-
3. You can ask questions about:
77-
- Stock prices
78-
- Company information
79-
- Analyst recommendations
80-
- Stock fundamentals
81-
- Historical prices
82-
- Company news
85+
## WhatsApp Business Setup
86+
87+
1. Go to Meta Developer Portal
88+
2. Set up your WhatsApp Business account
89+
3. Configure the webhook:
90+
- URL: Your ngrok URL + "/webhook" (e.g., https://your-domain.ngrok-free.app/webhook)
91+
- Verify Token: Same as WHATSAPP_VERIFY_TOKEN in your .envrc
92+
- Subscribe to the 'messages' webhook field
93+
94+
## How It Works
95+
96+
1. When someone sends a message to your WhatsApp Business number:
97+
98+
- The message is received via webhook
99+
- The AI agent processes the message
100+
- A response is automatically generated and sent back
101+
102+
2. The agent can:
103+
- Process incoming text messages
104+
- Generate contextual responses
105+
- Log all interactions
106+
107+
## Monitoring
108+
109+
The application logs important events:
110+
111+
- Server start/stop
112+
- Incoming messages
113+
- Response generation
114+
- Message delivery status
115+
116+
Check the console output for logs.
117+
118+
## Error Handling
119+
120+
The application includes error handling for:
121+
122+
- Invalid webhook verification
123+
- Message processing errors
124+
- API communication issues
125+
126+
## Security Notes
127+
128+
- Keep your environment variables secure
129+
- Don't commit `.envrc` to version control
130+
- Use HTTPS for all communications
131+
- Regularly rotate your access tokens
83132

84133
## Troubleshooting
85134

86-
- Make sure all environment variables are properly set
87-
- Check the FastAPI logs for any errors
88-
- Verify that ngrok is running and the webhook URL is correctly configured
89-
- Ensure your WhatsApp Business API is properly set up and the phone number is verified
135+
Common issues:
136+
137+
1. Webhook verification failing:
138+
139+
- Check your VERIFY_TOKEN matches
140+
- Ensure ngrok is running
141+
- Verify webhook URL is correct
142+
143+
2. Messages not being received:
144+
145+
- Check webhook subscription status
146+
- Verify WhatsApp Business API access
147+
148+
3. No responses being sent:
149+
- Verify OpenAI API key
150+
- Check WhatsApp access token
151+
152+
## Support
90153

91-
## Important Notes
154+
For issues and questions:
92155

93-
- The ngrok URL changes every time you restart ngrok, You can also use a static ngrok URL by running `ngrok http 8000 --domain=your-custom-domain.com`, you can get a custom domain from [here](https://dashboard.ngrok.com/domains)
94-
- You'll need to update the Webhook URL in the Meta Developer Portal whenever the ngrok URL changes
95-
- Keep your WHATSAPP_ACCESS_TOKEN and other credentials secure
96-
- The bot stores conversation history in a SQLite database in the `tmp` directory
156+
1. Check the logs for error messages
157+
2. Review Meta's WhatsApp Business API documentation
158+
3. Verify your API credentials and tokens

cookbook/tools/whatsapp_tools.py

+10-13
Original file line numberDiff line numberDiff line change
@@ -6,31 +6,28 @@
66
you'll need to complete these setup steps:
77
88
1. Create Meta Developer Account
9-
- Go to Meta Developer Portal (https://developers.facebook.com/) and create a new account
10-
- Create a new app at Meta Apps Dashboard (https://developers.facebook.com/apps/)
11-
- Enable WhatsApp integration for your app (https://developers.facebook.com/docs/whatsapp/cloud-api/get-started)
9+
- Go to [Meta Developer Portal](https://developers.facebook.com/) and create a new account
10+
- Create a new app at [Meta Apps Dashboard](https://developers.facebook.com/apps/)
11+
- Enable WhatsApp integration for your app [here](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started)
1212
1313
2. Set Up WhatsApp Business API
14-
- Get your WhatsApp Business Account ID from Business Settings (https://business.facebook.com/settings/)
15-
- Generate a permanent access token in System Users (https://business.facebook.com/settings/system-users)
16-
- Set up a test phone number (https://developers.facebook.com/docs/whatsapp/cloud-api/get-started#testing-your-app)
17-
- Create a message template in Meta Business Manager (https://business.facebook.com/wa/manage/message-templates/)
14+
You can get your WhatsApp Business Account ID from [Business Settings](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started)
1815
1916
3. Configure Environment
2017
- Set these environment variables:
21-
WHATSAPP_ACCESS_TOKEN=your_access_token # Permanent access token from System Users
22-
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id # Your WhatsApp test phone number ID
18+
WHATSAPP_ACCESS_TOKEN=your_access_token # Access Token
19+
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id # Phone Number ID
20+
WHATSAPP_RECIPIENT_WAID=your_recipient_waid # Recipient WhatsApp ID (e.g. 1234567890)
21+
WHATSAPP_VERSION=your_whatsapp_version # WhatsApp API Version (e.g. v22.0)
2322
2423
Important Notes:
25-
- WhatsApp has a 24-hour messaging window policy
26-
- You can only send free-form messages to users who have messaged you in the last 24 hours
2724
- For first-time outreach, you must use pre-approved message templates
28-
(https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates)
25+
[here](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates)
2926
- Test messages can only be sent to numbers that are registered in your test environment
3027
3128
The example below shows how to send a template message using Agno's WhatsApp tools.
3229
For more complex use cases, check out the WhatsApp Cloud API documentation:
33-
https://developers.facebook.com/docs/whatsapp/cloud-api/overview
30+
[here](https://developers.facebook.com/docs/whatsapp/cloud-api/overview)
3431
"""
3532

3633
from agno.agent import Agent

0 commit comments

Comments
 (0)