Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk): address sessions by the id create() returns in examples
Yudhi Armyndharisf3288d34e1ef
diff --git a/sdk/README.md b/sdk/README.mdindex 47c5fde32..30b93a0ce 100644--- a/sdk/README.md+++ b/sdk/README.md@@ -61,6 +61,11 @@ All five SDKs expose the same fluent resource surface:> documented by hand in `docs/06-api-specification.md`, and the docs-contract> gate names `POST /mcp` as the one heading allowed outside the contract.+Every example below addresses a session by its id: the UUID that+`sessions.create()` returns, not the name passed to it. Create a session once (a+second `create` with the same name answers `409`); afterwards, find its id with+`sessions.list` filtered by `name`.+## JavaScript / TypeScript```bash@@ -75,8 +80,9 @@ const client = new OpenWAClient({apiKey: 'owa_k1_…',});-await client.sessions.start('my-session');-const result = await client.messages.sendText('my-session', {+const session = await client.sessions.create({ name: 'my-session' });+await client.sessions.start(session.id);+const result = await client.messages.sendText(session.id, {chatId: '[email protected]',text: 'Hello from the OpenWA SDK!',});@@ -113,8 +119,9 @@ client = OpenWAClient(api_key="owa_k1_…",)-client.sessions.start("my-session")-result = client.messages.send_text("my-session", {+session = client.sessions.create({"name": "my-session"})+client.sessions.start(session["id"])+result = client.messages.send_text(session["id"], {"chatId": "[email protected]","text": "Hello from the OpenWA Python SDK!",})@@ -139,8 +146,9 @@ $client = new Client(['apiKey' => 'owa_k1_…',]);-$client->sessions->start('my-session');-$result = $client->messages->sendText('my-session', [+$session = $client->sessions->create(['name' => 'my-session']);+$client->sessions->start($session['id']);+$result = $client->messages->sendText($session['id'], ['chatId' => '[email protected]','text' => 'Hello from the OpenWA PHP SDK!',]);@@ -162,13 +170,16 @@ handler is a `MockHandler` — no global state, no network.```javaimport com.rmyndharis.openwa.OpenWAClient;+import com.rmyndharis.openwa.model.CreateSessionRequest;import com.rmyndharis.openwa.model.MessageResponse;import com.rmyndharis.openwa.model.SendTextRequest;+import com.rmyndharis.openwa.model.SessionResponse;OpenWAClient client = new OpenWAClient("http://localhost:2785", "owa_k1_…");-client.sessions.start("my-session");-MessageResponse result = client.messages.sendText("my-session",+SessionResponse session = client.sessions.create(CreateSessionRequest.builder().name("my-session").build());+client.sessions.start(session.id());+MessageResponse result = client.messages.sendText(session.id(),SendTextRequest.builder().chatId("[email protected]").text("Hello from the OpenWA Java SDK!")@@ -202,8 +213,12 @@ if err != nil {}ctx := context.Background()-client.Sessions.Start(ctx, "my-session")-res, err := client.Messages.SendText(ctx, "my-session", openwa.SendTextRequest{+session, err := client.Sessions.Create(ctx, openwa.CreateSessionRequest{Name: "my-session"})+if err != nil {+ log.Fatal(err)+}+client.Sessions.Start(ctx, session.ID)+res, err := client.Messages.SendText(ctx, session.ID, openwa.SendTextRequest{ChatID: "[email protected]",Text: "Hello from the OpenWA Go SDK!",})diff --git a/sdk/go/README.md b/sdk/go/README.mdindex 0dcf52a42..e5935b30e 100644--- a/sdk/go/README.md+++ b/sdk/go/README.md@@ -29,11 +29,17 @@ func main() {}ctx := context.Background()- if _, err := client.Sessions.Start(ctx, "my-session"); err != nil {+ // Sessions are addressed by the UUID that Create returns, not by name. Create a+ // session once; afterwards, find its ID with Sessions.List and a Name filter.+ session, err := client.Sessions.Create(ctx, openwa.CreateSessionRequest{Name: "my-session"})+ if err != nil {+ log.Fatal(err)+ }+ if _, err := client.Sessions.Start(ctx, session.ID); err != nil {log.Fatal(err)}- res, err := client.Messages.SendText(ctx, "my-session", openwa.SendTextRequest{+ res, err := client.Messages.SendText(ctx, session.ID, openwa.SendTextRequest{ChatID: "[email protected]",Text: "Hello from the OpenWA Go SDK!",})@@ -80,7 +86,7 @@ func main() {## Typed errors```go-res, err := client.Messages.SendText(ctx, "my-session", req)+res, err := client.Messages.SendText(ctx, sessionID, req)switch {case errors.Is(err, openwa.ErrConflict):// 409 — engine not ready; retry once the session is "ready".diff --git a/sdk/go/client.go b/sdk/go/client.goindex 13141e91f..d41d8feac 100644--- a/sdk/go/client.go+++ b/sdk/go/client.go@@ -9,10 +9,15 @@// }//// ctx := context.Background()-// if _, err := client.Sessions.Start(ctx, "my-session"); err != nil {+// // Sessions are addressed by the UUID that Create returns, not by name.+// session, err := client.Sessions.Create(ctx, openwa.CreateSessionRequest{Name: "my-session"})+// if err != nil {+// log.Fatal(err)+// }+// if _, err := client.Sessions.Start(ctx, session.ID); err != nil {// log.Fatal(err)// }-// res, err := client.Messages.SendText(ctx, "my-session", openwa.SendTextRequest{+// res, err := client.Messages.SendText(ctx, session.ID, openwa.SendTextRequest{// ChatID: "[email protected]",// Text: "Hello from the OpenWA Go SDK!",// })diff --git a/sdk/go/example_test.go b/sdk/go/example_test.goindex c60283474..52c4e4f5d 100644--- a/sdk/go/example_test.go+++ b/sdk/go/example_test.go@@ -17,11 +17,17 @@ func ExampleNew() {}ctx := context.Background()- if _, err := client.Sessions.Start(ctx, "my-session"); err != nil {+ // Sessions are addressed by the UUID that Create returns, not by name. Create a+ // session once; afterwards, find its ID with Sessions.List and a Name filter.+ session, err := client.Sessions.Create(ctx, openwa.CreateSessionRequest{Name: "my-session"})+ if err != nil {+ log.Fatal(err)+ }+ if _, err := client.Sessions.Start(ctx, session.ID); err != nil {log.Fatal(err)}- res, err := client.Messages.SendText(ctx, "my-session", openwa.SendTextRequest{+ res, err := client.Messages.SendText(ctx, session.ID, openwa.SendTextRequest{ChatID: "[email protected]",Text: "Hello from the OpenWA Go SDK!",})@@ -33,8 +39,9 @@ func ExampleNew() {func ExampleClient_typedErrors() {client, _ := openwa.New("http://localhost:2785", "owa_k1_…")+ sessionID := "…" // the UUID that Sessions.Create returned, not the session name- _, err := client.Messages.SendText(context.Background(), "my-session", openwa.SendTextRequest{+ _, err := client.Messages.SendText(context.Background(), sessionID, openwa.SendTextRequest{ChatID: "[email protected]",Text: "hi",})@@ -63,11 +70,12 @@ func ExampleWithRetry() {func ExampleClient_webhookEvents() {client, _ := openwa.New("http://localhost:2785", "owa_k1_…")+ sessionID := "…" // the UUID that Sessions.Create returned, not the session name// Subscribe to the group and call events with the Event* constants — they// are the exact wire values, so a typo is a compile error, not a silent// no-delivery.- _, err := client.Webhooks.Create(context.Background(), "my-session", openwa.CreateWebhookRequest{+ _, err := client.Webhooks.Create(context.Background(), sessionID, openwa.CreateWebhookRequest{URL: "https://example.com/hook",Events: []string{openwa.EventGroupJoin,diff --git a/sdk/java/README.md b/sdk/java/README.mdindex e0409e383..8f91001e8 100644--- a/sdk/java/README.md+++ b/sdk/java/README.md@@ -30,14 +30,19 @@ implementation 'com.rmyndharis:openwa:0.5.0'```javaimport com.rmyndharis.openwa.OpenWAClient;+import com.rmyndharis.openwa.model.CreateSessionRequest;import com.rmyndharis.openwa.model.MessageResponse;import com.rmyndharis.openwa.model.SendTextRequest;+import com.rmyndharis.openwa.model.SessionResponse;OpenWAClient client = new OpenWAClient("http://localhost:2785", "owa_k1_…");-client.sessions.start("my-session");+// Sessions are addressed by the UUID that create() returns, not by name. Create a session once;+// afterwards, find its id with client.sessions.list(ListSessionsQuery.builder().name("my-session").build()).+SessionResponse session = client.sessions.create(CreateSessionRequest.builder().name("my-session").build());+client.sessions.start(session.id());-MessageResponse result = client.messages.sendText("my-session",+MessageResponse result = client.messages.sendText(session.id(),SendTextRequest.builder().chatId("[email protected]").text("Hello from the OpenWA Java SDK!")@@ -83,7 +88,7 @@ import com.rmyndharis.openwa.errors.OpenWAConflictError;import com.rmyndharis.openwa.errors.OpenWANotFoundError;try {- client.messages.sendText("my-session", body);+ client.messages.sendText(sessionId, body);} catch (OpenWAConflictError e) {// 409 — engine not ready} catch (OpenWANotFoundError e) {diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.java b/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.javaindex ad21f26dc..f1063a1b5 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.java@@ -45,8 +45,10 @@ import java.util.Map;** <pre>{@code* OpenWAClient client = new OpenWAClient("http://localhost:2785", "owa_k1_…");- * client.sessions.start("my-session");- * client.messages.sendText("my-session",+ * // Sessions are addressed by the UUID that create() returns, not by name.+ * SessionResponse session = client.sessions.create(CreateSessionRequest.builder().name("my-session").build());+ * client.sessions.start(session.id());+ * client.messages.sendText(session.id(),* SendTextRequest.builder().chatId("[email protected]").text("Hello!").build());* }</pre>*/diff --git a/sdk/javascript/README.md b/sdk/javascript/README.mdindex dc6e615fa..8743a162b 100644--- a/sdk/javascript/README.md+++ b/sdk/javascript/README.md@@ -22,9 +22,12 @@ const client = new OpenWAClient({apiKey: 'owa_k1_…',});-await client.sessions.start('my-session');+// Sessions are addressed by the UUID that create() returns, not by name. Create a session once;+// afterwards, find its id with client.sessions.list({ name: 'my-session' }).+const session = await client.sessions.create({ name: 'my-session' });+await client.sessions.start(session.id);-const result = await client.messages.sendText('my-session', {+const result = await client.messages.sendText(session.id, {chatId: '[email protected]',text: 'Hello from the OpenWA SDK!',});diff --git a/sdk/javascript/src/client.ts b/sdk/javascript/src/client.tsindex 2d62694c2..bf81dd72a 100644--- a/sdk/javascript/src/client.ts+++ b/sdk/javascript/src/client.ts@@ -13,8 +13,10 @@* apiKey: 'owa_k1_…',* });*- * await client.sessions.start('my-session');- * await client.messages.sendText('my-session', {+ * // Sessions are addressed by the UUID that create() returns, not by name.+ * const session = await client.sessions.create({ name: 'my-session' });+ * await client.sessions.start(session.id);+ * await client.messages.sendText(session.id, {* chatId: '[email protected]',* text: 'Hello from the OpenWA SDK!',* });diff --git a/sdk/javascript/src/index.ts b/sdk/javascript/src/index.tsindex dd0a1829b..063a3ba05 100644--- a/sdk/javascript/src/index.ts+++ b/sdk/javascript/src/index.ts@@ -12,8 +12,10 @@* apiKey: 'owa_k1_…',* });*- * await client.sessions.start('my-session');- * const result = await client.messages.sendText('my-session', {+ * // Sessions are addressed by the UUID that create() returns, not by name.+ * const session = await client.sessions.create({ name: 'my-session' });+ * await client.sessions.start(session.id);+ * const result = await client.messages.sendText(session.id, {* chatId: '[email protected]',* text: 'Hello from the OpenWA SDK!',* });diff --git a/sdk/php/README.md b/sdk/php/README.mdindex 4ae557ab2..f72746f8b 100644--- a/sdk/php/README.md+++ b/sdk/php/README.md@@ -25,9 +25,12 @@ $client = new Client(['apiKey' => 'owa_k1_…',]);-$client->sessions->start('my-session');+// Sessions are addressed by the UUID that create() returns, not by name. Create a session once;+// afterwards, find its id with $client->sessions->list(['name' => 'my-session']).+$session = $client->sessions->create(['name' => 'my-session']);+$client->sessions->start($session['id']);-$result = $client->messages->sendText('my-session', [+$result = $client->messages->sendText($session['id'], ['chatId' => '[email protected]','text' => 'Hello from the OpenWA PHP SDK!',]);diff --git a/sdk/php/src/Client.php b/sdk/php/src/Client.phpindex 8c93a2e4b..18e171d0f 100644--- a/sdk/php/src/Client.php+++ b/sdk/php/src/Client.php@@ -39,8 +39,10 @@ use OpenWA\Resources\WebhooksResource;* 'apiKey' => 'owa_k1_…',* ]);*- * $client->sessions->start('my-session');- * $result = $client->messages->sendText('my-session', [+ * // Sessions are addressed by the UUID that create() returns, not by name.+ * $session = $client->sessions->create(['name' => 'my-session']);+ * $client->sessions->start($session['id']);+ * $result = $client->messages->sendText($session['id'], [* 'chatId' => '[email protected]',* 'text' => 'Hello from the OpenWA PHP SDK!',* ]);diff --git a/sdk/python/README.md b/sdk/python/README.mdindex 60c238289..90d0019ea 100644--- a/sdk/python/README.md+++ b/sdk/python/README.md@@ -22,9 +22,12 @@ client = OpenWAClient(api_key="owa_k1_…",)-client.sessions.start("my-session")+# Sessions are addressed by the UUID that create() returns, not by name. Create a session once;+# afterwards, find its id with client.sessions.list({"name": "my-session"}).+session = client.sessions.create({"name": "my-session"})+client.sessions.start(session["id"])-result = client.messages.send_text("my-session", {+result = client.messages.send_text(session["id"], {"chatId": "[email protected]","text": "Hello from the OpenWA Python SDK!",})@@ -35,7 +38,7 @@ The client is also a context manager (it closes the underlying connection pool o```pythonwith OpenWAClient(base_url="…", api_key="…") as client:- client.messages.send_text("my-session", {"chatId": "…@c.us", "text": "hi"})+ client.messages.send_text(session_id, {"chatId": "…@c.us", "text": "hi"})```For tests, pass an httpx transport — no global monkey-patching required:@@ -54,7 +57,7 @@ The active search provider (built-in DB full-text, or a plugin) answers; if noneis configured the server returns 501.```python-res = client.search.search({"q": "invoice", "sessionId": "my-session", "limit": 20})+res = client.search.search({"q": "invoice", "sessionId": session_id, "limit": 20})for hit in res["hits"]:print(hit["snippet"], hit["score"])```diff --git a/sdk/python/openwa/__init__.py b/sdk/python/openwa/__init__.pyindex 90141dd7a..b41e25bdf 100644--- a/sdk/python/openwa/__init__.py+++ b/sdk/python/openwa/__init__.py@@ -12,8 +12,10 @@ Example usage::api_key="owa_k1_…",)- client.sessions.start("my-session")- result = client.messages.send_text("my-session", {+ # Sessions are addressed by the UUID that create() returns, not by name.+ session = client.sessions.create({"name": "my-session"})+ client.sessions.start(session["id"])+ result = client.messages.send_text(session["id"], {"chatId": "[email protected]","text": "Hello from the OpenWA Python SDK!",})diff --git a/sdk/python/openwa/client.py b/sdk/python/openwa/client.pyindex b1e3083c5..4f0141e85 100644--- a/sdk/python/openwa/client.py+++ b/sdk/python/openwa/client.py@@ -11,8 +11,10 @@ transport) and exposes domain resources as properties::api_key="owa_k1_…",)- client.sessions.start("my-session")- client.messages.send_text("my-session", {+ # Sessions are addressed by the UUID that create() returns, not by name.+ session = client.sessions.create({"name": "my-session"})+ client.sessions.start(session["id"])+ client.messages.send_text(session["id"], {"chatId": "[email protected]","text": "Hello from the OpenWA SDK!",})