Skip to content

Commit 6e95e9d

Browse files
smashahsmashah
committed
📝 update intro docs
1 parent e0ac00f commit 6e95e9d

3 files changed

Lines changed: 192 additions & 77 deletions

File tree

‎docs/docs/get-started/quick-run.md‎

Lines changed: 81 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,120 +1,139 @@
11
---
2-
title: Get started with wa-automate via Docker
3-
sidebar_label: Easy API
2+
title: Quick Start Guide - wa-automate EASY API
3+
sidebar_label: Quick Start
44
sidebar_position: 0
5-
description:
6-
Guide showing how to use wa-automate with Docker. This also covers how to import
7-
data as well as persistence.
5+
description: A comprehensive guide to quickly set up wa-automate and create a Open-wa EASY API with zero installation requirements.
86
---
97

10-
# Zero Install EASY API
8+
# Quick Start Guide
119

12-
Ever wanted to create an API out of your WA number? You're in luck!
10+
Want to create an API from your WA number in seconds? This guide will show you how!
1311

14-
Open the terminal, and enter this:
12+
## Prerequisites
13+
14+
Before you begin, ensure you have the following installed on your system:
15+
- Node.js
16+
- npm (Node Package Manager)
17+
- npx (Node Package Runner)
18+
19+
## Basic Usage
20+
21+
1. Open your terminal and run:
1522

1623
```bash
17-
> npx @open-wa/wa-automate
24+
npx @open-wa/wa-automate
1825
```
1926

20-
> P.S you have to make sure you have `node`, `npm`, and `npx` installed on your system.
27+
This command will:
28+
- Start a @open-wa EASY API server
29+
- Provide you with a URL to an interactive API explorer
30+
- Generate documentation for all available endpoints
2131

22-
When you run the code, it will also give you a URL to an API explorer where you can play around with the various API endpoints with documentation.
32+
## Configuration Options
2333

24-
You can see all the help text like so:
34+
### Port Configuration
35+
Set a custom port for your API server:
2536

2637
```bash
27-
> npx @open-wa/wa-automate --help
38+
npx @open-wa/wa-automate -p 8080
2839
```
2940

30-
You can set a custom port:
41+
### API Security
42+
Protect your API with an authentication key:
3143

3244
```bash
33-
> npx @open-wa/wa-automate -p 8080
45+
# Auto-generate a secure key
46+
npx @open-wa/wa-automate -p 8080 -k
47+
48+
# Use a custom key
49+
npx @open-wa/wa-automate -p 8080 -k 'YOUR_SECURE_KEY'
3450
```
3551

36-
and an api key which will prevent unauthorized requests. This will result in a key being automatically generated for you:
52+
:::note
3753

38-
```bash
39-
> npx @open-wa/wa-automate -p 8080 -k
40-
```
54+
[randomkeygen.com](https://randomkeygen.com/) is a great resource for generating secure keys.
55+
56+
:::
4157

42-
or you can set your own, I got the following secure key from [https://randomkeygen.com/](https://randomkeygen.com/):
58+
### Tunneling
59+
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.
4360

4461
```bash
45-
> npx @open-wa/wa-automate -p 8080 -k 'K6MEQJRV3trXMPZ5eQd1Jl8NaaaRZxqy'
62+
npx @open-wa/wa-automate -p 8080 -k 'YOUR_SECURE_KEY' --tunnel
4663
```
4764

48-
You can easily force the program to maintain focus (`--keep-alive` or `-a`):
65+
:::note
4966

50-
```bash
51-
> npx @open-wa/wa-automate -p 8080 -k 'K6MEQJRV3trXMPZ5eQd1Jl8NaaaRZxqy' --keep-alive
67+
You will might need to manually install **cloudflared** for this to work.
5268

53-
//or
69+
:::
5470

55-
> npx @open-wa/wa-automate -p 8080 -k 'K6MEQJRV3trXMPZ5eQd1Jl8NaaaRZxqy' --keep-alive
56-
```
71+
## Session Management
5772

58-
## Restarting session
73+
Starting from version 2.0.0, sessions are managed using base64 strings. You can restore a session using any of these equivalent commands:
5974

60-
As of version 2.0.0 of this library, you can now provide session data as a base64 string. This is the default method goin forward and your `.data.json` files should have this string if you've run the program in version 2.0.0+.
75+
```bash
76+
# Using --session-data (recommended)
77+
npx @open-wa/wa-automate --session-data "YOUR_BASE64_SESSION_DATA"
6178

62-
There are 3 param tags that can be used to set session data `-s`, `--session` or `--session-data` - all work but make sure you wrap the string with double quotes `"` and NOT sinle quotes `'`.
79+
# Using --session
80+
npx @open-wa/wa-automate --session "YOUR_BASE64_SESSION_DATA"
6381

64-
```bash
65-
> npx @open-wa/wa-automate -p 8080 -k 'K6MEQJRV3trXMPZ5eQd1Jl8NaaaRZxqy' --session-data "eyJXQUJyb...ifQ=="
66-
//or
67-
> npx @open-wa/wa-automate -p 8080 -k 'K6MEQJRV3trXMPZ5eQd1Jl8NaaaRZxqy' --session "eyJXQUJyb...ifQ=="
68-
//or
69-
> npx @open-wa/wa-automate -p 8080 -k 'K6MEQJRV3trXMPZ5eQd1Jl8NaaaRZxqy' -s "eyJXQUJyb...ifQ=="
82+
# Using -s (shorthand)
83+
npx @open-wa/wa-automate -s "YOUR_BASE64_SESSION_DATA"
7084
```
7185

72-
## Running on a server
86+
:::note
87+
Always wrap your session data string in double quotes (`""`), not single quotes.
88+
:::
89+
90+
## Server Deployment
7391

74-
If you're not running this on your localhost, you'll need to set the server hostname for the api-docs to work correctly.
92+
When deploying to a remote server, specify your API hostname for proper documentation:
7593

7694
```bash
77-
> npx @open-wa/wa-automate -p 8080 --api-host 'https://my-wa-api.dev:8080'
95+
npx @open-wa/wa-automate -p 8080 --api-host 'https://your-api-domain.com:8080'
7896
```
7997

80-
## Webhooks
98+
## Webhook Integration
8199

82-
You can also set a webhook address to send all requests to. I like using [webhook.site](https://webhook.site/) to check and test events.
100+
Set up webhooks to receive real-time event notifications:
83101

84102
```bash
85-
> npx @open-wa/wa-automate -w 'https://webhook.site/7a00ac21-60f2-411e-a571-515b37b2025a'
103+
npx @open-wa/wa-automate -w 'https://your-webhook-url.com/endpoint'
86104
```
87105

88-
Now if you go to:
106+
:::tip Testing Webhooks
89107

90-
```http
91-
https://webhook.site/#!/7a00ac21-60f2-411e-a571-515b37b2025a
92-
```
108+
For testing webhooks, you can use services like [webhook.site](https://webhook.site/). Remember to clear your test data afterward for privacy!
93109

94-
you'll be able to see all the events come through.
110+
:::
95111

96-
If you do use this link please make sure to clear all of your requests for your privacy.
112+
## API Documentation
97113

98-
## API Docs
99-
100-
By default, the CLI generates and serves a swagger api explorer at `[host]/api-docs/`
114+
The API documentation is automatically available at:
115+
```
116+
http://[your-host]/api-docs/
117+
```
101118

102-
For example:
119+
This interactive documentation includes:
120+
- Complete endpoint listing
121+
- Request/response examples
122+
- Testing interface
123+
- Authentication details
103124

104-
```bash
105-
> npx @open-wa/wa-automate -w 'https://webhook.site/7a00ac21-60f2-411e-a571-515b37b2025a' -p 8008
106-
```
125+
## Getting Help
107126

108-
will server the api docs at
127+
View all available options and their descriptions:
109128

110-
```http
111-
http://localhost:8008/api-docs/
129+
```bash
130+
npx @open-wa/wa-automate --help
112131
```
113132

114-
## Postman collection
133+
## Postman Collection
115134

116-
The CLI will also automatically generate a postman collection for your specific set up (including api keys, hostname, ports, etc.) which you can then easily import into postman.
135+
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.
117136

118-
## Coming soon
137+
## Coming Soon
119138

120-
Soon SDKs for most programming lanugages will be created using the CLI as a base 'server'. Check this issue for updates: [#894](https://github.com/open-wa/wa-automate-nodejs/issues/894)
139+
SDKs for most programming languages will be created using the CLI as a base 'server'. Check this issue for updates: [#894](https://github.com/open-wa/wa-automate-nodejs/issues/894)

‎docs/docs/get-started/socketmode.md‎

Lines changed: 106 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,115 @@
11
---
2-
title: Socket mode
2+
title: Socket Mode
33
sidebar_position: 4
4-
description:
5-
Guide showing how to develop your own solutions without needing to wait for session restarts.
4+
description: Learn how to use Socket Mode to develop WhatsApp automation solutions with enhanced flexibility and development experience.
65
---
76

8-
# Socket mode
7+
# Socket Mode
98

10-
Now that you've checked out the EASY API and how to implement wa-automate with your own custom code I'm sure you're wondering if there was a best of both worlds? Yes there is! "Socket mode" allows you to seperate your session from your code and unlocks a number of benefits:
9+
Socket Mode is a powerful feature that allows you to separate your WhatsApp session from your application code. This separation provides several significant benefits:
1110

12-
- Your session and your code can be running on different servers
13-
- Rapid development - you no longer have to wait for a session to restart when restarting your custom code
14-
- 1-many - connect multiple socket clients to one session.
11+
- **Distributed Architecture**: Run your WhatsApp session and application code on different servers
12+
- **Rapid Development**: Make code changes without waiting for WhatsApp session restarts
13+
- **Multi-Client Support**: Connect multiple socket clients to a single WhatsApp session
14+
- **Enhanced Reliability**: Session persistence even if your application code crashes
1515

16-
How to:
16+
## Getting Started
1717

18-
## Step 1 - Start the EASY API in socket mode
18+
### Step 1: Start the EASY API in Socket Mode
1919

20+
Run the following command to start the EASY API with socket mode enabled:
21+
22+
```bash
23+
npx @open-wa/wa-automate --socket -p 8002 -k your_api_key
24+
```
25+
26+
Important parameters:
27+
- `--socket`: Required flag to enable socket mode
28+
- `-p 8002`: Port number for the socket server (can be customized)
29+
- `-k your_api_key`: Your API key for authentication
30+
31+
### Step 2: Connect Your Application
32+
33+
Here's an example showing how to connect to the socket server and interact with WhatsApp:
34+
35+
```typescript
36+
import {
37+
Client,
38+
SocketClient,
39+
} from "@open-wa/wa-automate-socket-client";
40+
41+
const RECIPIENT = 'PHONE_NUMBER@c.us'; // Format: country code + phone number
42+
43+
async function start() {
44+
// Connect to the socket server
45+
const client = await SocketClient.connect(
46+
"http://localhost:8002",
47+
"your_api_key"
48+
) as SocketClient & Client;
49+
50+
// Log the socket connection ID
51+
console.log("Socket Connected! ID:", client.socket.id);
52+
53+
// Listen for incoming messages
54+
client.onAnyMessage((message) => {
55+
console.log("New Message:", {
56+
messageId: message.id,
57+
content: message.body,
58+
sender: message.sender.id
59+
});
60+
});
61+
62+
// Example: Sending different types of messages
63+
64+
// Send text message
65+
const textMsg = await client.sendText(RECIPIENT, "Hello from Socket Mode!");
66+
console.log("Text message sent:", textMsg);
67+
68+
// Send audio file
69+
const audioMsg = await client.sendAudio(
70+
RECIPIENT,
71+
"https://example.com/audio.mp3"
72+
);
73+
console.log("Audio message sent:", audioMsg);
74+
75+
// Send video file with caption
76+
const videoMsg = await client.sendFile(
77+
RECIPIENT,
78+
"https://example.com/video.mp4",
79+
"video.mp4",
80+
"Check out this video!"
81+
);
82+
console.log("Video message sent:", videoMsg);
83+
}
84+
85+
start().catch(console.error);
86+
```
87+
88+
### Error Handling
89+
90+
Always implement proper error handling in your socket client:
91+
92+
```typescript
93+
client.socket.on('error', (error) => {
94+
console.error('Socket Error:', error);
95+
});
96+
97+
client.socket.on('disconnect', (reason) => {
98+
console.log('Socket Disconnected:', reason);
99+
});
100+
```
101+
102+
## Best Practices
103+
104+
1. **API Key Security**: Never hardcode your API key in the source code. Use environment variables instead.
105+
2. **Reconnection Logic**: Implement automatic reconnection logic for production environments.
106+
3. **Event Handling**: Set up proper event handlers for all relevant WhatsApp events you need to monitor.
107+
4. **Resource Cleanup**: Properly close socket connections when your application shuts down.
108+
109+
## Common Issues and Solutions
110+
111+
- If you can't connect, verify that the EASY API is running and the port is accessible
112+
- Ensure your API key matches between the server and client
113+
- Check network firewall settings if running on different machines
114+
115+
For more advanced usage and complete API reference, visit our [API Documentation](/api-reference).

‎docs/docs/intro.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ open-wa is a collection of tools designed to enable you to easily automate your
1111
There are multiple ways to run this library:
1212

1313
- CLI (npx/docker)
14-
- npx
15-
- docker
14+
- [npx](/docs/get-started/quick-run)
15+
- [Docker](/docs/get-started/docker)
1616

17-
- Your own code
18-
- Locally
19-
- Socketed
17+
- Your own custom code
18+
- [Locally](/docs/get-started/installation)
19+
- [Socketed](/docs/get-started/socketmode)

0 commit comments

Comments
 (0)