Skip to main content

Quick Start Guide

Want to create an API from your WA number in seconds? This guide will show you how!

Prerequisites​

Before you begin, ensure you have the following installed on your system:

  • Node.js
  • npm (Node Package Manager)
  • npx (Node Package Runner)

Basic Usage​

  1. Open your terminal and run:
npx @open-wa/wa-automate

This command will:

  • Start a @open-wa EASY API server
  • Provide you with a URL to an interactive API explorer
  • Generate documentation for all available endpoints

Configuration Options​

Port Configuration​

Set a custom port for your API server:

npx @open-wa/wa-automate -p 8080

API Security​

Protect your API with an authentication key:

# Auto-generate a secure key
npx @open-wa/wa-automate -p 8080 -k

# Use a custom key
npx @open-wa/wa-automate -p 8080 -k 'YOUR_SECURE_KEY'
note

randomkeygen.com is a great resource for generating secure keys.

Tunneling​

Your EASY API instance, by default, will be only accessible in your local network. This is useful and secure for local development but if you want to be able to access the API outside of your network you can do so easily with the --tunnel flag.

npx @open-wa/wa-automate -p 8080 -k 'YOUR_SECURE_KEY' --tunnel
note

You will might need to manually install cloudflared for this to work.

Session Management​

You may want to run multiple instances of the easy api for different host accounts. To enable this you will need to ensure that each session has a unique session ID and a seperate port.

# Using --session-data (recommended)
npx @open-wa/wa-automate --session-id sales --port 8081

# Using --session
npx @open-wa/wa-automate --session-id marketing --port 8082

Server Deployment​

When deploying to a remote server, specify your API hostname for proper documentation:

npx @open-wa/wa-automate -p 8080 --api-host 'https://your-api-domain.com:8080'

Webhook Integration​

Set up webhooks to receive real-time event notifications:

npx @open-wa/wa-automate -w 'https://your-webhook-url.com/endpoint'
Testing Webhooks

For testing webhooks, you can use services like webhook.site. Remember to clear your test data afterward for privacy!

API Documentation​

The API documentation is automatically available at:

http://[your-host]/api-docs/

This interactive documentation includes:

  • Complete endpoint listing
  • Request/response examples
  • Testing interface
  • Authentication details

Process Management with PM2​

Starting from V4.35.0, you can manage your EASY API process using PM2. This provides several benefits:

  • Automatic session recovery after restarts
  • Memory usage management
  • Process monitoring and logging
  • Scheduled restarts
Prerequisites

Make sure you have PM2 installed globally:

npm install -g pm2@latest

Basic PM2 Integration​

Use the --pm2 flag to offload your process to PM2:

npx @open-wa/wa-automate --pm2 --session-id STICKER-BOT
note

The process name is taken from the --session-id flag (default: @OPEN-WA EASY API). PM2 will not read the session ID from cli.config.json.

To use a different PM2 process name while keeping your existing session ID:

npx @open-wa/wa-automate --pm2 --name STICKER-BOT

Advanced PM2 Configuration​

PM2 offers powerful process management features that you can utilize:

npx @open-wa/wa-automate --pm2 "--max-memory-restarts 300M --cron-restart=\"0 */3 * * *\" --restart-delay=3000" --name STICKER-BOT

This example:

  • Restarts the process if memory exceeds 300MB
  • Schedules restarts every 3 hours
  • Adds a 3-second delay between restarts
warning

When using PM2 flags, do not use the = sign between the --pm2 flag and its value. The following will NOT work:

npx @open-wa/wa-automate --pm2="--max-memory-restarts 300M"

Getting Help​

View all available options and their descriptions:

npx @open-wa/wa-automate --help

Postman Collection​

A Postman collection is automatically generated for your specific setup, including API keys, hostname, ports, and more. You can easily import this collection into Postman for further testing and exploration.

Coming Soon​

SDKs for most programming languages will be created using the CLI as a base 'server'. Check this issue for updates: #894