From 31f506edc07ad42ae9a155fc8e6ae33f954b6ec1 Mon Sep 17 00:00:00 2001 From: Vadim Savilov Date: Mon, 20 Jul 2026 09:23:10 +0500 Subject: [PATCH] =?UTF-8?q?feature/SDK-72:=20=D0=9E=D0=BF=D0=B8=D1=81?= =?UTF-8?q?=D0=B0=D1=82=D1=8C=20=D1=81=D0=BA=D0=B8=D0=BB=D1=8B=20=D0=B4?= =?UTF-8?q?=D0=BB=D1=8F=20SDK-=D1=88=D0=B5=D0=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/green-api-java-sdk/SKILL.md | 58 +++++++++++++++++++ .../references/receiving-and-webhooks.md | 11 ++++ .../references/sdk-inventory.md | 16 +++++ .../references/sending-and-files.md | 17 ++++++ .../references/verification.md | 8 +++ 5 files changed, 110 insertions(+) create mode 100644 skills/green-api-java-sdk/SKILL.md create mode 100644 skills/green-api-java-sdk/references/receiving-and-webhooks.md create mode 100644 skills/green-api-java-sdk/references/sdk-inventory.md create mode 100644 skills/green-api-java-sdk/references/sending-and-files.md create mode 100644 skills/green-api-java-sdk/references/verification.md diff --git a/skills/green-api-java-sdk/SKILL.md b/skills/green-api-java-sdk/SKILL.md new file mode 100644 index 0000000..aa8409c --- /dev/null +++ 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 @c.us; groups use @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 new file mode 100644 index 0000000..00d84ec --- /dev/null +++ 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`; 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` | + +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 new file mode 100644 index 0000000..2d1b8bc --- /dev/null +++ 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 new file mode 100644 index 0000000..b10f172 --- /dev/null +++ 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 new file mode 100644 index 0000000..c962cf8 --- /dev/null +++ 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.