Skip to Content
Wazend

Sessions

Control WhatsApp sessions in Wazend: lifecycle, states, QR, pairing code and more.

A session represents a WhatsApp account (phone number) connected to Wazend, which you can use to send and receive messages.

Lifecycle

Before you can send or receive messages, you must start a session and authenticate it using a QR code or a pairing code.

Session states

  • STOPPED — the session is stopped.
  • STARTING — the session is starting.
  • SCAN_QR_CODE — scanning the QR or logging in with a phone number is required. Every time this state is emitted, the QR changes and you must get the updated QR.
  • PASSKEY_REQUIRED — WhatsApp requests a passkey (WebAuthn) to complete the pairing.
  • PASSKEY_CONFIRMATION_REQUIRED — the user must verify a code before completing the pairing.
  • WORKING — the session works and is ready to use.
  • FAILED — the session failed due to an error. It usually means authorization is required again or the device was disconnected from the account.

Session in FAILED state

In the FAILED state, try to restart the session. If it doesn't work, log out and start it again.

Update session

Update a session with a complete new configuration.

PUT /api/sessions/{session}
Body
{
  "config": {
    "webhooks": [
      {
        "url": "https://tu-servidor.com/webhook",
        "events": ["message"]
      }
    ]
  }
}

The session restarts

If the session is not in the STOPPED state, it will stop and start with the new configuration.

Start session

POST /api/sessions/{session}/start

Info

Idempotent operation: you can call it several times; it only starts if it isn't running.

Stop session

POST /api/sessions/{session}/stop

Info

Stopping doesn't log out or delete anything. Idempotent operation.

Restart session

POST /api/sessions/{session}/restart

Warning

If the session is already running (not in STOPPED), it will stop and start again.

Log out

POST /api/sessions/{session}/logout

Warning

Logging out deletes the authentication information and data, but keeps the configuration. If the session is in WORKING, it also removes the device from the Linked devices list.

List sessions

GET /api/sessions

Get session

GET /api/sessions/{session}

Get QR

Get the QR code to authenticate the session by scanning with the WhatsApp app.

GET /api/{session}/auth/qr?format=raw

Use format=raw to get the code string or format=image for the PNG.

Pairing code

Get a numeric code to link the session from the WhatsApp app.

POST /api/{session}/auth/request-code

Get profile information (Me)

GET /api/sessions/{session}/me
Response
{
  "id": "5215551234567@c.us",
  "pushName": "Mi Nombre",
  "reachoutTimelock": null,
  "messageCapping": null
}

Passkey

In some pairings, WhatsApp requests a passkey (WebAuthn). The PASSKEY_REQUIRED and PASSKEY_CONFIRMATION_REQUIRED states indicate that the user must complete this step to finish the pairing.

Events

The session emits events you can receive through Events or WebSockets. The main event is session.status; see the payload details on the Events page.