Official WhatsApp (Cloud API)

Official WhatsApp uses Meta’s Cloud API to send and receive messages. It’s the recommended mode for production: stable, with official SLA and limits, and without the disconnection risk that can happen with QR Code mode.

Prerequisites

Before connecting:

• Phone number dedicated to WhatsApp Business, with no active personal WhatsApp on it.
• Facebook Business Manager account (free).
• (Optional) Business verification in Meta Business Manager — required to remove sending limits in production and exit sandbox mode.

Step-by-step

1. Open Admin -> Agents -> [your agent] -> Triggers.
2. In the Official WhatsApp card (marked by the API Meta badge), click Connect.
3. A Meta window opens — follow the Embedded Signup flow:
   • Sign in with your Facebook Business account.
   • Select (or create) the WABA and phone number.
   • Confirm the requested permissions.
4. Wait up to 30 seconds while SquadOS registers the number on Cloud API. Keep the tab open during this time.
5. When it finishes, the card turns Connected and starts receiving messages.

Two-step verification (2FA)

If the number you’re connecting already has two-step verification enabled — the 6-digit PIN you set up inside your WhatsApp — SquadOS can’t finalize the registration automatically and opens a dialog asking what to do.

Why this happens: when migrating the number to Cloud API, Meta requires the current PIN as proof of ownership. Without it, the register call fails with error (#133005) Two step verification PIN Mismatch.

You have three paths, listed from fastest to last resort:

1. Enter the current PIN (fastest)

If you remember the 6-digit PIN, type it into the dialog field and click Register with this PIN. SquadOS uses that PIN to finish the registration. No other steps needed.

2. Reset the PIN in WhatsApp Manager (recommended if you forgot)

If you don’t remember the PIN, reset it in WhatsApp Manager:

1. Open Manager and select your number.
2. Go to the Two-step verification tab.
3. Click Enter new PIN and set a new 6-digit code.
4. Return to SquadOS and enter the new PIN in the dialog.

This path doesn’t require email confirmation and doesn’t disable any security layer on your number. It’s the official path Meta recommends when you’ve lost the PIN.

3. Disable two-step verification (last resort)

Only use this if neither path above is possible. In the same WhatsApp Manager, under Two-step verification, click Turn off two-step verification.

• Meta sends a confirmation email to the address associated with the business portfolio.
• You need to click the link in the email to complete the removal.
• Afterwards, return to SquadOS and click I disabled it, retry in the dialog.

Once the number is connected to SquadOS, you can re-enable 2FA again in WhatsApp Manager — the PIN that Cloud API set internally remains valid.

Troubleshooting

The number doesn’t appear after Embedded Signup. Registration may have failed for a reason other than 2FA. Open the browser console (F12 -> Console) when clicking “Connect” and check for any errors — send the text to support.

Messages aren’t arriving. Check in Admin -> Agents -> [your agent] -> Triggers -> Official WhatsApp -> Information whether the number status is Connected. If it’s Pending or Restricted, check Meta Business Manager for approvals in progress.

“Too many attempts” on the PIN. Meta temporarily blocks after several incorrect attempts. Wait a few minutes and try again, or use path #2 (reset in Manager) — the counter resets when you set a new PIN.