WhatsApp via Uazapi

The WhatsApp (UAZAPI) integration connects a Uazapi instance you already manage to a SquadOS inbox. The session and QR code remain in Uazapi’s dashboard; SquadOS validates the instance, receives messages through the webhook, and sends replies through the provider API.

Unofficial integration

This option uses an API based on WhatsApp Web, not Meta’s Cloud API. The session may disconnect, and improper use may be restricted by WhatsApp. For an official integration, use Official WhatsApp.

Before you start

You need:

• permission to create inboxes;
• a Uazapi instance you can access;
• the instance’s absolute, trusted Base URL, starting with https:// or http://;
• the Instance token.

A trailing slash is accepted and removed during validation. Use only the address of an instance you manage: the SquadOS backend accesses this URL to validate credentials, check status, and send messages.

Connect the inbox

1. In Admin, open Inboxes.
2. Click Connect inbox.
3. In the WhatsApp group, select WhatsApp (UAZAPI), described as Use your UAZAPI account.
4. In the Connect Uazapi panel, enter:
   • Base URL — for example, https://free.uazapi.com;
   • Instance token — the instance secret from the provider.
5. Click Validate and continue. Validation calls GET /instance/status. A valid result confirms that the address replied and accepted the token; it does not yet prove that WhatsApp is connected or that the webhook delivers messages.
6. Copy the Webhook URL displayed by SquadOS.
7. In the instance’s Uazapi dashboard, open the webhook settings and apply these exact options:
   1. paste the URL in the URL field and keep the method set to POST;
   2. leave addUrlEvents and addUrlTypesMessages off;
   3. under Listen to events, select 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 in Uazapi’s own dashboard.
8. Return to SquadOS and click Webhook configured.
9. Use Check again until Uazapi reports the connected state. The inbox is not created until this check succeeds.
10. Click Continue and choose a destination:
    • an active agent, for AI service; or
    • Human support, to start without an agent.
11. Name the inbox and finish the wizard.

SquadOS tries to identify the number from the owner field returned by Uazapi. The same external identity cannot belong to two inboxes at the same time.

Why the webhook needs these options

• The parser accepts JSON only and processes events whose type represents a message. Other events are acknowledged and ignored.
• Turning off addUrlEvents and addUrlTypesMessages prevents URL suffixes. The SquadOS endpoint requires the exact path supplied by the wizard; any extra segment prevents inbox identification.
• wasSentByApi prevents messages originating from the API itself from reaching the webhook. SquadOS also ignores messages marked as fromMe.
• isGroupYes prevents group traffic. Even if the provider delivers it, SquadOS does not create a conversation for messages identified as group messages.

Do not alter the copied URL or add events or segments to its path. Provider-side filtering reduces unnecessary traffic, but it does not replace the safeguards applied by SquadOS.

What comes in and goes out

Incoming messages

SquadOS accepts Uazapi’s current envelope (EventType: "messages") and a compatible legacy format. It obtains the reply destination from chatid, ignores self-sent and group messages, and recognizes ordinary text, extended text, and an image caption.

Incoming attachments are not preserved

The current adapter always supplies an empty attachment list. An image with a caption may preserve only the caption; a photo, audio message, or document without text is acknowledged by the webhook but does not reach the conversation as content. For a journey that depends on the file, ask the contact to send the information as text or use another channel.

Each individual contact is associated with the inbox and its conversation. If the destination is an active agent, the message enters that agent’s pipeline. With Human support, it becomes available to the team in Conversations without an automatic AI reply.

Outgoing messages

• Text is sent through POST /send/text.
• An image generated by the agent can be sent through POST /send/media with the image type.
• The adapter does not send a typing indicator.
• Audio and documents do not have native outbound support in the current integration contract.

Messages from the agent, an operator, and an Automation use the existing conversation and inbox. This integration does not apply the Cloud API’s 24-hour window or templates; provider policies and limits remain the responsibility of the instance administrator.

Check status and edit credentials

Open the inbox details to check status or change the Base URL and Instance token. When you save new credentials, SquadOS validates them before replacing the previous values. The webhook URL belongs to the inbox, not its destination agent; changing the destination does not require a new webhook.

An unsuccessful status request does not prove that the session ended. Today, however, an invalid HTTP response from the provider is treated as connected: false and may deactivate an active inbox. Before reconnecting, confirm the session and service availability directly in Uazapi’s dashboard.

Disconnect

When you disconnect through SquadOS, the product requests POST /instance/disconnect and removes the local inbox. Historical conversations remain recorded, but the inbox and its credentials no longer exist.

Also check Uazapi

An HTTP or network failure during the remote disconnect may be hidden while the local inbox is removed. After the action, check Uazapi’s dashboard and end the session manually if it is still connected.

Troubleshooting

Validation does not continue

• Confirm that the URL is absolute and uses http:// or https://. A trailing slash is not a problem.
• Confirm the token belongs to the same instance.
• Open Uazapi’s dashboard and check that the service is available. Network and HTTP 5xx errors appear as provider unavailability; other unsuccessful responses appear as invalid credentials.

The inbox is not created

The inbox is created only after Uazapi reports connected. Scan the QR code in the provider dashboard, return to SquadOS, and use Check again.

The inbox looks connected but receives no messages

Status checks the instance; it does not test webhook delivery. Review the six webhook options, keep the path exactly as copied, and send a text message from an individual number. Do not use media as the first test.

Self-sent or group messages reach the endpoint

Confirm wasSentByApi and isGroupYes under Exclude from listened events. SquadOS also discards these events, but the correct filter avoids unnecessary calls.