whatsapp-api-client-java

whatsapp-api-client-java - библиотека для интеграции с мессенджером WhatsApp через API сервиса green-api.com. Чтобы воспользоваться библиотекой, нужно получить регистрационный токен и ID аккаунта в личном кабинете. Есть бесплатный тариф аккаунта разработчика.

API

Документация к REST API находится по ссылке. Библиотека является оберткой к REST API, поэтому документация по ссылке выше применима и к самой библиотеке.

Авторизация

Чтобы отправить сообщение или выполнить другие методы Green API, аккаунт WhatsApp в приложении телефона должен быть в авторизованном состоянии. Для авторизации аккаунта перейдите в личный кабинет и сканируйте QR-код с использованием приложения WhatsApp.

Установка

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'

Примеры

Как инициализировать объект

Вы можете сконфигурировать свой bean, воспользоваться application.property или создать инстанс класса через конструктор.

Через конфигурацию:

@Configuration
public class GreenApiConf {

    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplateBuilder().build();
    }

    @Bean
    public GreenApi greenApi(RestTemplate restTemplate) {
        return new GreenApi(
            restTemplate,
            "https://media.greenapi.com",
            "https://api.greenapi.com",
            "{{YOUR-ID}}",
            "{{YOUR-TOKEN}}");
    }
}

Через application.yml:

Или используйте готовый бин, который клиент создается на основе параметров application.yml. Для этого укажите параметры вашего экземпляра в файле application.yml следующим образом:

green-api:
  host: https://api.green-api.com
  hostMedia: https://media.green-api.com
  instanceId: {{yourInstance}}
  token: {{yourToken}}

Убедитесь, что у вас есть RestTemplate bean с вашей конфигурацией, например:

@Bean
public RestTemplate restTemplate(RestTemplateBuilder restTemplateBuilder){
    return restTemplateBuilder.build();
    }

И добавьте com.greenapi.client в базовые пакеты для сканирования с помощью аннотации @ComponentScan:

@SpringBootApplication
@ComponentScan(basePackages = {"com.greenapi.client", "com.example"})
public class Application {

    public static void main(String[] args) {
        var context = SpringApplication.run(Application.class, args);
    }
}

Через конструктор:

var restTemplate=new RestTemplateBuilder().build();

    var greenApi1=new GreenApi(
    restTemplate,
    "https://media.green-api.com",
    "https://api.green-api.com",
    {{instanceId1}},
    {{instanceToken1}});

    var greenApi2=new GreenApi(
    restTemplate,
    "https://media.greenapi.com",
    "https://api.greenapi.com",
    {{instanceId2}},
    {{instanceToken2}});

Как отправить сообщение

Ссылка на пример: sendMessageExample.java.

@Log4j2
public class SendMessageExample {
    private void sendMessageExample(GreenApi greenApi) {
        var message = greenApi.sending.sendMessage(
            OutgoingMessage.builder()
                .chatId("111111111111@c.us")
                .message("Привет!")
                .build());

        if (message.getStatusCode().is2xxSuccessful()) {
            log.info(message.getBody());
        } else {
            log.warn("Message isn't sent, status code: " + message.getStatusCode());
        }
    }
}

Как создать группу и отправить сообщение

Ссылка на пример: CreateGroupSendMessageExample.java.

@Log4j2
class CreateGroupSendMessageExample {

    private void createGroupAndSendMessage(GreenApi greenApi) {
        var groupMembers = new ArrayList<String>();
        groupMembers.add("11001234567@c.us");
        groupMembers.add("11001234566@c.us");
        groupMembers.add("11001234565@c.us");

        var group = greenApi.groups.createGroup(
            CreateGroupReq.builder()
                .groupName("Test Group")
                .chatIds(groupMembers)
                .build()).getBody();

        if (group != null) {
            var message = 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());
            }
        }
    }
}

Как отправить файл загрузкой с диска

Чтобы отправить файл, нужно создать объект класса OutgoingFileByUpload и передать его в метод sendFileByUpload. Поля OutgoingFileByUpload соответствуют полям json объекта запроса.

Ссылка на пример: SendFileByUploadExample.java.

@Log4j2
public class SendFileByUploadExample {

    private void sendFileByUploadExample(GreenApi greenApi) {
        var file = new File("User/username/folder/Go-Logo_Blue.svg");

        var response = 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());
    }
}

Как отправить файл по ссылке

Ссылка на пример: SendFileByUrlExample.java.

@Log4j2
public class SendFileByUrlExample {

    private void sendFileByUrlExample(GreenApi greenApi) {
        var response = 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());
    }
}

Как отправить файл через uploadFile + sendFileByUrl

Ссылка на пример: UploadFileAndSendByUrlExample.java.

@Log4j2
public class UploadFileAndSendByUrlExample {

    private void uploadExample(GreenApi greenApi) throws IOException {
        var file = new File("User/username/folder/Go-Logo_Blue.svg");

        var response = greenApi.sending.uploadFile(file);
        if (response.getStatusCode().isError()) {
            log.error("upload file failed");
        }

        var responseEntity = greenApi.sending.sendFileByUrl(
            OutgoingFileByUrl.builder()
                .urlFile(Objects.requireNonNull(response.getBody()).getUrlFile())
                .build());

        log.info("file sent, message id: " + Objects.requireNonNull(responseEntity.getBody()).getIdMessage());
    }
}

Как отправить опрос

Ссылка на пример: SendPollExample.java.

@Log4j2
public class SendPollExample {
    private void sendPollExample(GreenApi greenApi) {
        var options = new ArrayList<Option>();
        options.add(new Option("option 1"));
        options.add(new Option("option 2"));
        options.add(new Option("option 3"));

        var dto = OutgoingPoll.builder()
            .chatId("111111111111@c.us")
            .message("text message")
            .options(options)
            .multipleAnswers(false)
            .build();

        var response = greenApi.sending.sendPoll(dto);
        log.info(response);
    }
}

Как получать входящие уведомления

Чтобы начать получать уведомления, нужно передать функцию-обработчик в webhookConsumer.start(). Функция-обработчик должна реализовывать интерфейс WebhookHandler. При получении нового уведомления ваша функция-обработчик будет выполнена. Чтобы перестать получать уведомления, нужно вызвать функцию webhookConsumer.stop().

WebhookConsumer - это класс ответственный за обработку сообщений, для его корректного функционирования нужны GreenApi и NotificationMapper. Вы можете передать их в него через бины или через конструктор.

NotificationMapper - это bean ответственный за преобразование JSON объекта в java объект. Для этого он использует ОbjectMapper из библиотеки com.fasterxml.jackson который должен быть доступен в качестве bean в конфигурации или установлен через конструктор.

WebhookHandler - это интерфейс. Вы можете написать любой класс для обработки уведомлений, просто реализуйте интерфейс и выполните свою логику в методе handle() или используйте лямбда выражение.

public interface WebhookHandler {
    void handle(Notification notification);
}

Ссылка на пример: WebhookExample.java.

@SpringBootApplication
public class WebhookExample {
    public static void main(String[] args) {
        var context = SpringApplication.run(WebhookExample.class, args);

        var webhookConsumer = (WebhookConsumer) context.getBean("webhookConsumer");
        webhookConsumer.start(notification -> System.out.println("New webhook received: " + notification));
    }
}

Как работать с контактами

Ссылка на пример: ContactsMethodsExample.java.

@Log4j2
class ContactsMethodsExample {

    private void addContact(GreenApi greenApi) {
        var addContactReq = AddContactReq.builder()
            .chatId("11001234567@c.us")
            .firstName("John")
            .lastName("Doe")
            .build();

        var addContactResp = greenApi.contacts.addContact(addContactReq).getBody();
    }

    private void editContact(GreenApi greenApi) {
        var editContactReq = EditContactReq.builder()
            .chatId("11001234567@c.us")
            .firstName("Jane")
            .lastName("Smith")
            .build();

        var editContactResp = greenApi.contacts.editContact(editContactReq).getBody();
    }

    private void deleteContact(GreenApi greenApi) {
        var deleteContactReq = DeleteContactReq.builder()
            .chatId("11001234567@c.us")
            .build();

        var deleteContactResp = greenApi.contacts.deleteContact(deleteContactReq).getBody();
    }
}

Так как каждое уведомление автоматически кастится до java объекта, вы можете фильтровать уведомление по любому полю самостоятельно. С описанием структуры объектов уведомлений можно ознакомиться по этой ссылке: Документация Для удобства все типы хуков и сообщений названы аналогично документации:

Java объект	Webhook's json объект
`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

Список примеров

Описание	Ссылка на пример
Как создать группу и отправить сообщение	SendMessageExample.java
Как создать группу и отправить сообщение	CreateGroupSendMessageExample.java
Как отправить файл загруженный с устройства	SendFileByUploadExample.java
Как отправить файл через ссылку	SendFileByUrlExample.java
Как отправить файл через uploadFile + sendByUrl	UploadFileAndSendByUrlExample.java
Как получать входящие уведомления	WebhookExample.java
Как работать с контактами	ContactsMethodsExample.java

Список всех методов библиотеки

Метод API	Описание	Documentation link
`account.getSettings()`	Метод предназначен для получения текущих настроек аккаунта	GetSettings
`account.setSettings()`	Метод предназначен для установки настроек аккаунта	SetSettings
`account.getStateInstance()`	Метод предназначен для получения состояния аккаунта	GetStateInstance
`account.getStatusInstance()`	Метод предназначен для получения состояния сокета соединения инстанса аккаунта с WhatsApp	GetStatusInstance
`account.reboot()`	Метод предназначен для перезапуска аккаунта	Reboot
`account.logout()`	Метод предназначен для разлогинивания аккаунта	Logout
`account.qr()`	Метод предназначен для получения QR-кода	QR
`account.getAuthorizationCode()`	Метод предназначен для авторизации экземпляра по номеру телефона. Метод используется как альтернатива методу QR.	GetAuthorizationCode
`account.setProfilePicture()`	Метод предназначен для установки аватара аккаунта	SetProfilePicture
`contacts.addContact()`	Метод предназначен для добавления контакта	AddContact
`contacts.editContact()`	Метод предназначен для изменения контакта	EditContact
`contacts.deleteContact()`	Метод предназначен для удаления контакта	DeleteContact
`device.getDeviceInfo()`	Метод предназначен для получения информации об устройстве (телефоне), на котором запущено приложение WhatsApp Business	GetDeviceInfo
`groups.createGroup()`	Метод предназначен для создания группового чата	CreateGroup
`groups.updateGroupName()`	Метод изменяет наименование группового чата	UpdateGroupName
`groups.getGroupData()`	Метод получает данные группового чата	GetGroupData
`groups.addGroupParticipant()`	Метод добавляет участника в групповой чат	AddGroupParticipant
`groups.removeGroupParticipant()`	Метод удаляет участника из группового чата	RemoveGroupParticipant
`groups.setGroupAdmin()`	Метод назначает участника группового чата администратором	SetGroupAdmin
`groups.removeAdmin()`	Метод лишает участника прав администрирования группового чата	RemoveAdmin
`groups.setGroupPicture()`	Метод устанавливает аватар группы	SetGroupPicture
`groups.leaveGroup()`	Метод производит выход пользователя текущего аккаунта из группового чата	LeaveGroup
`journals.getChatHistory()`	Метод возвращает историю сообщений чата	GetChatHistory
`journals.getMessage()`	Метод возвращает сообщение чата	GetMessage
`journals.lastIncomingMessages()`	Метод возвращает крайние входящие сообщения аккаунта	LastIncomingMessages
`journals.lastOutgoingMessages()`	Метод возвращает крайние отправленные сообщения аккаунта	LastOutgoingMessages
`queues.showMessagesQueue()`	Метод предназначен для получения списка сообщений, находящихся в очереди на отправку	ShowMessagesQueue
`queues.clearMessagesQueue()`	Метод предназначен для очистки очереди сообщений на отправку	ClearMessagesQueue
`readMark.readChat()`	Метод предназначен для отметки сообщений в чате прочитанными	ReadChat
`receiving.receiveNotification()`	Метод предназначен для получения одного входящего уведомления из очереди уведомлений	ReceiveNotification
`receiving.deleteNotification()`	Метод предназначен для удаления входящего уведомления из очереди уведомлений	DeleteNotification
`receiving.downloadFile()`	Метод предназначен для скачивания принятых и отправленных файлов	DownloadFile
`sending.sendMessage()`	Метод предназначен для отправки текстового сообщения в личный или групповой чат	SendMessage
`sending.sendButtons()`	Метод предназначен для отправки сообщения с кнопками в личный или групповой чат	SendButtons
`sending.sendTemplateButtons()`	Метод предназначен для отправки сообщения с интерактивными кнопками из перечня шаблонов в личный или групповой чат	SendTemplateButtons
`sending.sendPoll()`	Метод предназначен для отправки опроса в личный или групповой чат	SendPoll
`sending.sendListMessage()`	Метод предназначен для отправки сообщения с кнопкой выбора из списка значений в личный или групповой чат	SendListMessage
`sending.sendFileByUpload()`	Метод предназначен для отправки файла, загружаемого через форму (form-data)	SendFileByUpload
`sending.sendFileByUrl()`	Метод предназначен для отправки файла, загружаемого по ссылке	SendFileByUrl
`sending.uploadFile()`	Метод предназначен для загрузки файла в облачное хранилище, который можно отправить методом SendFileByUrl	UploadFile
`sending.sendLocation()`	Метод предназначен для отправки сообщения геолокации	SendLocation
`sending.sendContact()`	Метод предназначен для отправки сообщения с контактом	SendContact
`sending.sendLink()`	Метод предназначен для отправки сообщения со ссылкой, по которой будут добавлены превью изображения, заголовок и описание	SendLink
`sending.forwardMessages()`	Метод предназначен для пересылки сообщений в личный или групповой чат	ForwardMessages
`service.checkWhatsapp()`	Метод проверяет наличие аккаунта WhatsApp на номере телефона	CheckWhatsapp
`service.getAvatar()`	Метод возвращает аватар корреспондента или группового чата	GetAvatar
`service.getContacts()`	Метод предназначен для получения списка контактов текущего аккаунта	GetContacts
`service.getContactInfo()`	Метод предназначен для получения информации о контакте	GetContactInfo
`service.deleteMessage()`	Метод удаляет сообщение из чата	DeleteMessage
`service.archiveChat()`	Метод архивирует чат	ArchiveChat
`service.unarchiveChat()`	Метод разархивирует чат	UnarchiveChat
`service.setDisappearingChat()`	Метод предназначен для изменения настроек исчезающих сообщений в чатах	SetDisappearingChat
`webhook.start()`	Метод предназначен для старта получения новых уведомлений
`webhook.stop()`	Метод предназначен для остановки получения новых уведомлений
`statuses.sendTextStatus()`	Метод предназначен для отправки текстового статуса	SendTextStatus
`statuses.sendVoiceStatus()`	Метод предназначен для отправки голосового статуса	SendVoiceStatus
`statuses.sendMediaStatus()`	Метод предназначен для отправки медиа-файлов	SendMediaStatus
`statuses.getIncomingStatuses()`	Метод возвращает крайние входящие статусы аккаунта	GetIncomingStatuses
`statuses.getOutgoingStatuses()`	Метод возвращает крайние отправленные статусы аккаунта	GetOutgoingStatuses
`statuses.getStatusStatistic()`	Метод возвращает массив получателей со статусами, отмеченных как отправлено/доставлено/прочитано, для данного статуса	GetStatusStatistic

Документация по методам сервиса

Лицензия

Лицензировано на условиях Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0) . Смотрите файл LICENSE.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

whatsapp-api-client-java

API

Авторизация

Установка

Примеры

Как инициализировать объект

Как отправить сообщение

Как создать группу и отправить сообщение

Как отправить файл загрузкой с диска

Как отправить файл по ссылке

Как отправить файл через uploadFile + sendFileByUrl

Как отправить опрос

Как получать входящие уведомления

Как работать с контактами

Список примеров

Список всех методов библиотеки

Документация по методам сервиса

Лицензия

FilesExpand file tree

README_RU.md

Latest commit

History

README_RU.md

File metadata and controls

whatsapp-api-client-java

API

Авторизация

Установка

Примеры

Как инициализировать объект

Как отправить сообщение

Как создать группу и отправить сообщение

Как отправить файл загрузкой с диска

Как отправить файл по ссылке

Как отправить файл через uploadFile + sendFileByUrl

Как отправить опрос

Как получать входящие уведомления

Как работать с контактами

Список примеров

Список всех методов библиотеки

Документация по методам сервиса

Лицензия