Skip to main content
Channel of type Z_API_WHATSAPP. It connects through the QR Code, the way WhatsApp Web does — no Meta, no approval, no templates.
It is the highest-volume channel on the platform. If you come from Z-API, this is the model you already use.

Requirements

  • A WhatsApp number with the app installed on a phone
  • Access to the phone to scan the QR Code
  • @omnizapi/connect 1.1.1 or later
  • A route in your backend that fetches the QR Code with the Secret Key

Connecting

Besides the channelId, WhatsApp Web needs the getQRCode function. The SDK opens the connection window, the window asks your page for the QR Code, and the SDK calls your getQRCode to answer it. The user scans the QR Code from WhatsApp on the phone, under Linked devices.
Without getQRCode, connect rejects with an OmnizapiError with code INVALID_OPTIONS and closes the window before the connection loads. The other channels ignore getQRCode, so you can always pass it. Your page’s domain must be in the SDK authorized domains. Those are the domains the window sends the QR Code request to.

The route in your backend

The QR Code comes from GET /v1/channels/{id}/zapi/qr-code/image, which requires the Secret Key. That is why the fetch happens in your backend, and the key never reaches the browser.
The API returns qrcode, the QR Code image, and connected, which is true when the number is already connected. Pass both on as they came.
Check the user’s session and that the channel belongs to them before calling the API. A route that hands out the QR Code of any channel lets someone link their own number to a channel that is not theirs.
Up to version 1.0.4, the SDK only delivered the QR Code to the window inside the panel itself. On any other domain, the window closed right after opening and connect returned success: false with reason: "not_completed". Upgrade to 1.1.1 or later.

What is different on WhatsApp Web

This is an unofficial connection, based on WhatsApp Web. The risk of the number being blocked is higher than on the Official API, and the phone must keep an active session.
Need features only the Official API has — templates, Flows, the 24-hour window, lower blocking risk? See Meta WhatsApp.