Account and device status

Webhook on whapi channels and session status

Channel Statuses in Whapi.Cloud

Whapi.Cloud API channels can have different statuses during their lifecycle. Here’s what each status means:

✅ AUTH (Authorized): Your channel is fully connected and operational. You can send and receive messages.

📷 QR (Waiting for QR code scan): The channel is waiting for the QR code to be scanned or pairing to be completed. Make sure to scan the code promptly — if it expires, refresh the page or restart pairing.

⏳ INIT (Initialization): Temporary state of channel initialization on the server. If the channel remains in INIT for more than 40–50 seconds, something likely went wrong. Please contact support.

😴 LAUNCH (Connecting / Inactive): The channel is attempting to establish a technical connection to the WhatsApp account. This usually takes a few seconds. If it lasts longer, it may indicate a connection issue (e.g., number is blocked or session failed). If the status doesn’t change, contact support.

⛔️ STOP (Stopped): The channel is deactivated. Possible reasons: -End of trial or subscription; -Manual deactivation; -Billing or technical issue; Check your subscription status or contact support for assistance.

⚠️ SYNC_ERROR (Synchronization issue): There is a sync failure between your WhatsApp account and the API. You can still send messages, but GET requests (e.g., to fetch chats or messages) will not work. To resolve this, log out the channel and reconnect it. Read more: Channel status “SYNC_ERROR”

---

Webhook to change channel status

The health object contains information about the uptime of the channel and the status of the channel. Sent on event "channels.post"

{
  "health": {
    "start_at": 1713774883,
    "uptime": 1,
    "status": {
      "code": 1,
      "text": "INIT"
    },
    "version": "1.8.3-74-gf7df472"
  },
  "event": {
    "type": "channel",
    "event": "post"
  },
  "channel_id": "MANTIS-M72HC"
}

{
  "health": {
    "start_at": 1713774883,
    "uptime": 77,
    "status": {
      "code": 2,
      "text": "LAUNCH"
    },
    "version": "1.8.3-74-gf7df472"
  },
  "event": {
    "type": "channel",
    "event": "post"
  },
  "channel_id": "MANTIS-M72HC"
}

{
  "health": {
    "start_at": 1713774883,
    "uptime": 78,
    "status": {
      "code": 3,
      "text": "QR"
    },
    "version": "1.8.3-74-gf7df472"
  },
  "event": {
    "type": "channel",
    "event": "post"
  },
  "channel_id": "MANTIS-M72HC"
}

{
  "health": {
    "start_at": 1713774883,
    "uptime": 89,
    "status": {
      "code": 5,
      "text": "ERROR"
    },
    "version": "1.8.3-74-gf7df472"
  },
  "event": {
    "type": "channel",
    "event": "post"
  },
  "channel_id": "MANTIS-M72HC"
}

The QR code object contains the QR code image and the status of the QR code. The QR code is only valid for a limited time. Sent on event "channels.patch"

---

Why Does My Channel Change Status During the Day?

It’s normal for WhatsApp Web–based channels to briefly reconnect throughout the day. During this process, you may receive a sequence of webhook events such as:

INIT → LAUNCH → AUTH

This typically lasts 2–3 seconds and may occur once or several times a day, depending on device conditions and connection stability.

While the API continues to work normally, requests made during this short window may return 401 "need channel authorization" errors.

To handle this smoothly:

• Use webhooks to track channel status changes;

• Pause message sending while the channel is not in AUTH ;

• Add retry logic for API calls that fail with 401;

• If reconnects are too frequent, consider using a dedicated regional proxy or configuring a proxy inside the WhatsApp app;

---

Tracking WhatsApp Sessions via Webhooks

To receive notifications when a WhatsApp account is logged out from the API channel (e.g., session terminated from the phone or due to an unexpected disconnect), make sure to enable the following webhook events in your channel settings:

• users.post — triggered when the account is successfully connected (session established)

• users.delete — triggered when the account is disconnected or logged out

These events are especially helpful when:

• The WhatsApp session is manually closed from the mobile device

• The session expires due to inactivity or internal WhatsApp policy

• The device is forcibly unlinked

You will receive a webhook callback containing relevant data (channel ID, time, type of event), which allows you to track connection status changes in real time.

Connecting an account to the channel

You can also use a webhook to track the connection/disconnection of an account to a channel. To do this, use the users.post and users.delete settings.

{
  "user": {
    "id": "61371989950",
    "name": "Jonathan"
  },
  "event": {
    "type": "users",
    "event": "post"
  },
  "channel_id": "MANTIS-M72HC"
}

Disconnect account from channel

{
  "user": {
    "id": "61371989950",
    "name": "Jonathan"
  },
  "event": {
    "type": "users",
    "event": "delete"
  },
  "channel_id": "MANTIS-M72HC"
}