WhatsApp (QR Code)

WhatsApp QR Code connects an inbox to a WhatsApp session scanned by a phone. It is useful for a short demo or for validating an agent before configuring the official API. The connection belongs to the organization, and the inbox is created only after pairing succeeds.

Choose among the five WhatsApp connections

The channel catalog offers five providers:

WhatsApp, described as Scan a QR code with your phone (tests only): this is the flow covered by this guide;
WhatsApp Official: Meta’s production integration, with a customer-service window and templates;
WhatsApp Z-API, WhatsApp UAZAPI, and WhatsApp Evolution: credential-based connections to an existing account at those providers.

Do not confuse the WhatsApp catalog option with WhatsApp Official. When you open the first option, the connection panel is titled WhatsApp QR Code.

Before connecting

Use a number reserved for testing and keep access to the phone that controls the account. The same WhatsApp identity cannot remain active in two inboxes in the organization: a new connection takes over the number and removes the previous inbox. If the number is active in another organization, SquadOS blocks pairing and asks you to disconnect it there first.

To open the flow, you must be allowed to create inboxes and change agents. The inbox can route to an active AI agent or remain under Human support.

Connect by QR Code

Open Inboxes in the sidebar.
Select Connect inbox.
Under Pick the channel, open the WhatsApp group and select WhatsApp — the option whose description ends in tests only.
In the WhatsApp QR Code panel, wait for the code to appear. The Expires in countdown starts at two minutes.
In the WhatsApp phone app, open the linked-devices area and use its link-device action to scan the code. The action’s name and position may vary by app version.
Keep the SquadOS screen open until connection is confirmed. If time runs out, select Refresh QR and scan the new code; Cancel abandons that attempt.
Under Who handles this inbox?, choose Human support or an active AI agent.
Under Destination, review the selection, fill in Inbox name, and select Done.

Requesting a QR and leaving before pairing does not create an empty inbox. After a successful scan, the inbox appears under Inboxes with the identified number.

What happens to a message

The Wuzapi webhook turns each accepted private message into an inbox conversation. The contact is identified by phone number, and the conversation title uses the display name or number. Messages sent by the connected number itself and group messages are ignored to prevent loops and participant mixing.

The channel receives:

regular and extended text;
images, including their captions;
audio and voice messages;
documents, including their captions.

Videos, stickers, and events other than a new message do not enter the pipeline. If the provider supplies an internal identifier without an alternate phone number, the event is also ignored because SquadOS cannot safely identify the contact.

With an agent as the destination, the message follows the agent’s normal pipeline. With Human support, it enters the Conversations queue without an automatic reply; an operator can take it and reply there. If the agent is inactive, the incoming message may be recorded without an automatic reply, so choose only active agents.

Replies and proactive messages

Agent replies, operator messages, and an automation’s Send message action use the unofficial session itself. This channel does not use Meta templates or apply the Official API’s 24-hour window. Proactive sending is therefore technically possible, but that does not make it safe for production: volume, spam, and WhatsApp changes remain subject to instability and blocking.

The agent sends text and can send a generated image. Operators and automations send text through the same inbox. Check the conversation to confirm that a message is marked as delivered; a provider failure can leave the attempt recorded with a delivery error.

Status and disconnection

When you open a connected inbox’s configuration, SquadOS checks the session state. This check is not continuous monitoring: its result is cached for five minutes, and the screen does not refresh it when the window regains focus. A transient Wuzapi outage can also appear as Disconnected even while the real session still exists. Before generating another QR, close and reopen the configuration and confirm the number’s state on the phone.

To end the connection voluntarily, open the inbox, use Disconnect on the WhatsApp QR Code card, and confirm. SquadOS attempts to log the session out of Wuzapi and removes the inbox from the list: with no conversations, removal is permanent; with history, the inbox is archived internally to preserve each conversation’s source. To revoke the session outside SquadOS, also remove the linked device in the WhatsApp app.

If the session is lost on its own, the inbox may be deactivated instead of removed, and the organization receives the disconnection reason. Reconnecting requires generating and scanning a new QR Code.

Quick diagnosis

The QR does not appear: wait for the generation attempt. If the panel reports an error, select Try Again; an unavailable or incompatible Wuzapi version can prevent generation.
The QR expired: select Refresh QR and scan the new code within two minutes.
The inbox appears disconnected: reopen its configuration and check linked devices on the phone before replacing the session; a transient status-check failure produces the same state.
The message does not appear: confirm that it is a private conversation and a supported format. Groups, videos, stickers, and events without an identifiable phone number are ignored.
The message appears, but there is no reply: confirm that the destination is an active agent. Under Human support, an operator must reply from Conversations.
The reply does not reach WhatsApp: check delivery state in the conversation, inbox connection, and organization credits. After a provider error, avoid bulk retries until you establish whether the first attempt was delivered.

Limits that remain

this connection has no Meta SLA, certification, or support;
the session may stop after a protocol change;
free-form sending outside Meta’s window is an unofficial-provider capability, not a compliance guarantee;
the channel does not receive groups, videos, or stickers;
for a stable operation, move to WhatsApp Official.