Start a session and initialize WhatsApp connection
POST/api/sessions/:sessionId/start
Start a session and initialize WhatsApp connection
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 503
- 504
Session started
Session already started or already starting, or this node is at its MAX_CONCURRENT_SESSIONS cap (Maximum concurrent sessions reached (N)), answered only after the 404 and the 409 for a session running on another node; a start refused at the cap launches nothing and leaves a stop in place.
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
A credential teardown for the same session name is still in flight (e.g. a prior logout that owns destructive cleanup). Retryable — the body carries code: SESSION_NAME_TEARDOWN_PENDING; wait for it to settle and retry. No destructive side effect runs before this refusal. Also returned when another node currently holds this session's engine: only the owner may start it, and the claim is refused before any engine is launched, so no second connection to the account is opened. Also returned, with no code, when a stop, a logout or force-kill that found a running engine, or a data import (stopOrphans) of this session began or finished while the start was waiting, or a delete of it was still running: the start yields and launches nothing. After a stop or force-kill, a new POST /start clears it and starts the session; after a delete, or an import that removed the session, the retry answers 404.
The gateway is shutting down, the session could not be checked (the database could not serve the read) or claimed for this node (nothing was launched), or the engine's browser or socket connection died during launch and the one automatic retry failed too (no engine is left running); the start can be retried.
The engine did not finish starting within its timeout (WhatsApp Web or the network unreachable, a stalled browser or resource limit, or, on whatsapp-web.js, an unreachable proxyUrl or the auth timeout); the engine is torn down and the start can be retried.