🖥️ Sessions

Endpoints

See the list of engines that support the features ->.

Start

In order to start a new session - call POST /api/sessions/start

{
  "name": "default"
}

Configure webhooks

You can configure webhooks for a session:

{
  "name": "default",
  "config": {
    "webhooks": [
      {
        "url": "https://httpbin.org/post",
        "events": [
          "message"
        ]
      }
    ]
  }
}

Read more about available options on Webhooks page ->

The configuration is saved and will be applied if the docker container restarts, and you set WHATSAPP_RESTART_ALL_SESSIONS environment variables. Read more about it in Autostart section.

Configure proxy

You can configure proxy for a session by setting config.proxy fields when you POST /api/sessions/start:

  • server - proxy server address, without http:// or https:// prefixes
  • username and password - set this if the proxy requires authentication

No authentication

{
  "name": "default",
  "config": {
    "proxy": {
      "server": "localhost:3128"
    }
  }
}

Proxy with authentication

{
  "name": "default",
  "config": {
    "proxy": {
      "server": "localhost:3128",
      "username": "username",
      "password": "P@ssw0rd"
    }
  }
}

The configuration is saved and will be applied if the docker container restarts, and you set WHATSAPP_RESTART_ALL_SESSIONS environment variables. Read more about it in Autostart section.

You can configure proxy when for all sessions by set up environment variables. Read more about it on Proxy page -> or Configuration page ->.

Enable debug

You can enable debug mode for a session by setting config.debug field to true. It’ll show you more logs in the console. Can be useful for debugging purposes when you’re experiencing some issues.

{
  "name": "default",
  "config": {
    "debug": true
  }
}

List

To get session list - call GET /api/sessions.

The response:

[
  {
    "name": "default",
    "status": "WORKING",
    "config": {
      "proxy": null,
      "webhooks": [
        {
          "url": "https://httpbin.org/post",
          "events": [
            "message",
            "session.status"
          ],
          "hmac": null,
          "retries": null,
          "customHeaders": null
        }
      ],
      "debug": false
    },
    "me": {
      "id": "79111111@c.us",
      "pushName": "WAHA"
    },
    "engine": {
      "engine": "NOWEB"
    }
  }
]

You can add ?all=true parameter to the request GET /api/session?all=True it’ll show you ALL session, including STOPPED, so you can know which one will be restarted if you set WHATSAPP_RESTART_ALL_SESSIONS=True environment variable.

Get session

To get information about a specific session - call GET /api/sessions/{session}.

{
  "name": "default",
  "status": "WORKING",
  "config": {
    "proxy": null,
    "webhooks": [
      {
        "url": "https://httpbin.org/post",
        "events": [
          "message",
          "session.status"
        ],
        "hmac": null,
        "retries": null,
        "customHeaders": null
      }
    ],
    "debug": false
  },
  "me": {
    "id": "79111111@c.us",
    "pushName": "WAHA"
  },
  "engine": {
    "engine": "NOWEB"
  }
}

Stop

In order to stop a new session - call POST /api/sessions/stop

{
  "name": "default",
  "logout": true
}

Logout

In order to log out the session - call POST /api/sessions/logout

{
  "name": "default",
  "logout": true
}

Get screenshot

Get screenshot of the session’s screen.

GET /api/screenshot?session=default

Get screenshot in Base64

You can get screenshot in base64 format by adding Accept: application/json header to the request.

GET /api/screenshot?session=default
Accept: application/json

{
  "mimetype": "image/png",
  "data": "base64-encoded-data"
}

You can change it in Swagger by clicking on Media Type dropdown and selecting application/json:

Get me

Get information about the associated account for that session (if any).

GET /api/sessions/{session}/me

Authenticated and working session’s response:

{
  "id": "11111111111@c.us",
  "pushName": "string"
}

Stopped or not authenticated session returns null:

null

Get QR

See the list of engines that support the features ->.

The simplest way to authenticate a new session - get QR code and scan it on your device.

GET /api/{session}/auth/qr

You’ll get QR image that you can scan and get authenticated

QR formats

You can get QR in different formats:

  1. binary image - GET /api/{session}/auth/qr
  2. base64 image - GET /api/{session}/auth/qr and set Accept: application/json header
  3. raw - GET /api/{session}/auth/qr?format=raw

Here’s detailed information about each format:

  1. binary image, binary image - default format, you’ll get image in response
# Get image - binary
GET /api/{session}/auth/qr

# OR
GET /api/{session}/auth/qr?format=image

# OR specify Accept header as well
GET /api/{session}/auth/qr?format=image
Accept: image/png
  1. base64 image - you’ll get image in base64 format in response if you set Accept: application/json header.
GET /api/{session}/auth/qr?format=image
Accept: application/json

{
  "mimetype": "image/png",
  "data": "base64-encoded-data"
}

You can change it in Swagger by clicking on Media Type dropdown and selecting application/json:

  1. raw - you’ll get raw data in response, you can use it to generate QR code on your side
GET /api/{session}/auth/qr?format=raw

{
  "value": "value-that-you-need-to-use-to-generate-qr-code"
}

Get pairing code

See the list of engines that support the features ->.

You can link a session with phone number - make a request to the endpoint.

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

Body example:

{
  "phoneNumber": "12132132130"
}

You’ll get code in the response that you can use on your WhatsApp app to connect the session:

{
  "code": "ABCD-ABCD"
}

Webhooks

See the list of engines that support the feature ->.

session.status

The session.status event is triggered when the session status changes.

  • STOPPED - session is stopped
  • STARTING - session is starting
  • SCAN_QR_CODE - session is required to scan QR code or login via phone number.
    • When you receive the session.status event with SCAN_QR_CODE status, you can fetch updated QR ->
    • The SCAN_QR_CODE is issued every time when QR updated (WhatsApp requirements)
  • WORKING - session is working and ready to use
  • FAILED - session is failed due to some error. It’s likely that authorization is required again or device has been disconnected from that account. Try to restart the session and if it doesn’t help - logout and start the session again.
{
    "event": "session.status",
    "session": "default",
    "me": {
        "id": "7911111@c.us",
        "pushName": "~"
    },
    "payload": {
        "status": "WORKING"
    },
    "engine": "WEBJS",
    "environment": {
        "version": "2023.10.12",
        "engine": "WEBJS",
        "tier": "PLUS"
    }
}

Advanced sessions

With WAHA Plus version you can save session state to avoid scanning QR code everytime, configure autostart options so when the docker container restarts - it restores all previously run sessions!

Session persistent

If you want to save your session and do not scan QR code everytime when you launch WAHA - connect the session storage to the container ->

Autostart

If you don’t want to call POST /api/sessions/start for every session each time when the container restart - you can use set of these environment variables to start sessions for you:

  • WHATSAPP_RESTART_ALL_SESSIONS=True: Set this variable to True to start all STOPPED sessions after container restarts. By default, this variable is set to False.
    • Please note that this will start all STOPPED sessions, not just the sessions that were working before the restart. You can maintain the session list by using POST /api/session/stop with the logout: True parameter or by calling POST /api/session/logout to remove STOPPED sessions. You can see all sessions, including STOPPED sessions, in the GET /api/sessions/all=True response.
  • WHATSAPP_START_SESSION=session1,session2: This variable can be used to start sessions with the specified names right after launching the API. Separate session names with a comma.

Multiple sessions

If you want to save server’s CPU and Memory - run multiple sessions inside one docker container! Plus version supports multiple sessions in one container.

Edit this page on GitHub
← 🔄 Webhooks
🌐 Proxy →