Skip to content

Commit c490e61

Browse files
LouukeLouuke
authored
Add a complete documentation to the README
1 parent 544b9b3 commit c490e61

File tree

1 file changed

+190
-1
lines changed

1 file changed

+190
-1
lines changed

‎README.md

Lines changed: 190 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,191 @@
11
# WhatsJava
2-
Implementation of the WhatsApp Web API in Java
2+
WhatsJava is a reimplementation of the WhatsApp Web API and provides a direct interface for developers.
3+
4+
Big thanks to [@Sigalor](https://github.com/sigalor) and all participants of the [whatsapp-web-reveng project](https://github.com/sigalor/whatsapp-web-reveng) and [@adiwajshing](https://github.com/adiwajshing/Baileys) for the Typescript/Javascript implementation.
5+
6+
This project is **WIP** and things could break in the future.
7+
8+
## How to use it
9+
**Note**: The project is tested and compiled with Java 11
10+
11+
### Connect and login
12+
`WAClient` connects to the WhatsApp backend server and is used for all interactions with the server. Therefore, a new `WAClient` instance needs to be created first.
13+
14+
A path to a storage location is also required to store the keys needed to reestablish a session.
15+
```java
16+
WAClient client = new WAClient("auth.json");
17+
```
18+
The session is opened by calling `openConnection()`.
19+
```java
20+
WAClient client = new WAClient("auth.json");
21+
client.openConnection();
22+
```
23+
After a session has been successfully initialized, a qr code must be scanned from the device where WhatsApp is running on. To learn how to receive the qr code please refer to "Message handlers".
24+
25+
### Message handlers
26+
After a WAClient instance is initialized, the `addClientActionListener` method can be called to register a `ClientActionInterface` and receive a number of callbacks. `ClientActionListener` is an empty implementation of `ClientActionInterface` interface.
27+
28+
- Called when a new qr code has been generated and has to be scanned for login. A qr code has a lifetime of 20 seconds, which is why it can be generated up to five times.
29+
```java
30+
client.addClientActionListener(new ClientActionListener() {
31+
@Override
32+
public void onQRCodeScanRequired(BufferedImage img) {
33+
save(img);
34+
}
35+
36+
// ...
37+
});
38+
```
39+
- Called if the login was successful (Code: 200) or an error occurred.
40+
```java
41+
@Override
42+
public void onReceiveLoginResponse(int httpCode) {
43+
if(httpCode == 200) {
44+
System.out.println("Logged in successfully! Code: " + httpCode);
45+
} else {
46+
System.out.println("Login failed! Code: " + httpCode);
47+
}
48+
}
49+
```
50+
- Other callbacks defined in `ClientActionInterface` interface:
51+
```java
52+
@Override
53+
public void onWebChat(WebChat[] chats) {
54+
// ...
55+
}
56+
57+
@Override
58+
public void onWebContact(WebContact[] contacts) {
59+
// ...
60+
}
61+
62+
@Override
63+
public void onWebEmoji(WebEmoji[] emojis) {
64+
// ...
65+
}
66+
67+
@Override
68+
public void onWebStatus(WebStatus[] status) {
69+
// ...
70+
}
71+
72+
@Override
73+
public void onWebConversationMessage(WebConversationMessage conversationMessage) {
74+
// ...
75+
}
76+
77+
@Override
78+
public void onWebImageMessage(WebImageMessage imageMessage) {
79+
// ...
80+
}
81+
82+
@Override
83+
public void onWebVideoMessage(WebVideoMessage videoMessage) {
84+
// ...
85+
}
86+
```
87+
### Send text messages
88+
```java
89+
String remoteJid = "0123456789@s.whatsapp.net";
90+
91+
client.sendMessage(remoteJid, "Hello World");
92+
```
93+
**Note**:
94+
- WhatsApp identifies a person or a group with a unique chat identification - `jid`.
95+
- Chats: `[country code][phone number]@s.whatsapp.net`, for example `490123456789@s.whatsapp.net`
96+
- Groups: `[phone number of group creator]-[timestamp of group creation]@g.us`, e.g. `490123456789-1596766695@g.us`
97+
98+
### Load conversation
99+
Queries the chat history of a conversation
100+
```java
101+
// Query the last 25 messages
102+
client.loadConversation(remoteJid, 25);
103+
```
104+
Queries the chat history after a certain message
105+
```java
106+
// Query the last 25 messages after the message with the id x, which I'm not the owner of
107+
client.loadConversation(remoteJid, 25, "4C739872E8K15F7L0ACB", false);
108+
```
109+
110+
### Objects
111+
- **WebChat**: Contains information about direct chats or groups
112+
113+
| Method | Description |
114+
| ------------- |---------------|
115+
| getJid | Returns unique chat identification |
116+
| getName | Returns your given contact name |
117+
| getUnreadMessages | Returns the amount of unread messages |
118+
| getLastInteraction | Returns the timestamp of the last message |
119+
| isMuted | Returns if the chat is muted |
120+
121+
- **WebContact**: Contains information about direct chats or groups
122+
123+
| Method | Description |
124+
| ------------- |---------------|
125+
| getJid | Returns unique chat identification |
126+
| getName | Returns the name your contact gave to WhatsApp |
127+
128+
- **WebEmoji**: Contains information about the emojis you used the most
129+
130+
| Method | Description |
131+
| ------------- |---------------|
132+
| getCode | Returns emoji code |
133+
| getValue | Returns the frequency of use |
134+
135+
- **WebStatus**: Contains a WebImageMessage or WebVideoMessage
136+
137+
| Method | Description |
138+
| ------------- |---------------|
139+
| isWebImageMessage | Returns `true` if it contains a WebImageMessage |
140+
| isWebVideoMessage | Returns `true` if it contains a WebVideoMessage |
141+
| getWebImageMessage | Returns WebImageMessage |
142+
| getWebVideoMessage | Returns WebVideoMessage |
143+
144+
- **WebConversationMessage**: Contains information about generic text messages
145+
146+
| Method | Description |
147+
| ------------- |---------------|
148+
| getText | Returns content of the message |
149+
| hasQuotedTextMessage | Returns `true` if it contains a QuotedTextMessage |
150+
| getQuotedTextMessage | Returns QuotedTextMessage |
151+
152+
- **QuotedTextMessage**:
153+
154+
| Method | Description |
155+
| ------------- |---------------|
156+
| getText | Returns quote |
157+
158+
- **WebImageMessage**: Contains information about image messages
159+
160+
| Method | Description |
161+
| ------------- |---------------|
162+
| getMimetype | Returns mimetype of the image |
163+
| getCaption | Returns caption |
164+
| getJpegThumbnail | Returns a thumbnail of the image |
165+
| ... | ... |
166+
167+
**Note**: Full resolution images are not implemented
168+
169+
- **WebVideoMessage**: Contains information about video messages
170+
171+
| Method | Description |
172+
| ------------- |---------------|
173+
| getMimetype | Returns mimetype of the video |
174+
| getSeconds | Returns video length |
175+
| getJpegThumbnail | Returns a thumbnail of the video |
176+
| ... | ... |
177+
178+
**Note**: The download of videos is not implemented
179+
180+
- **WebMessage**: Each Web[Type]Message class extends WebMessage and therefore contains the following methods
181+
182+
| Method | Description |
183+
| ------------- |---------------|
184+
| getRemoteJid | Returns unique chat identification |
185+
| getId | Returns the id of a message |
186+
| getFromMe | Returns `true` if the message is from you |
187+
| getMessageTimestamp | Returns the message timestamp |
188+
| getStatus | Returns the status of the message |
189+
190+
## Legal
191+
This code is in no way affiliated with, authorized, maintained, sponsored or endorsed by WhatsApp or any of its affiliates or subsidiaries. This is an independent and unofficial software. Use at your own risk.

0 commit comments

Comments
 (0)