green-api · VadimSav · Jul 22, 2026 · Jul 20, 2026
diff --git a/skills/green-api-java-sdk/SKILL.md b/skills/green-api-java-sdk/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: green-api-java-sdk
+metadata:
+  version: 0.1.0
+description: Implement WhatsApp integrations in Java with com.green-api:whatsapp-api-client-java 0.1.8. Use for GREEN-API sending, files, polling, webhooks, account, groups, journals, queues, marking, and service operations.
+---
+
+# GREEN-API Java SDK 0.1.8
+
+Use only with com.green-api:whatsapp-api-client-java:0.1.8. This skill is inventory-locked: use only members and DTOs in references/sdk-inventory.md. Read the linked official GREEN-API page before every implementation; it is authoritative for semantics, parameters, limits, notification formats, and errors.
+
+Before a live action confirm greenApi.account.getStateInstance() is authorized, keep tokens in environment variables, check ResponseEntity status and body, and run references/verification.md.
+
+## Initialization
+
+    GreenApi greenApi = new GreenApi(new RestTemplate(),
+        "https://media.green-api.com", "https://api.green-api.com",
+        System.getenv("GREEN_API_INSTANCE_ID"), System.getenv("GREEN_API_TOKEN"));
+
+Constructor order is exactly RestTemplate, hostMedia, host, instanceId, instanceToken. Spring Boot uses green-api.host, green-api.hostMedia, green-api.instanceId, green-api.token and component scanning com.greenapi.client.
+
+## Send text
+
+    var response = greenApi.sending.sendMessage(OutgoingMessage.builder()
+        .chatId("79990000000@c.us").message("Hello from GREEN-API").build());
+    if (!response.getStatusCode().is2xxSuccessful() || response.getBody() == null)
+        throw new IllegalStateException("sendMessage failed: " + response.getStatusCode());
+    String idMessage = response.getBody().getIdMessage();
+
+chatId and message are required. Personal chats use <digits>@c.us; groups use <group-id>@g.us. Official SendMessage limit: 20,000 characters, UTF-8 without BOM.
+
+## Send file
+
+    File file = new File("/absolute/path/report.pdf");
+    var response = greenApi.sending.sendFileByUpload(OutgoingFileByUpload.builder()
+        .chatId("79990000000@c.us").file(file).fileName(file.getName()).caption("Report").build());
+
+For repeated delivery use uploadFile(File) then sendFileByUrl(OutgoingFileByUrl). See references/sending-and-files.md.
+
+## Poll or webhook
+
+receiveNotification() returns body "null" when empty. Process FIFO and delete only after successful handling:
+
+    var json = greenApi.receiving.receiveNotification().getBody();
+    if (json != null && !"null".equals(json)) {
+        var notification = new NotificationMapper().get(json);
+        handle(notification);
+        greenApi.receiving.deleteNotification(notification.getReceiptId());
+    }
+
+Configure InstanceSettingsReq.webhookUrl and switches for direct HTTP webhooks, parse POST JSON with NotificationMapper.get(String), and never delete a queue notification in that handler. WebhookConsumer.start(WebhookHandler) is polling, not an HTTP endpoint.
+
+## Pitfalls
+
+- Authorization is required; queued messages may remain 24 hours.
+- Set documented delaySendMessagesMilliseconds; never burst messages.
+- Use ASCII @c.us and @g.us suffixes.
+- Source marks sendButtons, sendTemplateButtons, and sendListMessage temporarily unavailable (HTTP 403).
diff --git a/skills/green-api-java-sdk/references/receiving-and-webhooks.md b/skills/green-api-java-sdk/references/receiving-and-webhooks.md
@@ -0,0 +1,11 @@
+# Receiving and webhooks
+
+| SDK call | Official page | SDK behavior |
+|---|---|---|
+| `receiving.receiveNotification()` | [ReceiveNotification](https://green-api.com/en/docs/api/receiving/technology-http-api/ReceiveNotification/) | `ResponseEntity<String>`; body is literal `null` when queue is empty |
+| `receiving.deleteNotification(Integer)` | [DeleteNotification](https://green-api.com/en/docs/api/receiving/technology-http-api/DeleteNotification/) | delete the receipt only after processing |
+| `receiving.downloadFile(MessageReq)` | [DownloadFile](https://green-api.com/en/docs/api/receiving/files/DownloadFile/) | `ResponseEntity<byte[]>` |
+
+The official [HTTP API guide](https://green-api.com/en/docs/api/receiving/technology-http-api/) requires FIFO receive → process → delete. Notifications are retained for 24 hours; repeat requests ending in HTTP 500+. Configure notification switches with `account.setSetting(InstanceSettingsReq)`.
+
+For direct webhooks set `InstanceSettingsReq.webhookUrl` and the required switch fields, then accept POST JSON and parse it with `NotificationMapper.get(String)`. Read the official [webhook endpoint](https://green-api.com/en/docs/api/receiving/technology-webhook/) and applicable [notification format](https://green-api.com/en/docs/api/receiving/notifications-format/) page before branching by type. `WebhookConsumer` is a polling consumer, not an HTTP endpoint.
diff --git a/skills/green-api-java-sdk/references/sdk-inventory.md b/skills/green-api-java-sdk/references/sdk-inventory.md
@@ -0,0 +1,16 @@
+# SDK API inventory: 0.1.8
+
+Every method below is present in the `whatsapp-api-client-java-0.1.8` source JAR. Read the corresponding page in the official [GREEN-API API index](https://green-api.com/en/docs/api/) before using it; that page is authoritative for parameters, responses, limits, and errors.
+
+| Group | Implemented public methods |
+|---|---|
+| account | `getSettings()`, `getWaSettings()`, `setSetting(InstanceSettingsReq)`, `getStateInstance()`, `getStatusInstance()`, `reboot()`, `logout()`, `getQrCode()`, `setProfilePicture(File)`, `getAuthorizationCode(Long)` |
+| groups | `createGroup(CreateGroupReq)`, `updateGroupName(ChangeGroupNameReq)`, `getGroupData(String)`, `addGroupParticipant(ChangeParticipantReq)`, `removeGroupParticipant(ChangeParticipantReq)`, `setGroupAdmin(ChangeParticipantReq)`, `removeGroupAdmin(ChangeParticipantReq)`, `setGroupPicture(ChangeGroupPictureReq)`, `leaveGroup(String)` |
+| journals | `getChatHistory(GetChatHistoryReq)`, `getMessage(MessageReq)`, `lastIncomingMessages(Integer)`, `lastOutgoingMessages(Integer)` |
+| queues | `showMessagesQueue()`, `clearMessagesQueue()` |
+| marking | `readChat(MessageReq)` |
+| service | `checkWhatsapp(Long)`, `getAvatar(String)`, `getContacts()`, `getContactInfo(String)`, `deleteMessage(MessageReq)`, `archiveChat(String)`, `unarchiveChat(String)`, `setDisappearingChat(String, Long)` |
+| sending | `sendMessage(OutgoingMessage)`, `sendButtons(OutgoingButtons)`, `sendTemplateButtons(OutgoingTemplateButtons)`, `sendListMessage(OutgoingListMessage)`, `sendContact(OutgoingContact)`, `sendFileByUpload(OutgoingFileByUpload)`, `sendFileByUrl(OutgoingFileByUrl)`, `uploadFile(File)`, `sendLocation(OutgoingLocation)`, `sendPoll(OutgoingPoll)` |
+| receiving | `receiveNotification()`, `deleteNotification(Integer)`, `downloadFile(MessageReq)` |
+
+Do not write Java SDK code for a REST method absent from this table. `NotificationMapper.get(String)`, `WebhookConsumer.start(WebhookHandler)`, `WebhookConsumer.stop()`, and `WebhookHandler.handle(Notification)` are also present SDK helpers.
diff --git a/skills/green-api-java-sdk/references/sending-and-files.md b/skills/green-api-java-sdk/references/sending-and-files.md
@@ -0,0 +1,17 @@
+# Sending and files
+
+Read each official page before implementation.
+
+| SDK call | Official page | SDK request fields | Body on success |
+|---|---|---|---|
+| `sending.sendMessage(OutgoingMessage)` | [SendMessage](https://green-api.com/en/docs/api/sending/SendMessage/) | inherited `chatId`, `quotedMessageId`; `message`, `linkPreview` | `SendMessageResp.idMessage` |
+| `sending.sendFileByUpload(OutgoingFileByUpload)` | [SendFileByUpload](https://green-api.com/en/docs/api/sending/SendFileByUpload/) | inherited `chatId`, `quotedMessageId`; `file`, `fileName`, `caption` | `SendFileByUploadResp.idMessage`, `urlFile` |
+| `sending.sendFileByUrl(OutgoingFileByUrl)` | [SendFileByUrl](https://green-api.com/en/docs/api/sending/SendFileByUrl/) | inherited `chatId`, `quotedMessageId`; `urlFile`, `fileName`, `caption` | `SendMessageResp.idMessage` |
+| `sending.uploadFile(File)` | [UploadFile](https://green-api.com/en/docs/api/sending/UploadFile/) | file argument | `UploadFileResp.urlFile` |
+| `sending.sendContact(OutgoingContact)` | [SendContact](https://green-api.com/en/docs/api/sending/SendContact/) | DTO fields | `SendMessageResp.idMessage` |
+| `sending.sendLocation(OutgoingLocation)` | [SendLocation](https://green-api.com/en/docs/api/sending/SendLocation/) | DTO fields | `SendMessageResp.idMessage` |
+| `sending.sendPoll(OutgoingPoll)` | [SendPoll](https://green-api.com/en/docs/api/sending/SendPoll/) | DTO fields | `SendMessageResp.idMessage` |
+
+The source also implements `sendButtons(OutgoingButtons)`, `sendTemplateButtons(OutgoingTemplateButtons)`, and `sendListMessage(OutgoingListMessage)`; source comments warn that each currently returns HTTP 403. Do not use them for a first working integration.
+
+Official constraints: SendMessage accepts emoji, has a 20,000-character maximum, and requires UTF-8 without BOM. Quote only within the target chat. For mailing or unreliable external storage, upload once with `uploadFile(File)` and pass returned `urlFile` to `sendFileByUrl`. Queue delivery rate follows the instance Message sending delay setting.
diff --git a/skills/green-api-java-sdk/references/verification.md b/skills/green-api-java-sdk/references/verification.md
@@ -0,0 +1,8 @@
+# Verification
+
+In a clean Maven project, add the dependency from SKILL.md and run:
+
+    grep -RInE 'sendMessage|sendFileByUpload|sendFileByUrl|uploadFile|receiveNotification|deleteNotification|setSetting|WebhookConsumer|NotificationMapper' ~/.m2/repository/com/green-api/whatsapp-api-client-java/0.1.8
+    mvn -q -DskipTests compile
+
+Before a live send, call `greenApi.account.getStateInstance()` and proceed only for the documented authorized state. Use a consented test chat, require 2xx and non-empty `SendMessageResp.idMessage`, and keep credentials in environment variables. A successful response queues the message; use notifications or journals for delivery confirmation.