Initial Setup & Configuration

This section guides you through the initial setup process, from cloning the repository to configuring all the necessary environment variables.

1. Clone the Repository

First, clone the project repository to your local machine:

git clone https://gitlab.com/castlecraft/whatsapp_agent.git
cd whatsapp-agent

2. Configure Environment Variables

The application is configured using environment variables defined in a .env file. You will need to create this file in the deploy/ directory.

Create a file named deploy/deploy.env and populate it with the following content. You must replace the placeholder values with your actual credentials and settings.

deploy/deploy.env

# --- Application Settings ---
APP_NAME=whatsapp-agent

# --- PostgreSQL Credentials ---
POSTGRES_USER=your_db_user
POSTGRES_PASSWORD=your_db_password
POSTGRES_DB=whatsapp_agent_db

# --- Webhook Settings ---
WEBHOOK_VERIFY_TOKEN="a-very-strong-and-secret-token"
# Optional: For end-to-end encrypted webhooks. See Encryption Setup section.
WEBHOOK_E2E_PRIVATE_KEY_B64=""

# --- Exotel API Credentials ---
EXOTEL_API_KEY="your-exotel-api-key"
EXOTEL_API_TOKEN="your-exotel-api-token"
EXOTEL_ACCOUNT_SID="your-exotel-account-sid"
EXOTEL_SUBDOMAIN="@api.in.exotel.com"
EXOTEL_FROM_NUMBER="+919876543210"
EXOTEL_STATUS_CALLBACK_URL=""

# --- WhatsApp Flow Decryption ---
# See Encryption Setup section.
WHATSAPP_FLOW_PRIVATE_KEY_B64="your-base64-encoded-private-key-for-flows"

# --- Third-Party CRM Integration ---
CRM_API_URL="https://your-crm.com/api"
CRM_API_KEY="your-crm-api-key"
CRM_API_SECRET="your-crm-api-secret"
CRM_DOCTYP="Lead"

# --- S3-Compatible Storage ---
S3_ENDPOINT_URL="" # e.g., 'https://s3.amazonaws.com'
S3_ACCESS_KEY_ID="your-s3-access-key"
S3_SECRET_ACCESS_KEY="your-s3-secret-key"
S3_BUCKET_NAME="your-bucket-name"
S3_REGION_NAME="ap-south-1"

3. Encryption Setup

The application uses a single private key to decrypt both end-to-end encrypted webhook notifications and data submitted from WhatsApp Flows. You will generate a key pair locally and register the public key with Meta. The provided setup_whatsapp_encryption.py script automates this entire process.

Generating and Configuring Your Key

1. Set Your API Token: The setup script needs a temporary System User access token with whatsapp_business_management permission. Export it in your terminal:

   export WHATSAPP_API_TOKEN='your-temporary-api-token'

2. Run the Setup Script: Execute the script, replacing YOUR_PHONE_NUMBER_ID with the ID from your Meta App Dashboard.

   python scripts/setup_whatsapp_encryption.py YOUR_PHONE_NUMBER_ID

   This script generates a private key (whatsapp_private_key.pem), derives the public key, and registers the public key with Meta's API for your phone number.

3. Encode and Configure the Key: The content of the generated whatsapp_private_key.pem file must be base64 encoded.

   # For Linux/macOS
   cat whatsapp_private_key.pem | base64 -w 0

   Copy the resulting base64 string. You must paste this same string as the value for both of the following variables in your deploy/deploy.env file:

   • WEBHOOK_E2E_PRIVATE_KEY_B64 (for encrypted webhooks)
   • WHATSAPP_FLOW_PRIVATE_KEY_B64 (for encrypted Flow data)