whatsapp-api-client-java

whatsapp-api-client-java is a library for integration with WhatsApp messenger using the API service green-api.com. You should get a registration token and an account ID in your personal cabinet to use the library. There is a free developer account tariff.

API

The documentation for the REST API can be found at the link. The library is a wrapper for the REST API, so the documentation at the link above also applies.

Authorization

To send a message or perform other Green API methods, the WhatsApp account in the phone app must be authorized. To authorize the account, go to your cabinet and scan the QR code using the WhatsApp app.

Installation

Maven

<dependency>
<groupId>com.green-api</groupId>
<artifactId>whatsapp-api-client-java</artifactId>
<version>version</version>
</dependency>

Gradle

implementation group: 'com.green-api', name: 'whatsapp-api-client-java', version: 'version'

Examples

How to initialize an object

You can configure your bean, use application.yml, or instantiate class via the constructor.

Via configuration:

@ConfigurationpublicclassGreenApiConf {
@BeanpublicRestTemplaterestTemplate() {
returnnewRestTemplateBuilder().build();
}
@BeanpublicGreenApigreenApi(RestTemplaterestTemplate) {
returnnewGreenApi(
restTemplate,
"https://media.greenapi.com",
"https://api.greenapi.com",
"{{YOUR-ID}}",
"{{YOUR-TOKEN}}");
}
}

Via application.yml:

To use a ready-made bean that is created based on application.yml parameters, specify the parameters of your instance in the application.yml file as follows:

green-api:
host: https://api.green-api.comhostMedia: https://media.green-api.cominstanceId: {{yourInstance}}token: {{yourToken}}

Make sure you have a RestTemplate bean with your configuration, like this:

@BeanpublicRestTemplaterestTemplate(RestTemplateBuilderrestTemplateBuilder){
returnrestTemplateBuilder.build();
}

And add com.greenapi.client to the base scanning packages using the @ComponentScan annotation:

@SpringBootApplication@ComponentScan(basePackages = {"com.greenapi.client", "com.example"})
publicclassApplication {
publicstaticvoidmain(String[] args) {
varcontext = SpringApplication.run(Application.class, args);
}
}

Via constructor:

varrestTemplate = newRestTemplateBuilder().build();
vargreenApi1 = newGreenApi(
restTemplate,
"https://media.green-api.com",
"https://api.green-api.com",
{{instanceId1}},
{{instanceToken1}});
vargreenApi2 = newGreenApi(
restTemplate,
"https://media.greenapi.com",
"https://api.greenapi.com",
{{instanceId2}},
{{instanceToken2}});

How to send message

Link to example: sendMessageExample.java.

@Log4j2publicclassSendMessageExample {
privatevoidsendMessageExample(GreenApigreenApi) {
varmessage = greenApi.sending.sendMessage(
OutgoingMessage.builder()
.chatId("111111111111@c.us")
.message("hola a todos")
.build());
if (message.getStatusCode().is2xxSuccessful()) {
log.info(message.getBody());
} else {
log.warn("Message isn't sent, status code: " + message.getStatusCode());
}
}
}

How to create a group and send message

Link to example: CreateGroupSendMessageExample.java.

@Log4j2classCreateGroupSendMessageExample {
privatevoidcreateGroupAndSendMessage(GreenApigreenApi) {
vargroupMembers = newArrayList<String>();
groupMembers.add("11001234567@c.us");
groupMembers.add("11001234566@c.us");
groupMembers.add("11001234565@c.us");
vargroup = greenApi.groups.createGroup(
CreateGroupReq.builder()
.groupName("Test Group")
.chatIds(groupMembers)
.build()).getBody();
if (group != null) {
varmessage = greenApi.sending.sendMessage(
OutgoingMessage.builder()
.chatId(group.getChatId())
.message("hola a todos")
.build()).getBody();
if (message != null) {
log.info("Create group: " + group.isCreated() +
"\nSend message: " + message.getIdMessage());
}
}
}
}

How to send a file by uploading from the disk

To send a file, you need to give the path to the file.

Link to example: SendFileByUploadExample.java.

@Log4j2publicclassSendFileByUploadExample {
privatevoidsendFileByUploadExample(GreenApigreenApi) {
varfile = newFile("User/username/folder/Go-Logo_Blue.svg");
varresponse = greenApi.sending.sendFileByUpload(OutgoingFileByUpload.builder()
.file(file)
.fileName(file.getName())
.chatId("11001234567@c.us")
.build());
if (response.getStatusCode().isError()) {
log.warn("message sending is failed");
}
log.info("message sent, id: " + Objects.requireNonNull(response.getBody()).getIdMessage());
}
}

How to send a file by URL

Link to example: SendFileByUrlExample.java.

@Log4j2publicclassSendFileByUrlExample {
privatevoidsendFileByUrlExample(GreenApigreenApi) {
varresponse = greenApi.sending.sendFileByUrl(OutgoingFileByUrl.builder()
.urlFile("https://go.dev/blog/go-brand/Go-Logo/SVG/Go-Logo_Blue.svg")
.fileName("Go-Logo_Blue.svg")
.chatId("11001234567@c.us")
.build());
if (response.getStatusCode().isError()) {
log.warn("message sending is failed");
}
log.info("message sent, id: " + Objects.requireNonNull(response.getBody()).getIdMessage());
}
}

How to send a file by UploadFile + SendFileByUrl

Link to example: UploadFileAndSendByUrlExample.java.

@Log4j2publicclassUploadFileAndSendByUrlExample {
privatevoiduploadExample(GreenApigreenApi) throwsIOException {
varfile = newFile("User/username/folder/Go-Logo_Blue.svg");
varresponse = greenApi.sending.uploadFile(file);
if (response.getStatusCode().isError()) {
log.error("upload file failed");
}
varresponseEntity = greenApi.sending.sendFileByUrl(
OutgoingFileByUrl.builder()
.urlFile(Objects.requireNonNull(response.getBody()).getUrlFile())
.build());
log.info("file sent, message id: " + Objects.requireNonNull(responseEntity.getBody()).getIdMessage());
}
}

How to send a Poll

Link to example: SendPollExample.java.

@Log4j2publicclassSendPollExample {
privatevoidsendPollExample(GreenApigreenApi) {
varoptions = newArrayList<Option>();
options.add(newOption("option 1"));
options.add(newOption("option 2"));
options.add(newOption("option 3"));
vardto = OutgoingPoll.builder()
.chatId("111111111111@c.us")
.message("text message")
.options(options)
.multipleAnswers(false)
.build();
varresponse = greenApi.sending.sendPoll(dto);
log.info(response);
}
}

How to receive incoming notifications

To start receiving notifications, you need to pass a handler function to webhookConsumer.start(). The handler function should implement the WebhookHandler interface. When a new notification is received, your handler function will be executed. To stop receiving notifications, you need to call the webhookConsumer.stop() function.

WebhookConsumer is a class responsible for processing messages. For its correct functioning, it requires GreenApi and NotificationMapper. You can inject them into it using beans or through the constructor.

NotificationMapper is a bean responsible for converting a JSON object into a Java object. It uses the ObjectMapper from the com.fasterxml.jackson library, which should be available as a bean in your configuration or set via the constructor.

WebhookHandler is an interface. You can write any class to handle notifications; just implement the interface and execute your logic in the handle() method or use a lambda expression.

publicinterfaceWebhookHandler {
voidhandle(Notificationnotification);
}

Link to example: WebhookExample.java.

@SpringBootApplicationpublicclassWebhookExample {
publicstaticvoidmain(String[] args) {
varcontext = SpringApplication.run(WebhookExample.class, args);
varwebhookConsumer = (WebhookConsumer) context.getBean("webhookConsumer");
webhookConsumer.start(notification -> System.out.println("New webhook received: " + notification));
}
}

How to work with contacts

Link to example: ContactsMethodsExample.java.

@Log4j2classContactsMethodsExample {
privatevoidaddContact(GreenApigreenApi) {
varaddContactReq = AddContactReq.builder()
.chatId("11001234567@c.us")
.firstName("John")
.lastName("Doe")
.build();
varaddContactResp = greenApi.contacts.addContact(addContactReq).getBody();
}
privatevoideditContact(GreenApigreenApi) {
vareditContactReq = EditContactReq.builder()
.chatId("11001234567@c.us")
.firstName("Jane")
.lastName("Smith")
.build();
vareditContactResp = greenApi.contacts.editContact(editContactReq).getBody();
}
privatevoiddeleteContact(GreenApigreenApi) {
vardeleteContactReq = DeleteContactReq.builder()
.chatId("11001234567@c.us")
.build();
vardeleteContactResp = greenApi.contacts.deleteContact(deleteContactReq).getBody();
}
}

Since each notification is automatically cast to a java object, you can filter the notification by any field yourself. A description of the structure of notification objects can be found at this link: Documentation For convenience, all types of hooks and messages are named similarly to the documentation:

Java object	Webhook's json object
`TextMessageWebhook`	TextMessage
`TemplateMessageWebhook`	TemplateMessage
`StickerMessageWebhook`	StickerMessage
`ReactionMessageWebhook`	ReactionMessage
`QuotedMessageWebhook`	QuotedMessage
`PollUpdateMessageWebhook`	PollUpdateMessage
`PollMessageWebhook`	PollMessage
`LocationMessageWebhook`	LocationMessage
`ListMessageWebhook`	ListMessage
`GroupInviteMessageWebhook`	GroupInviteMessage
`FileMessageWebhook`	imageMessage, videoMessage, documentMessage, audioMessage
`ExtendedTextMessageWebhook`	ExtendedTextMessage
`ButtonsMessageWebhook`	ButtonsMessage
`ContactMessageWebhook`	ContactMessage
`ContactsArrayMessageWebhook`	ContactMessage
`TemplateButtonsReplyMessageWebhook`	TemplateButtonsReplyMessage
`ButtonsResponseMessageWebhook`	ButtonsResponseMessage
`ListResponseMessageWebhook`	ListResponseMessage

List of examples

Description	Link to example
How to send message	SendMessageExample.java
How to create a group and send message	CreateGroupSendMessageExample.java
How to send a file by uploading from the disk	SendFileByUploadExample.java
How to send a file by URL	SendFileByUrlExample.java
How to send a file by UploadFile + SendByUrl	UploadFileAndSendByUrlExample.java
How to receive incoming notifications	WebhookExample.java
How to work with contacts	ContactsMethodsExample.java
How to forward messages	ForwardMessagesExample.java
How to send interactive buttons	SendInteractiveButtonsExample.java
How to send a typing/recording indicator	SendTypingExample.java
How to get the list of chats	GetChatsExample.java
How to get incoming and outgoing calls	CallsJournalExample.java
How to update group settings	UpdateGroupSettingsExample.java
How to use getStateInstanceHistory and updateApiToken	AccountMethodsExample.java
How to delete a status	DeleteStatusExample.java
How to send a message with typing time and custom preview	SendMessageWithPreviewExample.java
How to send a file with typing indicator	SendFileWithTypingExample.java

List of all library methods

Method	Description	Documentation
`account.getSettings()`	The method is aimed for getting the current settings of the account settings	GetSettings
`account.setSettings()`	The method is aimed for setting an account settings settings	SetSettings
`account.getStateInstance()`	The method is aimed for getting the account state	GetStateInstance
`account.getStatusInstance()`	The method is aimed for getting the status of the account instance socket connection with WhatsApp	GetStatusInstance
`account.reboot()`	The method is aimed for rebooting an account	Reboot
`account.logout()`	The method is aimed for logging out an account	Logout
`account.qr()`	The method is aimed for getting QR code	QR
`account.getAuthorizationCode()`	The method is intended to authorize an instance by phone number. The method is used as an alternative to the QR method.	GetAuthorizationCode
`account.setProfilePicture()`	The method is aimed for setting an account picture	SetProfilePicture
`account.getStateInstanceHistory()`	The method returns the history of instance state changes	GetStateInstanceHistory
`account.updateApiToken()`	The method generates a new API token for the instance	UpdateApiToken
`contacts.addContact()`	The method is aimed for adding a number to contacts	AddContact
`contacts.editContact()`	The method is used to edit a number in contacts	EditContact
`contacts.deleteContact()`	The method is used to remove a number from contacts	DeleteContact
`device.getDeviceInfo()`	The method is aimed for getting information about the device (phone) running WhatsApp Business application	GetDeviceInfo
`groups.createGroup()`	The method adds a participant to a group chat. IMPORTANT: If one tries to create a group with a non-existent number, WhatsApp may block the sender's number.	CreateGroup
`groups.updateGroupName()`	The method changes a group chat name	UpdateGroupName
`groups.getGroupData()`	The method gets group chat data	GetGroupData
`groups.addGroupParticipant()`	The method adds a participant to a group chat	AddGroupParticipant
`groups.removeGroupParticipant()`	The method removes a participant from a group chat	RemoveGroupParticipant
`groups.setGroupAdmin()`	The method sets a group chat participant as an administrator	SetGroupAdmin
`groups.removeAdmin()`	The method removes a participant from group chat administartion rights	RemoveAdmin
`groups.setGroupPicture()`	The method sets a group picture	SetGroupPicture
`groups.leaveGroup()`	The method makes the current account user leave the group chat	LeaveGroup
`groups.updateGroupSettings()`	The method updates the group's permission settings (who can send messages, edit group info)	UpdateGroupSettings
`journals.getChatHistory()`	The method returns the chat message history	GetChatHistory
`journals.getMessage()`	The method returns the chat message	GetMessage
`journals.lastIncomingMessages()`	The method returns the last incoming messages of the account. In the default mode the incoming messages for 24 hours are returned	LastIncomingMessages
`journals.lastOutgoingMessages()`	The method returns the last outgoing messages of the account. In the default mode the last messages for 24 hours are returned	LastOutgoingMessages
`journals.lastIncomingCalls()`	The method returns the last incoming calls of the account	LastIncomingCalls
`journals.lastOutgoingCalls()`	The method returns the last outgoing calls of the account	LastOutgoingCalls
`queues.showMessagesQueue()`	The method is aimed for getting a list of messages in the queue to be sent	ShowMessagesQueue
`queues.slearMessagesQueue()`	The method is aimed for clearing the queue of messages to be sent	ClearMessagesQueue
`readMark.readChat()`	The method is aimed for marking messages in a chat as read. Either all messages or a specified message in a chat can be marked as read	ReadChat
`receiving.receiveNotification()`	The method is aimed for receiving one incoming notification from the notifications queue	ReceiveNotification
`receiving.deleteNotification()`	The method is aimed for deleting an incoming notification from the notification queue	DeleteNotification
`receiving.downloadFile()`	The method is aimed for downloading incoming and outgoing files	DownloadFile
`sending.sendMessage()`	The method is aimed for sending a text message to a personal or a group chat	SendMessage
`sending.sendButtons()`	The method is aimed for sending a button message to a personal or a group chat	SendButtons
`sending.sendTemplateButtons()`	The method is aimed for sending a message with template list interacrive buttons to a personal or a group chat	SendTemplateButtons
`sending.sendPoll()`	The method is aimed for sending a poll a personal or a group chat	SendPoll
`sending.sendListMessage()`	The method is aimed for sending a message with a select button from a list of values to a personal or a group chat	SendListMessage
`sending.sendFileByUpload()`	The method is aimed for sending a file uploaded by form (form-data)	SendFileByUpload
`sending.sendFileByUrl()`	The method is aimed for sending a file uploaded by Url	SendFileByUrl
`sending.uploadFile()`	The method is designed to upload a file to the cloud storage, which can be sent using the sendFileByUrl method	UploadFile
`sending.sendLocation()`	The method is aimed for sending a location message	SendLocation
`sending.sendContact()`	The method is aimed for sending a contact message	SendContact
`sending.sendLink()`	The method is aimed for sending a message with a link, by which an image preview, title and description will be added	SendLink
`sending.forwardMessages()`	The method is intended for forwarding messages to a personal or group chat	ForwardMessages
`sending.sendInteractiveButtons()`	The method sends a message with action buttons (url, call, copy code) to a chat	SendInteractiveButtons
`sending.sendInteractiveButtonsReply()`	The method sends a message with reply buttons to a chat. Beta feature	SendInteractiveButtonsReply
`service.checkWhatsapp()`	The method checks WhatsApp account availability on a phone number	CheckWhatsapp
`service.getAvatar()`	The method returns a user or a group chat avatar	GetAvatar
`service.getContacts()`	The method is aimed for getting a list of the current account contacts	GetContacts
`service.getContactInfo()`	The method is aimed for getting information on a contact	GetContactInfo
`service.deleteMessage()`	The method deletes a message from a chat	DeleteMessage
`service.archiveChat()`	The method archives a chat. One can archive chats that have at least one incoming message	ArchiveChat
`service.unarchiveChat()`	The method unarchives a chat	UnarchiveChat
`service.setDisappearingChat()`	The method is aimed for changing settings of disappearing messages in chats	SetDisappearingChat
`service.editMessage()`	The method is aimed for editing a text message in a chat	EditMessage
`service.sendTyping()`	The method shows a typing or recording indicator to the chat recipient	SendTyping
`service.getChats()`	The method returns the list of chats for the current account	GetChats
`webhook.start()`	The method is aimed for starting to receive webhooks
`webhook.stop()`	The method is aimed for stopping to receive webhooks
`statuses.sendTextStatus()`	The method is used to send a text status	SendTextStatus
`statuses.sendVoiceStatus()`	The method is used to send a voice status	SendVoiceStatus
`statuses.sendMediaStatus()`	The method is used to send a pictures or video status	SendMediaStatus
`statuses.getIncomingStatuses()`	The method is used to get the incoming status messages of the instance	GetIncomingStatuses
`statuses.getOutgoingStatuses()`	The method is used to get the outgoing statuses of the account	GetOutgoingStatuses
`statuses.getStatusStatistic()`	The method is used to get an array of recipients marked sent/delivered/read for a given status	GetStatusStatistic
`statuses.deleteStatus()`	The method deletes a sent status	DeleteStatus

Service methods documentation

License

Licensed under Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0) terms. Please see file LICENSE.

Name		Name	Last commit message	Last commit date
.mvn/wrapper		.mvn/wrapper
skills/greenapi-whatsapp-java		skills/greenapi-whatsapp-java
src		src
.gitignore		.gitignore
LICENSE.txt		LICENSE.txt
README.md		README.md
lombok.config		lombok.config
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

Navigation Menu

Uh oh!

Repository files navigation

whatsapp-api-client-java

API

Authorization

Installation

Examples

How to initialize an object

How to send message

How to create a group and send message

How to send a file by uploading from the disk

How to send a file by URL

How to send a file by UploadFile + SendFileByUrl

How to send a Poll

How to receive incoming notifications

How to work with contacts

List of examples

List of all library methods

Service methods documentation

License

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

whatsapp-api-client-java

API

Authorization

Installation

Examples

How to initialize an object

How to send message

How to create a group and send message

How to send a file by uploading from the disk

How to send a file by URL

How to send a file by UploadFile + SendFileByUrl

How to send a Poll

How to receive incoming notifications

How to work with contacts

List of examples

List of all library methods

Service methods documentation

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages