Request an 8-char pairing code to link via phone number (alternative to QR)
POST/api/sessions/:sessionId/pairing-code
On the whatsapp-web.js engine, only request a code for a number you are prepared to re-link. A request for a number that already has a linked session has been observed to end with WhatsApp revoking that device: the linked session logs out, its credentials are deleted and it falls back to qr_ready. On that engine a number that is the stored phone of another session of this gateway (the Brazilian, Mexican and Argentine mobile spellings of one number count as the same) is refused with 409 and WhatsApp is not asked; the gateway cannot see a link made on another gateway or only on the phone. Baileys was not affected in the same tests and accepts the request: its sessions are companion devices and may share a number. Link by QR when a session of that number must stay up.
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 409
- 503
Pairing code generated
Session not started or already authenticated
The API key is missing, unknown, revoked, or expired
The API key's role, session or chat scope, or IP allow-list does not allow this operation
Session not found
The session is not waiting to be linked: the engine is still connecting, or reconnecting after a drop, so the request never reached WhatsApp. Wait for status to read qr_ready and retry. Once a code has been accepted the session moves through authenticating and initializing to ready and answers this until then; wait for ready in that case. A session that reads ready is already linked and answers 400 instead. One window answers this while the session still reads qr_ready: on the Baileys engine a socket that has begun closing stops accepting a pairing request before the status catches up, which on a silently dropped connection takes until the WebSocket's close timeout (30 s); retry, and the status follows shortly. On whatsapp-web.js also answered, with nothing sent to WhatsApp, when the requested number is the stored phone of another session of this gateway: delete that session, or log it out while it runs, first.
The pairing code could not be generated: the gateway stopped waiting after its attempt budget, usually because WhatsApp Web kept reloading its QR page. The condition is transient and the request is worth retrying; the last attempt's reason is carried in the message. An attempt that timed out may still have reached WhatsApp, and a retry starts the linking flow again, with the same risk of unlinking an already-linked device that this route carries generally. The Baileys engine does not answer this, having no page to reload.