Spaces:
Runtime error
Runtime error
File size: 4,416 Bytes
46252cd | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | # OpenWA Java SDK
Official Java client for the [OpenWA](https://github.com/rmyndharis/OpenWA)
WhatsApp API Gateway.
Hand-written against the exact API surface (paths, DTOs, response shapes) and
unit-tested with a mock HTTP transport that asserts on the precise request URL,
method, and body — so contract drift is caught at test time. Synchronous,
Java 17+, one runtime dependency ([Gson](https://github.com/google/gson)).
## Install
**Maven**
```xml
<dependency>
<groupId>com.rmyndharis</groupId>
<artifactId>openwa</artifactId>
<version>0.1.1</version>
</dependency>
```
**Gradle**
```groovy
implementation 'com.rmyndharis:openwa:0.1.1'
```
## Quickstart
```java
import com.rmyndharis.openwa.OpenWAClient;
import com.rmyndharis.openwa.model.MessageResponse;
import com.rmyndharis.openwa.model.SendTextRequest;
OpenWAClient client = new OpenWAClient("http://localhost:2785", "owa_k1_…");
client.sessions.start("my-session");
MessageResponse result = client.messages.sendText("my-session",
SendTextRequest.builder()
.chatId("628123456789@c.us")
.text("Hello from the OpenWA Java SDK!")
.build());
System.out.println(result.messageId());
```
For full control over configuration (timeout, default headers, a custom
transport), build a `ClientConfig`:
```java
import com.rmyndharis.openwa.ClientConfig;
import java.time.Duration;
OpenWAClient client = new OpenWAClient(ClientConfig.builder()
.baseUrl("https://wa.example.com")
.apiKey("owa_k1_…")
.timeout(Duration.ofSeconds(15))
.build());
```
## Resources
The client exposes the same fluent resource surface as the JavaScript, Python,
and PHP SDKs:
`sessions` · `messages` · `contacts` · `groups` · `webhooks` · `chats` ·
`labels` · `channels` · `catalog` · `status` · `templates` · `health` · `search` ·
`profile` · `calls`,
plus `client.auth()`.
Operator-only modules (`docker`, `metrics`, `infra`, `plugins`, `mcp`) are
intentionally not exposed; all user-facing resources are.
## Error handling
Errors are a typed, unchecked hierarchy — branch with `instanceof` or on
`.status()`:
```java
import com.rmyndharis.openwa.errors.OpenWAConflictError;
import com.rmyndharis.openwa.errors.OpenWANotFoundError;
try {
client.messages.sendText("my-session", body);
} catch (OpenWAConflictError e) {
// 409 — engine not ready
} catch (OpenWANotFoundError e) {
// 404 — session or chat not found
}
```
| Class | HTTP | Meaning |
| ---------------------------- | ---- | ---------------------------------------- |
| `OpenWAAuthError` | 401 | Missing or invalid API key |
| `OpenWAForbiddenError` | 403 | API key role insufficient |
| `OpenWANotFoundError` | 404 | Resource not found |
| `OpenWAConflictError` | 409 | Engine not ready |
| `OpenWARateLimitError` | 429 | Rate limited |
| `OpenWANotImplementedError` | 501 | Active engine does not support the call |
| `OpenWAApiError` | — | Any other non-2xx (carries `.status()`) |
| `OpenWATimeoutError` | — | Request exceeded the configured timeout |
All extend `OpenWAError` (a `RuntimeException`).
## Reliability & security
- **Use HTTPS in production.** The API key is sent as `X-API-Key` on every
request and is bearer-equivalent — never send it over plaintext `http://`
outside local development.
- **No automatic retries.** A failed request throws immediately; wrap calls in
your own backoff if you need retries (especially for `429`). Inject a custom
`HttpTransport` for retry or observability middleware.
- **Redirects are never followed.** A `3xx` surfaces as an `OpenWAApiError`
rather than being followed, so the API key is never re-sent to a redirect
target.
- **Default per-request timeout** is 30 s (configurable). Path segments (chat /
message ids) are percent-encoded; a base-URL path prefix (e.g. behind a proxy
at `/v1`) is preserved.
## Development
```bash
cd sdk/java
mvn -B verify # compile + run the full test suite
```
Tests inject a recording `HttpTransport` and assert on the exact path — so the
regression that would ship a broken `messages/text` path (the real path is
`messages/send-text`) can never recur silently.
|