WhatsApp via Uazapi

Uazapi is a Brazilian provider that also exposes WhatsApp through a REST API, in both self-host and managed models. SquadOS connects to your Uazapi instance with a base URL + token, and the QR code is scanned inside Uazapi’s dashboard (not here).

Unofficial API

Like Z-API, Uazapi runs on top of the WhatsApp Web protocol — no Meta SLA, risk of getting banned if used for spam, and the session can drop without warning. For production at scale, consider the Official WhatsApp (Cloud API).

When to use

Use Uazapi when	Don’t use when
You already host Uazapi or use their managed service	Starting from scratch with no preference — evaluate Z-API or Cloud API
You need more server flexibility (self-host)	You don’t have a team to keep the server running
You have medium volume with tolerance for occasional drops	Critical support where downtime becomes an incident

Prerequisites

Before you connect:

• A running Uazapi instance, either on their service (e.g. https://free.uazapi.com) or self-hosted.
• Base URL of your instance (no trailing slash): https://free.uazapi.com, https://uazapi.yourdomain.com, etc.
• Instance token — generated in Uazapi’s dashboard.

The WhatsApp QR code is scanned in Uazapi’s dashboard, not in SquadOS. SquadOS only polls the instance status and sends/receives messages.

Step by step

1. Open Admin → Agents → [your agent] → Triggers.

2. On the Uazapi card (inside the WhatsApp QR Code section), click Connect.

3. Fill in:

   

   • Base URL — your instance base (e.g. https://free.uazapi.com).
   • Instance token — token generated on the dashboard.

4. Click Validate and continue. SquadOS calls GET /instance/status on your Uazapi — if the token is wrong, the modal shows the error.

5. The next step displays the webhook URL generated by SquadOS and the exact configuration sequence Uazapi’s dashboard requires. Copy the URL and, on Uazapi’s panel (the Webhooks button on the instance):

   1. Paste the URL into the Webhook URL field and keep the method as POST.
   2. Keep addUrlEvents and addUrlTypesMessages off.
   3. Under Listen to events, add only: messages.
   4. Under Exclude from listened events, add: wasSentByApi and isGroupYes.
   5. Toggle Enabled and click Save.
   6. Connect WhatsApp by scanning the QR code inside Uazapi’s dashboard (not in SquadOS).

6. Back in SquadOS, click I’ve configured the webhook.

7. SquadOS calls /instance/status to verify. If Uazapi reports status connected, the card switches to Connected and the number appears (extracted from the owner field Uazapi returns).

If verification fails, open Uazapi’s dashboard, confirm the status is connected (and that you scanned the QR there) and click Check again.

Why these specific webhook filters?

The configuration in step 5 isn’t decoration — it’s what makes the integration work:

• messages is the only event SquadOS parses. Other events would be answered with OK - other event (ignored) but would still hit the webhook and create useless noise.
• wasSentByApi filters out messages the agent itself just sent — without this, the agent’s reply would come back through the webhook and the agent would reply to its own reply, in a loop.
• isGroupYes filters group messages. SquadOS doesn’t respond in groups today; letting them through wastes processing.
• addUrlEvents and addUrlTypesMessages off keep the webhook URL static (no dynamic suffixes), which is what SquadOS expects to validate the webhook_secret.

If messages aren’t arriving, review this configuration first before anything else.

How it works

• SquadOS does not host the WhatsApp session — it lives on your Uazapi instance.
• Messages come in via webhook, become conversations in SquadOS, and the agent replies via POST /send/text on Uazapi.
• Media (images, audio, documents) is sent via POST /send/media.

Editing credentials later

If the token expired or you changed the base URL, open the connected Uazapi card, click info and edit. SquadOS revalidates against Uazapi before saving; if it fails, the previous set is kept.

The webhook URL does not change — it’s fixed per agent.

Disconnecting

On the connected Uazapi card, click Disconnect. SquadOS calls POST /instance/disconnect on Uazapi and marks the trigger as inactive. The instance itself keeps existing on Uazapi’s dashboard.

Troubleshooting

• “Invalid credentials” at step 1. Check the base URL (no trailing slash, with https://) and the token. If Uazapi responds 401/403, this error shows up.
• Webhook configured but no messages arriving. The most common culprit is the event configuration on the webhook. Go back to Uazapi’s panel and confirm step 5 above item by item — especially that only messages is selected and that wasSentByApi is in the excluded list.
• Agent replies to its own reply in a loop. It means wasSentByApi is not in the excluded events. Fix it on Uazapi’s panel.
• Group messages arriving. isGroupYes is not in the excluded list. SquadOS already filters groups on its side, but excluding at the webhook level cuts useless traffic.
• Status stays “disconnected” forever. You need to scan the QR code on Uazapi’s dashboard — SquadOS does not show the QR for this provider (Uazapi manages the session there).