Documentation / WhatsApp channel
Connect WhatsApp
In short: You connect a WhatsApp Business number to an organisation on the Organisation > Channels > WhatsApp > Settings page. First you choose a connection mode (Full Cloud API or Coexistence: Business app + aishaa), then you click Connect WhatsApp and go through the Meta pop-up. After that you receive and answer WhatsApp messages in aishaa as tickets.
Where to find this
Go to Organisation > Channels > WhatsApp > Settings. The page is called WhatsApp settings, with the subtitle Connect an existing WhatsApp Business app number and import as much recent 1:1 history as Meta allows.
Who: from the Organisation admin role upwards. The connection applies per organisation: each organisation has its own WhatsApp number. If you work with multiple organisations, first choose the right organisation with the organisation switcher at the top of the page.
An overview of everything on this page is in WhatsApp settings.
The Connect WhatsApp block under Organisation > Channels > WhatsApp > Settings with the choice between Full Cloud API and Coexistence: Business app + aishaa and the Connect WhatsApp button.
What you need at Meta
The connection runs via Meta (the parent company of WhatsApp). Make sure you have the following before you start:
- A Meta Business account (business portfolio) that you can sign in to with a Facebook account that has admin rights.
- A WhatsApp Business account (WABA) within that Meta Business account.
- A phone number for WhatsApp. If you choose Coexistence, this is the number currently in use in the WhatsApp Business app on your phone.
During the connection, aishaa asks Meta for permission to manage your WhatsApp Business account and to send and receive messages. Without that permission the connection cannot be completed.
The Open Meta Business button on the page takes you straight to the WhatsApp Business accounts in your Meta Business settings.
Choosing a connection mode
Below Connect WhatsApp is the explanation Choose how this number is connected. API only has no dependency on the app; coexistence keeps the WhatsApp Business app alongside aishaa. You only see this choice as long as there is no connection yet.
| Option | Meaning |
|---|---|
| Full Cloud API | The number is handled entirely by aishaa. The WhatsApp Business app is no longer needed and there are no dependencies on the app. |
| Coexistence: Business app + aishaa (default) | The WhatsApp Business app on the primary phone stays in use alongside aishaa. Messages come in at both places. Meta’s restrictions apply; as soon as you choose this option, the Important for WhatsApp coexistence block appears with all the conditions. |
For Coexistence, first read Coexistence: the WhatsApp Business app and aishaa together. Some choices (display name, profile picture) are fixed after connecting.
Connecting step by step
- Go to Organisation > Channels > WhatsApp > Settings and check that the right organisation is selected.
- Choose the connection mode Full Cloud API or Coexistence: Business app + aishaa.
- Click Connect WhatsApp. A Meta pop-up opens (Embedded Signup). Allow pop-ups for aishaa if your browser blocks them.
- In the pop-up, sign in to Facebook, choose your Meta Business account, the WhatsApp Business account and the phone number, and complete Meta’s steps.
- At the end, the pop-up shows the page Completing WhatsApp connection with You can close this window. aishaa will continue in the original tab. The pop-up closes and aishaa completes the connection in the tab where you started. You see the message WhatsApp connected successfully. or WhatsApp connected, but webhook subscription needs attention.
Below the Connect WhatsApp block, the Last connection result block appears with the outcome of this connection: WhatsApp connected and webhook subscription succeeded. or WhatsApp connected, but webhook subscription did not fully succeed., followed by the fields Webhook status, Phone registration, Contact sync and History sync.
The Connection status card
At the top of the page is the Connection status block with the text Current WhatsApp Business connection for this organisation. Use Refresh to fetch the current status.
As long as there is no connection, it says WhatsApp is not connected yet. Connect a WhatsApp Business account to enable this channel. After a successful connection it says WhatsApp is connected., followed by the Status at Meta block. It shows whether Meta delivers messages from the number (Delivering, Limited, Blocked or Unknown at Meta). Right after connecting it says Not read at Meta yet. The first reading follows within the hour. What the statuses mean and what to do if the number is blocked is explained in WhatsApp settings.
Below that are these fields:
| Field | Meaning |
|---|---|
| Display phone number | The connected phone number as customers see it. |
| Phone number ID | The identifier of the number at Meta. |
| WABA ID | The identifier of the WhatsApp Business account at Meta. Templates belong to this account. |
| Webhook subscription | Whether aishaa is registered with Meta to receive messages. |
| Phone registration | Whether the number is registered with Meta for sending via aishaa. |
| Token expires at | Until when aishaa’s access at Meta is valid. aishaa renews it automatically. |
| Updated at | When the connection was last updated. |
| Contact sync | Status and request time of the contact import from the WhatsApp Business app. |
| History sync | Status and request time of the import of earlier conversations. |
| Last contact sync webhook | When Meta last passed on contacts. |
| Last history sync webhook | When Meta last passed on conversation history. |
| Last Business app send | When a message was last sent from the WhatsApp Business app (Coexistence only). |
A field that is not known yet shows a dash.
Warnings below the fields start with Webhook subscription warning, Phone registration warning, Contact sync warning or History sync warning, followed by Meta’s message. If it says This connection requires re-authentication., the connection must be confirmed again at Meta: for a Cloud API connection, click Connect WhatsApp again; for Coexistence, click Reconnect connection.
Below the status card there are also the buttons Disconnect WhatsApp (see Disconnect WhatsApp) and Open Meta Business.
The Connection status block after a successful connection, with the message WhatsApp is connected and the fields Display phone number, Webhook subscription, Phone registration, Contact sync and History sync.
What happens after connecting
- New WhatsApp messages from customers arrive as tickets in Tickets. How messages end up in tickets and how you reply is explained in WhatsApp in the inbox.
- With a Coexistence connection, aishaa imports the contacts from the WhatsApp Business app (with their profile name) into Contacts, plus as much recent one-to-one history as Meta allows. Imported history ends up in a separate, closed ticket per contact. Such a history ticket stays closed, does not count as work and is not analysed by aishaa; it is only there so that the customer’s timeline is complete.
- If you want to be able to contact customers outside the 24-hour window, create templates via Account > WhatsApp templates (see WhatsApp templates). Account admins also see a WhatsApp templates button at the bottom of the WhatsApp page.
Error messages while connecting
| Message | Meaning and solution |
|---|---|
| The Meta window could not be opened. Allow pop-ups for aishaa and try again. | Your browser blocked the pop-up. Allow pop-ups for aishaa and start again with Connect WhatsApp. |
| The Meta window could not be opened or completed. Check that pop-ups are allowed for aishaa and try again. | The same, but aishaa could not establish where exactly it went wrong. |
| The Meta window was closed before the WhatsApp connection was completed. or Meta Embedded Signup was cancelled before completion. | The pop-up was closed or cancelled before all steps were finished. Start again. |
| The Meta window was not completed in time. Start connecting again. | The pop-up stayed open too long. Start again. |
| The reconnect could not be confirmed. The existing channel was safely set back to ‘reconnect required’; please try the guided reconnect again. | Reconnecting a coexistence number was not completed. Nothing is broken; click Reconnect connection once more. |
| This number was connected before. Use ‘Reconnect connection’ for the existing channel. | This number already has a connection in aishaa. Use Reconnect connection instead of a new connection (see Coexistence: the WhatsApp Business app and aishaa together). |
| The Meta sign-up could not be started. Check that your browser does not block Facebook scripts or pop-ups and try again. | Something in your browser or an extension is blocking the sign-up. Try it without blockers, or in another browser profile. |
| Meta did not return a login code. Start connecting again., Meta did not return a valid code and state. or Meta returned an invalid OAuth state. | The pop-up returned an incomplete or unexpected result, for example because the page was refreshed in the meantime. Start the connection again from this page. |
| Meta Embedded Signup returned an error. (or Meta’s own error message) | Meta could not complete the connection. Read Meta’s message, solve the problem in your Meta Business account and try again. |
| Meta returned a Facebook login code, but no WhatsApp Embedded Signup event. | The pop-up was a Facebook sign-in, but not a WhatsApp connection. Try again. If this keeps happening, contact the aishaa team. |
| The WhatsApp connection could not be completed. Run the Meta flow again and check that you select the right business account and phone number. The debug details below help support if it keeps failing. | Complete Meta’s steps again and pay attention to which business account and number you select. |
| Could not start WhatsApp connection. or WhatsApp connection could not be completed. | aishaa could not start or complete the connection. Click Refresh, try again and contact the aishaa team if it keeps failing. |
| WhatsApp connected, but webhook subscription needs attention. | The number is connected, but Meta did not fully confirm the registration for incoming messages. Check the warning in the Last connection result block and click Refresh. If the warning remains, contact the aishaa team. |
| Failed to load WhatsApp status. | The page could not fetch the status. Click Refresh. |
If completing the connection in the intermediate window fails, you see Could not complete WhatsApp connection there with one of these messages: Meta did not return a code or an error., This page was not opened by the WhatsApp connect window. Return to the original aishaa tab and try again. or The result could not be passed to the original aishaa tab. Return to that tab and try again.
If a connection keeps failing, contact the aishaa team via the aishaa support chat in aishaa (menu Chat, conversation aishaa support) or via support@aishaa.nl.
Sending debug details with a report
At the bottom of the page there is the collapsible Debug details box with the help text Technical details of the last connection attempt, useful when contacting support. Open it if you are reporting a problem and send the contents along; that saves questions back and forth. You do not need to do anything with it yourself. The Last connection result block also shows the fields Connection ID, Endpoint ID and Transport ID; you may send those along too.
Good to know
- You cannot change the connection mode on this page after connecting. If you want to switch from Coexistence to Full Cloud API or the other way round, first disconnect the number (see Disconnect WhatsApp) and connect again.
- With an existing Cloud API connection, Connect WhatsApp remains available. You use that button to confirm the same connection again, for example after This connection requires re-authentication.
- The WhatsApp page shows one connection per organisation. Previously connected Coexistence numbers remain visible in the Manage or reconnect a coexistence channel list, with the hint Previously connected coexistence channels remain available here for status checks and reconnecting. Use Back to default channel to return to the active number.
- Creating a new connection and breaking a connection are only possible with the right to manage channels. The appointed phone manager may only reconnect (see Phone manager and default agent).
- Only email, WhatsApp and telephony are available channels in aishaa. You cannot connect Instagram, X, SMS or a chat widget.