Free, Open Source, Self-Hosted WhatsApp API Gateway
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.
On the whatsapp-web.js engine, request a code only for a number you are prepared to re-link. A pairing request for a number that already has a linked session has been observed to end with WhatsApp revoking that device: within about a minute the linked session logs
WhatsApp unlinked this device (LOGOUT), its stored credentials are deleted, and it returns toqr_readywith no phone. The request runs inside the shared WhatsApp Web page and resets its linking mode before it asks for a code, so the blast radius is the account, not the session. The gateway answers409for a number that is the stored phone of another of its sessions, but it cannot see a link made on another gateway or only on the phone. Baileys has no such page, was not affected in the same tests and is not refused. If a session of that number must stay up, link the new one by QR.
Flow
[Create Session]
│
▼
[Start Session]
│
▼
[Wait for status qr_ready]
│
▼
[Request Pairing Code]
│
▼
[Enter Code in WhatsApp]
│
▼
[Session Connected]
1. Create a Session
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
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, and the engine needs a moment to connect after start returns. Poll GET /api/sessions/{sessionId} until status is qr_ready: that is the point the engine can accept a pairing request. Requesting a code before that returns 409. Treat qr_ready as the signal to try, not a guarantee: on Baileys the socket can already be closing while the status has not caught up, so a 409 is still possible for a few seconds and is worth one retry.
3. Request a Pairing Code
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
{
"pairingCode": "ABCD1234",
"status": "qr_ready"
}
4. Enter the Code in WhatsApp
On the phone that owns the WhatsApp account:
- Open WhatsApp.
- Go to Settings.
- Open Linked Devices.
- Choose Link with phone number.
- 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, callPOST /api/sessions/{sessionId}/startfirst. - If OpenWA returns
Session is already authenticated, the account is already linked and no pairing code is needed. On whatsapp-web.js a request whose number is the stored phone of a DIFFERENT session of this gateway answers409: log that session out or delete it first. Nothing refuses a number linked to a device outside this gateway, or only on the phone, and on whatsapp-web.js that is the request that can unlink it; see the warning at the top. - If OpenWA returns 409
Session is not waiting to be linked, the engine is still connecting (or reconnecting after a drop). Wait forstatusto readqr_readyand request again. After a code was accepted the same 409 is answered until the session isready; do not request another code then. On Baileys the same 409 can also answer whilestatusalready readsqr_ready, for as long as the WebSocket takes to finish closing (up to 30 s on a silently dropped connection); retry rather than treating it as a bad state. - If the phone number is rejected, send digits only in international format, without
+, spaces, or punctuation. - On the Baileys engine, if pairing keeps failing with a generic "check the phone number" rejection even though the number is correct and in the right format, WhatsApp is refusing the linked-device identity for that account rather than the number itself. The device name is carried into the pairing request, and some accounts reject a non-standard one. The default is
Ubuntu; ifBAILEYS_BROWSER_NAMEwas set to a custom brand, set it back toUbuntu(or another standard OS name), restart OpenWA itself (the name is read at boot, so stopping and starting the session is not enough), and request a fresh code. whatsapp-web.js does not send this device name and never readsBAILEYS_BROWSER_NAME, so the variable has no effect there. - If you want to create a brand-new WhatsApp account programmatically, that is outside OpenWA's scope. OpenWA only links an existing WhatsApp account.