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;
• for Coexistence, the number active on the WhatsApp Business app on your phone, on the latest version.

In Official API only mode, the number can’t be on the WhatsApp Business app. To keep using the app on your phone, connect with Coexistence. 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.

3. Choose the connection mode and select Connect with WhatsApp:

   • Coexistence: keep using the WhatsApp Business app on your phone and serve customers through SquadOS on the same number;
   • Official API only: serve customers only through SquadOS, with a number that is not on the WhatsApp Business app.

4. In the Meta popup, sign in to the correct account and complete all of Embedded Signup.

   • With Coexistence, choose to connect the existing WhatsApp Business app account, enter the number, and follow the instructions shown on your phone, including the one to share your chat history.
   • With Official API only, 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.

5. 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.

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

7. 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.

If the connection doesn’t finish, the notice shows the reason and the View documentation button opens the matching section of WhatsApp Official connection errors.

Coexistence

With Coexistence, the same number serves customers through the WhatsApp Business app on your phone and through SquadOS at the same time. The number stays registered on the app, so the connection doesn’t ask for a PIN or number registration.

Contacts and history

Right after the connection, SquadOS asks Meta for the app’s contacts and chat history. The connection card shows the progress:

• Contacts applied shows how many app contacts were linked to SquadOS contacts. Syncing continues after the initial import.
• History shows as Importing history, History imported, History not shared, when sharing was declined on the phone, or Unable to import history.

Imported conversations land in Conversations as closed and with the AI Agent turned off. Media older than 14 days shows as Historical media unavailable or expired.

Replies from the phone

Messages sent from the app on the phone appear in the SquadOS conversation. When someone replies from the phone in a conversation handled by an agent, the AI Agent is paused in that conversation, as in human handoff.

Coexistence limits

• Group chats don’t appear in SquadOS.
• The WhatsApp Business app must be opened on the phone at least once every 14 days.
• Messages sent through SquadOS are charged by Meta under the official API rules. Messages sent from the app remain free.
• The SquadOS 24-hour window only counts customer messages received after the connection. Imported history doesn’t reopen the window.

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.

The screen is available to people who configure inboxes and to people who handle conversations. People who handle conversations can create, sync, and delete templates even without access to inboxes.

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

Each connection error notice has its own section in WhatsApp Official connection errors. The table below covers the channel’s other notices.

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.
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.