WhatsApp Official

WhatsApp Official connects a WhatsApp Business account to SquadOS through Meta’s Cloud API. Each connected number becomes an inbox that can route new conversations to an active AI agent or to human support.

This channel is different from WhatsApp, Z-API, UAZAPI, and Evolution: only WhatsApp Official uses Meta’s customer-service window and approved templates.

Before connecting

Have the following ready:

• a Meta account with access to the correct business portfolio;
• a WhatsApp Business Account (WABA), created before or during Meta signup;
• a phone number available in that WABA;
• authorization to grant the permissions requested in the popup;
• the current six-digit PIN if the number uses two-step verification.

The product instructs you to make sure the number is not active in another WhatsApp Business app. Number migration or release, display-name approval, and account requirements are controlled by Meta; follow the current instructions in WhatsApp Manager instead of deleting an account or changing security by trial and error.

Connect the inbox

1. Open Inboxes and select Connect inbox.

2. Under WhatsApp, choose WhatsApp Official. Confirm the description Meta’s official API with a verified number and select Connect with WhatsApp.

3. In the Meta popup, sign in to the correct account and complete all of Embedded Signup. Choose or create the WABA and select the number to connect. If the account has multiple WABAs, explicitly selecting the number lets SquadOS identify the matching account.

4. Return to SquadOS and keep the tab open while it shows Connecting to Meta. This can take up to 30 seconds. The inbox is created only after the flow returns enough data and setup can persist the connection.

5. If Two-step verification detected appears, complete Two-step verification before moving on. When the card shows Connected, select Continue.

6. Under Who handles this inbox?, choose Human support or an active AI agent. Review the Inbox name and select Done.

Caution

Do not treat Connected as an end-to-end test. Send a message from another number, confirm that the conversation appears under Conversations, and verify that the selected destination can reply.

Two-step verification (2FA)

The Number verification pending state means Embedded Signup finished, but number registration has not been activated. The dialog accepts exactly six digits.

• If you know the PIN, fill in Two-step verification PIN and select Register with this PIN.
• If you forgot it, use Reset PIN in WhatsApp Manager, follow Meta’s current process, and return to enter the new PIN.
• Or disable 2FA (last resort) exposes Open WhatsApp Manager. Only after completing that change at Meta should you use I disabled it, retry.
• If the process is still pending, use Finish registration on the connection card.

An incorrect PIN leaves registration pending. Repeated attempts may produce Too many incorrect attempts; wait for the period shown by the interface or reset the PIN at Meta. Do not create another inbox to bypass this state.

What the channel receives

The current adapter receives:

• text;
• images, including captions;
• audio;
• documents, including captions;
• locations, converted into a text description for the agent.

Images, audio, and documents only reach the model according to the agent’s attachment settings. Types the adapter does not recognize are not interpreted as useful media. To validate a format, send a real sample and inspect the persisted message under Conversations.

An inbox assigned to Human support creates the conversation without invoking an agent. An agent destination depends on that agent remaining active; choose an active agent even if the selector also displays other records.

Replying and the 24-hour window

The window is measured from the customer’s most recent message:

• within 24 hours, the agent and operator can reply with free-form text;
• outside the window, the composer blocks free-form text and shows Send template;
• after the template is sent, the customer must still reply before the free-form window opens again;
• this rule does not apply to QR Code or BYO-provider WhatsApp integrations.

In Automations, Send message also needs an approved template under Outside the 24h window. Without that fallback, an expired attempt is skipped as meta_window_closed. See Automation actions.

Create, sync, and send templates

Open Settings → WhatsApp templates (/settings/whatsapp-templates) to manage templates for every WhatsApp Official inbox. An inbox’s Actions menu also offers Message templates.

1. Select New template and, when there is more than one official inbox, choose the owning inbox.
2. Fill in name, language, type, and message. Use {{v1}}, {{v2}}, and so on for variable parts and provide an example for each one.
3. Select Send for approval. A template can appear as Under review, Approved, Rejected, or Unavailable.
4. Use Refresh to sync the catalog. Only Approved templates appear in Send template.
5. To send, choose the template, fill every variable value, review How the message will arrive, and select Send template.

SquadOS’s catalog reflects the status reported by WhatsApp. If no approved template exists, the dialog offers Manage templates; creating a template does not enable sending before approval.

Connection state and details

On the connected card, open the information panel to inspect data returned by Meta: Verified name, Number, Number status, Quality, Message limit, Mode, Official account, WABA Account, Business verification, and Webhook URL. Manage in Meta Business Suite opens Meta’s environment.

These details are loaded on demand and may be cached for a few minutes. Use them for diagnostics, but verify receipt and delivery with a real conversation.

Reconnect, disconnect, or delete

• Reconnect appears on the inbox row only when it is inactive for a recoverable reason, such as expired authorization or pending registration. Open that action and complete Meta’s flow again.
• Disconnect is on the connected channel’s configuration card. Voluntary disconnection removes the inbox from the list; existing conversations remain in history but can no longer reply through that connection.
• Delete inbox also removes the credential. Do not use deletion as a way to troubleshoot 2FA or Meta approval.

Caution

If the same WABA has more than one number connected to SquadOS, do not disconnect one without validating the others afterwards. The current implementation removes the webhook subscription at the entire WABA level before removing the inbox.

Troubleshooting

Message	What to check
Could not load Meta SDK	Reload the page and make sure the browser did not block Meta’s scripts or popup.
Connection cancelled	Reopen Connect with WhatsApp and finish the popup; closing or cancelling does not finish authorization.
No WhatsApp Business account found	Complete every Embedded Signup screen and confirm that an accessible WABA exists.
More than one WhatsApp Business account found	Repeat the flow and select a specific number to identify the correct WABA.
Authorization code expired or already used	Start a new connection to generate another code and do not reuse the previous attempt.
No phone numbers on account	Add or select a number in WhatsApp Manager and repeat signup.
Failed to activate webhook on Meta	Confirm access and permissions for the WABA. After retrying, validate with a real message.
Failed to register phone number	Check the number’s state in WhatsApp Manager and whether another WhatsApp Business app is active. Use the 2FA flow if it appears.
Number connected with restrictions	Inspect Business verification, Mode, Quality, and Message limit; complete the account requirements shown by Meta.
Could not get information from Meta	Authorization may have expired. Close and reopen the information panel; if the inbox becomes inactive and offers Reconnect, authorize it again.
The template is missing	Confirm it belongs to the correct inbox/WABA, sync with Refresh, and check that it is Approved.
The message did not arrive	Inspect the error band on the message or The message was saved, but WhatsApp could not deliver it; connected and persisted do not mean delivered by Meta.