Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): bring the SDK reference in line with the shipped clients

Yudhi Armyndharisbd9d9c06559e
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 73d8eb2bc..b1d138e98 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -76,11 +76,13 @@ const client = new OpenWAClient({
});
async function main() {
- // Start a session and bring the WhatsApp connection up.
- 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);
// Send a text message.
- 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!',
});
@@ -107,7 +109,7 @@ The constructor takes a single `OpenWAClientOptions` object. `baseUrl` and `apiK
| ---------------- | ------------------------ | -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `baseUrl` | `string` | yes | — | Base URL of the OpenWA API, e.g. `http://localhost:2785`. A trailing slash is trimmed; a path prefix (e.g. `https://host/v1`) is preserved. |
| `apiKey` | `string` | yes | — | API key sent as the `X-API-Key` header on every request. |
-| `timeoutMs` | `number` | no | `30000` | Per-request timeout in milliseconds. Overridable per call via `RequestOptions.timeoutMs` on the raw `request()` method. |
+| `timeoutMs` | `number` | no | `30000` | Per-request timeout in milliseconds; `0` or `Infinity` turns it off. Overridable per call via `RequestOptions.timeoutMs` on the raw `request()` method. |
| `defaultHeaders` | `Record<string, string>` | no | `{}` | Headers merged onto every request. The `Content-Type: application/json` and `X-API-Key` headers always take precedence. |
| `fetch` | `FetchLike` | no | `globalThis.fetch` | Injectable transport (the WHATWG `fetch` signature). Use this to wrap requests with retry/observability middleware, or to supply a `fetch` on runtimes that lack a global one. |
@@ -376,7 +378,7 @@ import {
} from '@rmyndharis/openwa';
try {
- await client.messages.sendText('my-session', {
+ await client.messages.sendText(sessionId, {
chatId: '[email protected]',
text: 'Hi!',
});
@@ -440,12 +442,13 @@ client = OpenWAClient(
api_key="owa_k1_…",
)
-# Create then start a session
-client.sessions.create({"name": "my-session"})
-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"])
# Send a text message
-result = client.messages.send_text("my-session", {
+result = client.messages.send_text(session["id"], {
"chatId": "[email protected]",
"text": "Hello from the OpenWA Python SDK!",
})
@@ -748,7 +751,7 @@ from openwa import (
client = OpenWAClient(base_url="http://localhost:2785", api_key="owa_k1_…")
try:
- client.messages.send_text("my-session", {
+ client.messages.send_text(session_id, {
"chatId": "[email protected]",
"text": "Hi!",
})
@@ -804,9 +807,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!',
]);
@@ -827,13 +833,14 @@ Two escape hatches sit on the client itself:
The constructor takes a single associative `$config` array:
-| Key | Type | Default | Description |
-| ---------------- | ------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `baseUrl` | `string` | — (**required**) | API base URL, e.g. `http://localhost:2785`. A trailing `/` is stripped; any path prefix (e.g. `/v1` behind a proxy) is preserved. |
-| `apiKey` | `string` | — (**required**) | Sent as the `X-API-Key` header on every request. |
-| `timeout` | `float` | `30.0` | Per-request timeout in seconds. |
-| `httpClient` | `?\GuzzleHttp\ClientInterface` | `null` | Inject a Guzzle client (e.g. one built on a `MockHandler`) for testing or middleware. When `null`, a default Guzzle client is created with the configured timeout. |
-| `defaultHeaders` | `array<string,string>` | `[]` | Extra headers applied on every request, **under** the SDK's auth/JSON headers (which always win). |
+| Key | Type | Default | Description |
+| ------------------- | ------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `baseUrl` | `string` | — (**required**) | API base URL, e.g. `http://localhost:2785`. A trailing `/` is stripped; any path prefix (e.g. `/v1` behind a proxy) is preserved. |
+| `apiKey` | `string` | — (**required**) | Sent as the `X-API-Key` header on every request. |
+| `timeout` | `float` | `30.0` | Per-request timeout in seconds. |
+| `httpClient` | `?\GuzzleHttp\ClientInterface` | `null` | Inject a Guzzle client (e.g. one built on a `MockHandler`) for testing or middleware. When `null`, a default Guzzle client is created with the configured timeout. |
+| `defaultHeaders` | `array<string,string>` | `[]` | Extra headers applied on every request, **under** the SDK's auth/JSON headers (which always win). |
+| `allowInsecureHttp` | `bool` | `false` | Skip the `error_log()` warning written for an `http://` `baseUrl` whose host is not localhost (e.g. a private Docker network or a TLS-terminating proxy). |
Missing `baseUrl` or `apiKey` throws `OpenWA\Exceptions\OpenWAException` from the constructor.
@@ -1090,7 +1097,7 @@ use OpenWA\Exceptions\OpenWATimeoutException;
use OpenWA\Exceptions\OpenWAApiException;
try {
- $result = $client->messages->sendText('my-session', [
+ $result = $client->messages->sendText($sessionId, [
'chatId' => '[email protected]',
'text' => 'Hello!',
]);
@@ -1111,7 +1118,7 @@ try {
- **Redirects are never followed.** Guzzle is configured with `allow_redirects => false`, so a `3xx` surfaces as an `OpenWAApiException` rather than being followed — the `X-API-Key` header is never re-sent to a redirect target.
- **Auth/JSON headers take precedence.** `defaultHeaders` are merged in first, then `X-API-Key`, `Content-Type: application/json`, and `Accept: application/json` are applied on top, so they can't be clobbered.
-- **Path segments are percent-encoded.** Ids (chat/message/group ids, session names) pass through `encodeSegment()`, which `rawurlencode`s the value but keeps the WhatsApp-id-safe characters `@`, `:`, and `+` readable — so a value containing `/`, `#`, or `?` cannot break out of its path position.
+- **Path segments are percent-encoded.** Ids (session/chat/message/group ids) pass through `encodeSegment()`, which `rawurlencode`s the value but keeps the WhatsApp-id-safe characters `@`, `:`, and `+` readable — so a value containing `/`, `#`, or `?` cannot break out of its path position.
- **Base-URL path prefix is preserved.** The base URL has its trailing `/` trimmed and requests are issued against an absolute `baseUrl . $path`; Guzzle's `base_uri` is intentionally unset, so a prefix like `/v1` behind a reverse proxy is retained.
- **Null query values are dropped.** Absent optional query parameters (`null`) are filtered out before the request, so they are never sent.
- **No automatic retries.** A failed request throws immediately; wrap calls in your own backoff if you need retries (notably for `429`). The injectable `httpClient` is the extension point for retry/observability middleware.