Skip to main content

Maintenance & Troubleshooting

This section provides guidance on common maintenance tasks and how to troubleshoot potential issues with your WhatsApp Agent deployment.

Updating the Application​

To update your application to the latest version, follow these steps:

  1. Pull the Latest Docker Image:

    docker compose pull

    This command downloads the newest versions of the webhook and worker images as specified in your deploy/compose.yml file.

  2. Recreate the Services:

    # Ensure you are in the deploy/ directory
    docker compose up -d

    Docker Compose is smart enough to detect that the image has changed. It will stop the old containers and start new ones using the updated image. Your data in PostgreSQL and Redis will be preserved.

  3. Automatic Migrations: The entrypoint script will automatically run any new database migrations required by the updated version, so your database schema will be updated seamlessly.

Common Troubleshooting Steps​

Most issues can be diagnosed by checking the application logs.

1. Check the Logs​

The first step in troubleshooting is always to look at the logs from the webhook and worker containers.

  • Webhook Service Logs (for API errors, webhook verification issues):

    docker compose logs -f webhook

  • Worker Service Logs (for CRM or S3 integration errors):

    docker compose logs -f worker

Look for any lines containing ERROR or CRITICAL.

2. Webhook Verification Fails​

  • Symptom: When you try to verify your Callback URL in the Meta Developer Dashboard, it fails.
  • Cause: The WEBHOOK_VERIFY_TOKEN in your deploy/deploy.env file does not exactly match the token you entered in the Meta dashboard.
  • Solution: Double-check that the tokens are identical, with no extra spaces or characters. Restart the webhook service if you change the .env file (docker compose up -d --force-recreate webhook).

3. Flow Data Decryption Fails​

  • Symptom: The logs show errors related to Decryption failed or Invalid padding when a user submits a flow.
  • Cause: The WHATSAPP_FLOW_PRIVATE_KEY_B64 in your .env file is incorrect or corrupted.
  • Solution: Ensure you have correctly copied and pasted the base64-encoded private key generated by the setup_whatsapp_encryption.py script.

4. CRM Notifications Fail​

  • Symptom: The worker logs show 401 Unauthorized, 404 Not Found, or other HTTP errors when trying to send data to the CRM.
  • Cause: This can have several causes:
    • Incorrect CRM_API_URL, CRM_API_KEY, or CRM_API_SECRET in your .env file.
    • The doctype specified in your crm_mappings/*.yaml file does not exist in your Frappe/ERPNext instance.
    • A field name in the field_map of your mapping file does not exist in the target CRM DocType.
  • Solution: Carefully verify all CRM-related credentials and mapping file configurations against your CRM setup.

5. Network Issues​

  • Symptom: The logs show Connection refused or Timeout errors when trying to connect to Exotel, your CRM, or S3.
  • Cause: A firewall or network security group on your server is blocking outbound connections.
  • Solution: Ensure your server's firewall rules allow outbound traffic on port 443 (for HTTPS) to the required external services.