From 07fa46dbd84ce473a47ab7c8b8d3027347d4e48e Mon Sep 17 00:00:00 2001
From: hsnyvsh <60756171+hsnyvsh@users.noreply.github.com>
Date: Fri, 19 Jun 2026 12:42:36 +0200
Subject: [PATCH 1/2] docs: add phone-number pairing example

---
 docs/examples/session-phone-number-pairing.md | 96 +++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 docs/examples/session-phone-number-pairing.md

diff --git a/docs/examples/session-phone-number-pairing.md b/docs/examples/session-phone-number-pairing.md
new file mode 100644
index 00000000..1c79b0bb
--- /dev/null
+++ b/docs/examples/session-phone-number-pairing.md
@@ -0,0 +1,96 @@
+# Session Phone-Number Pairing
+
+OpenWA supports linking an existing WhatsApp account to a session by phone number as an alternative to scanning a QR code.
+
+This flow returns an 8-character pairing code that the user enters in WhatsApp on their phone.
+
+> This does **not** create or register a new WhatsApp account. It only links an existing WhatsApp account as a companion device for an OpenWA session.
+
+## Flow
+
+```
+[Create Session]
+      │
+      ▼
+[Start Session]
+      │
+      ▼
+[Request Pairing Code]
+      │
+      ▼
+[Enter Code in WhatsApp]
+      │
+      ▼
+[Session Connected]
+```
+
+## 1. Create a Session
+
+```bash
+curl -X POST http://localhost:2785/api/sessions \
+  -H "X-API-Key: $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "support-bot"
+  }'
+```
+
+Save the returned session `id`.
+
+## 2. Start the Session
+
+```bash
+curl -X POST http://localhost:2785/api/sessions/{sessionId}/start \
+  -H "X-API-Key: $API_KEY"
+```
+
+The session must be started before requesting a pairing code.
+
+## 3. Request a Pairing Code
+
+```bash
+curl -X POST http://localhost:2785/api/sessions/{sessionId}/pairing-code \
+  -H "X-API-Key: $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "phoneNumber": "628123456789"
+  }'
+```
+
+`phoneNumber` must be digits only in international format: country code + number, without `+`, spaces, or dashes.
+
+Example values:
+
+| Country | Example |
+| ------- | ------- |
+| Indonesia | `628123456789` |
+| Spain | `34612345678` |
+| United States | `14155552671` |
+
+## Response
+
+```json
+{
+  "pairingCode": "ABCD1234",
+  "status": "qr_ready"
+}
+```
+
+## 4. Enter the Code in WhatsApp
+
+On the phone that owns the WhatsApp account:
+
+1. Open WhatsApp.
+2. Go to **Settings**.
+3. Open **Linked Devices**.
+4. Choose **Link with phone number**.
+5. Enter the pairing code returned by OpenWA.
+
+After the code is accepted, the OpenWA session should move to a connected/ready state.
+
+## Troubleshooting
+
+- If OpenWA returns `Session is not started`, call `POST /api/sessions/{sessionId}/start` first.
+- If OpenWA returns `Session is already authenticated`, the account is already linked and no pairing code is needed.
+- If the phone number is rejected, send digits only in international format, without `+`, spaces, or punctuation.
+- If you want to create a brand-new WhatsApp account programmatically, that is outside OpenWA's scope. OpenWA only links an existing WhatsApp account.

From b222abc9bef129363c875748782d36afaeaf4c2b Mon Sep 17 00:00:00 2001
From: hsnyvsh <60756171+hsnyvsh@users.noreply.github.com>
Date: Fri, 19 Jun 2026 12:43:11 +0200
Subject: [PATCH 2/2] docs: link phone-number pairing example

---
 docs/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/README.md b/docs/README.md
index 973acd36..e14bf568 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -61,6 +61,7 @@
 
 | Example | Description |
 | ------- | ----------- |
+| [Session Phone-Number Pairing](./examples/session-phone-number-pairing.md) | Link an existing WhatsApp account by phone number instead of scanning QR |
 | [Webhook Signature Verification](./examples/webhook-signature-verification.md) | Verify signed OpenWA webhook deliveries in Node.js and Python |
 | [n8n Appointment Booking Workflow](./examples/n8n-appointment-booking.md) | Build an appointment-booking flow with OpenWA and n8n |