Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): address sessions by the id create() returns in examples

Yudhi Armyndharisf3288d34e1ef
diff --git a/sdk/README.md b/sdk/README.md
index 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.
```java
import 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.md
index 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.go
index 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.go
index 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.md
index e0409e383..8f91001e8 100644
--- a/sdk/java/README.md
+++ b/sdk/java/README.md
@@ -30,14 +30,19 @@ implementation 'com.rmyndharis:openwa:0.5.0'
```java
import 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.java
index 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.md
index 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.ts
index 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.ts
index 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.md
index 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.php
index 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.md
index 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
```python
with 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 none
is 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__.py
index 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.py
index 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!",
})