Ir para o conteúdo

Ngrok Setup for Development (Optional. Used for Whatsapp local debug)

This project includes optional ngrok configuration for creating secure tunnels to your local development server. This is only needed for testing webhooks (like WhatsApp webhooks) during development.

⚠️ Important: Ngrok is completely optional and only used for development. It is not required in production environments.

Configuration

Environment Variables (Optional)

Only add these variables to your .env file if you want to use ngrok for development:

# Your ngrok API key from https://dashboard.ngrok.com/get-started/your-authtoken
NGROK_API_KEY=your_ngrok_api_key_here

# Custom ngrok domain (can be changed as needed)
DEV_CUSTOM_NGROK_DOMAIN=nanndoj.ngrok.io

API Key

IMPORTANT:

  • Your ngrok API key should be stored in the NGROK_API_KEY environment variable, never committed to the repository for security reasons
  • These variables are completely optional - if not present, the backend will run normally without ngrok
  • Only add them if you need tunneling for webhook testing

Usage

Install Dependencies

pnpm install

Start Ngrok Tunnel Only

pnpm ngrok
# or
pnpm tunnel

Start Backend + Ngrok Together

pnpm dev:tunnel

Output

When the tunnel is established, you'll see:

✅ Ngrok tunnel established!
🌐 Public URL: https://nanndoj.ngrok.io
📚 API Docs: https://nanndoj.ngrok.io/api/docs
💬 WhatsApp Webhook: https://nanndoj.ngrok.io/api/whatsapp/webhook

WhatsApp Webhook Configuration

Use the webhook URL provided by ngrok to configure your WhatsApp webhook:

https://nanndoj.ngrok.io/api/whatsapp/webhook

Troubleshooting

Domain Already in Use

If you get an error that the domain is already in use:

  1. Stop any existing ngrok processes
  2. Try a different domain in your .env file
  3. Or use the ngrok dashboard to manage existing tunnels

Authentication Failed

  • Check that NGROK_API_KEY is set in your .env file
  • Ensure the API key is correct (get it from https://dashboard.ngrok.com/get-started/your-authtoken)

Port Conflicts

  • Make sure the PORT in your .env matches your backend server port
  • Default backend port is 3001

Custom Domain

You can change the custom domain by updating the DEV_CUSTOM_NGROK_DOMAIN environment variable in your .env file. The domain should be your ngrok custom domain (e.g., yourname.ngrok.io).

Scripts

  • pnpm ngrok - Start ngrok tunnel only
  • pnpm dev:tunnel - Start both backend and ngrok tunnel
  • pnpm tunnel - Alias for pnpm ngrok
  • pnpm whatsapp:register-webhook - Register WhatsApp webhook with Ubots API

WhatsApp Webhook Registration

Once your ngrok tunnel is running, register your webhook URL with the Ubots API:

# Make sure your webhook URL is set in .env
# WHATSAPP_WEBHOOK_URL=https://nanndoj.ngrok.io/api/whatsapp/webhook

# Register the webhook
pnpm whatsapp:register-webhook

This script will:

  • Authenticate with the Ubots API using your credentials
  • Register your webhook URL to receive WhatsApp events
  • Configure event types: SENT, DELIVERED, READ, FAILED, RECEIVED