WhatsApp via Z-API

The WhatsApp (Z-API) integration connects an instance you already manage in Z-API to SquadOS. The provider account, session, and QR code stay in the Z-API dashboard; SquadOS validates the credentials, receives messages through a webhook, and sends replies through the provider API.

Unofficial integration

Z-API uses a WhatsApp Web-based session, not Meta’s official API. Session availability and rules depend on the provider and WhatsApp. For an official integration, use Official WhatsApp (Cloud API).

Before you start

You need:

• permission to create or edit inboxes in SquadOS;
• a Z-API account with an instance already created;
• that instance’s QR code already scanned in the Z-API dashboard;
• Instance ID;
• Instance Token;
• Account Security Token, also called the Client Token.

These are the exact three labels in the SquadOS form. Copy every value from the same instance. You do not scan the QR code in SquadOS.

Connect the inbox

1. In the admin panel, open Inboxes.
2. Select Connect inbox.
3. Under WhatsApp, choose WhatsApp (Z-API). Its description is Use your own Z-API account.
4. In Connect Z-API, fill in Instance ID, Instance Token, and Account Security Token.
5. Select Validate and continue. SquadOS checks the instance status with all three credentials. If the provider is unavailable or rejects them, no inbox is created; check the values and try again.
6. SquadOS displays a unique webhook URL. Copy it.
7. In the Z-API dashboard, open the instance settings and go to Webhooks → On message received. Paste the URL into the webhook field and save it.
8. Return to SquadOS and select Webhook configured. The system checks Z-API again.
9. If you see Your instance is not connected yet, connect the number by scanning its QR code in the Z-API dashboard, then use Check again in SquadOS.
10. After Connected! Ready to use. appears, wait for the dialog to return to the inbox step and select Continue.
11. Under Who handles this inbox?, choose an active agent for automatic replies or Human support to leave messages in the operator queue.
12. Review the Inbox name and select Done.

The inbox is created only after verification confirms the connection. Closing the wizard before that point should not leave an incomplete inbox in the list.

One instance per inbox

The same number cannot remain active in two inboxes in the same organization. If it is already connected, SquadOS may direct you to the existing inbox or replace the association according to the channel identity rule. A conflict with another organization must be resolved from that other inbox.

What happens to messages

• Individual messages received at the webhook create or continue a conversation identified by the contact’s phone number.
• Messages sent by the connected number itself and group messages are ignored.
• An inbox assigned to an active agent sends the input to that agent and delivers its reply through Z-API.
• A Human support inbox receives the conversation without invoking an agent; an operator replies from the conversations screen.
• Text uses Z-API’s text endpoint. Agent-generated images can use its image endpoint; if that delivery fails, the product tries to send a text notice.
• This channel does not use Meta’s official API 24-hour window or message templates. Automations and proactive sends still require a conversation and contact already associated with the inbox.

Inbound attachments are not processed

In the current behavior, the Z-API adapter discards an inbound photo, audio file, or document. If the media has a caption, only that caption may arrive as text; media without a caption can produce an empty input. Do not instruct customers to send files through this channel when support depends on the attachment contents. This limitation is recorded in the audit dossier and was not fixed in the documentation.

Review and edit the connection

From the inbox list, edit the Z-API inbox and open its channel settings. The information panel shows, when available:

• the connected number;
• the connection date;
• the current webhook URL, with an action to copy it;
• Instance ID, Instance Token, and Account Security Token.

When you save changed credentials, SquadOS first combines the new fields with the existing configuration and validates that complete set with Z-API. If validation fails, the previous configuration remains stored. The webhook URL keeps the inbox’s existing secret; rotating tokens does not require replacing that URL at the provider.

Disconnect

Use Disconnect in the inbox channel settings. SquadOS asks Z-API to disconnect and removes the inbox from the list. Existing conversations remain in history with their channel source, but the inbox credential is removed.

Afterwards, check the instance status in Z-API. A remote endpoint failure can currently be logged while SquadOS still removes the inbox and reports success. If the instance remains connected, end the session directly in Z-API before reusing or abandoning the number.

Troubleshooting

The credentials fail validation

Confirm all three values belong to the same instance and that Account Security Token is the account security token. Remove spaces or line breaks copied with the tokens. If the message says the provider cannot be reached, retry before replacing credentials that were already working.

The connection is not confirmed

Open the instance in Z-API and confirm that both the instance and smartphone are shown as connected. SquadOS requires both states. Then use Check again.

An HTTP failure during this status request can also be interpreted as a disconnected session and, for an active inbox, deactivate it with a session-lost reason. Confirm the real state in Z-API before creating another connection.

The webhook is saved, but messages do not arrive

Confirm that:

• the URL is saved under Webhooks → On message received for the correct instance;
• the complete URL was copied;
• the instance and smartphone are still connected;
• the test is an individual conversation, sent by someone else, using a text message;
• the inbox has the intended destination: an active agent or human support.

The Connected state proves the provider status request, not webhook delivery. Run a real test and confirm that the conversation appears in SquadOS.

The conversation appears, but there is no automatic reply

Check that the inbox is assigned to an active agent. Human support never invokes AI automatically. If the agent reply exists in history but the contact did not receive it, inspect the session status and outbound history in Z-API.

Customer media does not appear

This is the adapter’s current limitation: the file is not transported into the conversation. Ask for a text description or use another channel that accepts the required attachment type.