Skip to main content

WhatsApp Bot Integration

Deploy an Ask-powered WhatsApp chatbot that receives messages via WhatsApp Cloud API, processes them through your Ask agent, and maintains conversation context automatically.

Features​

  • 🔄 Automatic conversation management - Sessions reset after inactivity or /new command
  • 📱 WhatsApp Cloud API - Built on Meta's official API using pywa
  • 🗄️ PostgreSQL persistence - Tracks conversation state per user
  • 🐳 Docker-ready - One-command deployment with Docker Compose

Architecture​

Prerequisites​

Before you begin, ensure you have:

  • Ask Agent: Provisioned agent with API key from Ask Platform
  • WhatsApp Business Account: Set up via Meta Business Suite
    • WhatsApp phone number ID
    • Permanent access token
    • App ID and App Secret
  • Docker & Docker Compose: Install Docker Desktop
  • Public Webhook URL: Use ngrok, cloud hosting, or reverse proxy

Quick Start​

1. Clone the Repository​

git clone https://github.com/ai71-Ask/ask_whatsapp_bot
cd ask_whatsapp_bot

2. Configure Environment Variables​

Create a .env file in the project root:

cp env.example .env

Edit .env with your credentials:

bash
# Ask Configuration
AGENT_ID=your_agent_id
ASK_API_KEY=your_api_key
ASK_API_BASE=https://api.ask.dev.ai71services.ai

# WhatsApp Configuration
WHATSAPP_TOKEN=your_whatsapp_permanent_token
WHATSAPP_PHONE_ID=your_phone_number_id
WHATSAPP_APP_ID=your_app_id
WHATSAPP_APP_SECRET=your_app_secret
VERIFY_TOKEN=your_custom_verification_token

# Webhook Configuration
WEBHOOK_URL=https://your-domain.com/webhook

# Application Settings
PORT=8443
SESSION_TIMEOUT=60

# Database (Docker Compose)
DB_PASSWORD=your_secure_password
Security

Always use HTTPS for production webhooks. Meta requires valid SSL certificates for webhook URLs.

Webhook Setup

Your WEBHOOK_URL must be publicly accessible. For local testing, use ngrok:

ngrok http 8443

Then use the ngrok URL (e.g., https://abc123.ngrok.io/webhook) as your WEBHOOK_URL.

3. Deploy with Docker Compose​

Start both the application and PostgreSQL database:

docker compose up --build -d

This command:

  • Builds the FastAPI application
  • Starts PostgreSQL database
  • Runs database migrations automatically
  • Exposes the bot on port 8443

View logs:

# Watch application logs
docker compose logs -f bot

# View all services
docker compose logs -f

Stop services:

docker compose down

# Remove data volumes
docker compose down -v

Building Custom Docker Image​

If you need to build and deploy a custom Docker image:

Build Image​

docker build -t ask-whatsapp-bot:latest .

Environment Variables Reference​

Required Variables​

VariableDescriptionExample
AGENT_IDYour Ask agent identifieragent_abc123
ASK_API_KEYAsk API authentication keyask_key_xyz789
WHATSAPP_TOKENWhatsApp permanent access tokenEAABsbCS...
WHATSAPP_PHONE_IDWhatsApp Business phone number ID123456789012345
WHATSAPP_APP_IDMeta app identifier987654321
WHATSAPP_APP_SECRETMeta app secret for HMAC validationabc123def456
VERIFY_TOKENCustom token for webhook verificationmy_secret_token
WEBHOOK_URLPublic webhook endpointhttps://bot.example.com/webhook

Optional Variables​

VariableDescriptionDefault
ASK_API_BASEAsk API base URLhttps://api.ask.dev.ai71services.ai
PORTApplication port8443
SESSION_TIMEOUTConversation reset timeout (minutes)60
DB_PASSWORDPostgreSQL password (Docker Compose)changeme

Testing the Integration​

1. Send Test Message​

  1. Open WhatsApp on your phone
  2. Send a message to your WhatsApp Business number
  3. The bot should respond with output from your Ask agent

2. Test Session Reset​

Send /new to start a fresh conversation with no prior context.

Conversation Management​

The bot automatically manages conversation sessions:

  • Session ID: Unique per WhatsApp user (phone number)
  • Context: Maintained across messages within timeout window
  • Reset Triggers:
    • /new command from user
    • Inactivity exceeding SESSION_TIMEOUT minutes (default: 60)
Data Storage

Only conversation_id, phone_number, and last_interaction timestamp are stored. Message content and history are managed by Ask, not persisted in the bot's database.

User Flow​