Documentation / Help and troubleshooting
WhatsApp connection lost
In short: For a WhatsApp number in coexistence mode, aishaa monitors whether the WhatsApp Business app on the primary phone is still opened regularly. If that does not happen for too long, or Meta reports a connection error, the red bar WhatsApp connection may be broken appears at the top of aishaa. First open the WhatsApp Business app on the primary phone. If that does not help, reconnect with Reconnect connection. Never delete the app, the WhatsApp Business account or the platform connection: that causes a waiting period at Meta of one to two months.
Where to find this
- The red bar WhatsApp connection may be broken appears at the top of every page of aishaa for as long as the connection is considered broken. Orange reminders also appear there when the connection is at risk.
- The status and the buttons to restore it are on Organisation > Channels > WhatsApp > Settings, in the Coexistence status block. The Reconnect button in the red bar takes you straight there.
Who: everyone with access to the organisation sees the bar and the reminders. The Open WhatsApp Business app and Reconnect connection buttons are available from the Organisation admin role and to the designated phone manager, even without that role. The connection applies per organisation and per number.
Recognise the situation
The status chip in the Coexistence status block tells you the state of the connection. Below it is Last seen app-side activity: with the last moment aishaa saw activity from the WhatsApp Business app (a sent message or a synchronisation of the app with Meta).
| Status | What is going on | What to do |
|---|---|---|
| Healthy | Activity from the app has been seen in the last 7 days. | Nothing. |
| Activity unknown | No activity seen for 8 days or longer. | Open the WhatsApp Business app on the primary phone. |
| At risk | No activity seen for 10 days or longer. aishaa sends reminders and shows an orange bar. | Open the WhatsApp Business app on the primary phone today. |
| Possibly broken | No activity seen for 14 days or longer, or Meta has reported a registration or connection error. Messages may be missing. aishaa shows the red bar. | Go through the steps below. |
| Unknown | The status has not been determined yet, for example straight after connecting. | Click Refresh and check again later. |
The reminders arrive as a notification in aishaa, as a push notification for anyone who has those turned on, and as an email. After 10 days the phone manager (or, if there is none, the organisation admins) receives As a precaution, open the WhatsApp Business app; after 12 days the organisation admins and phone manager receive WhatsApp channel may be at risk; after 14 days or on a connection error WhatsApp connection may be broken. The exact rules are in Coexistence: the WhatsApp Business app and aishaa together.
The red bar WhatsApp connection may be broken at the top of aishaa with the text Channel (number): messages may be missing until the coexistence connection has been restored. and the Reconnect button.
Step 1: open the WhatsApp Business app on the primary phone
Meta only keeps the connection going if the WhatsApp Business app on the primary phone is opened regularly (as a precaution, at least every 13 days). So this is always the first step, even with Possibly broken.
- Find the primary phone: the device on which the WhatsApp Business number is registered. Who manages that device is shown on the WhatsApp page under Phone manager.
- Open the WhatsApp Business app on that phone and leave it open for a moment, so the app can synchronise with Meta. At the same time, check that the app is up to date (at least version 2.24.17).
- Use the help on the page for this: on a phone or tablet the Open WhatsApp Business app button, on a computer the Open the app on the primary phone block with one QR code for Android and one for iPhone. Scan the code with the primary phone. WhatsApp Web or WhatsApp for desktop does not count: Activity via WhatsApp Web or desktop does not count.
- Click Refresh on the WhatsApp page. The status only goes back to Healthy once aishaa sees real activity from the app, for example a message sent from the app. Just clicking the button or scanning the QR code does not reset the counter; it only suppresses the reminders for three days.
If the connection was only At risk or Activity unknown, this is usually enough. The orange bar and the reminders disappear by themselves as soon as the connection is healthy again.
The Coexistence status block on Organisation > Channels > WhatsApp > Settings with the Possibly broken status chip, the line Last seen app-side activity, the Open WhatsApp Business app button or the QR codes, and the Reconnect connection button.
Step 2: check whether messages are coming in again
Send a test message from another WhatsApp number to the connected number and check whether it appears as a ticket in Tickets. Reply from aishaa and check that the reply arrives.
- If the message arrives in the WhatsApp Business app but not in aishaa, the API connection with Meta is broken. Go to step 3.
- If the message arrives in both, the connection works. The status follows as soon as aishaa has registered the activity.
Step 3: reconnect
If the API connection no longer works, restore it with the shortened reconnect. aishaa then uses the same WhatsApp Business account, the same number and the same channel settings; you do not need to set anything up again.
- Go to Organisation > Channels > WhatsApp > Settings, or click Reconnect in the red bar. If there are several coexistence numbers in this organisation, first choose the right number in the Manage or reconnect a coexistence channel list.
- Click Reconnect connection.
- Read the Reconnect coexistence? dialog carefully. Before and during the recovery, do NOT do the following:
– uninstall the WhatsApp Business app from the phone;
– remove the WhatsApp Business account (WABA) or the phone number from Meta;
– break the platform connection manually from the app.
Those actions can make the shortened reconnect unusable and cause a long waiting period. - Click Continue reconnecting and go through the Meta pop-up, just as with the first connection. Choose the same business, the same WhatsApp Business account and the same number. If you choose a different number or account, aishaa refuses the recovery and the existing channel stays unchanged.
- Then click Refresh. Check under Connection status that it says WhatsApp is connected. and that there is no longer a Webhook subscription warning or Phone registration warning. Repeat step 2 with a test message.
Do not disconnect the number with Disconnect WhatsApp to solve a problem. Disconnecting stops receiving and sending in aishaa and does not solve the cause. See Disconnect WhatsApp.
Step 4: Meta does not allow reconnecting
If the red block Reconnecting is currently not possible appears after you click Reconnect connection, Meta is reporting that the number is not eligible for the shortened reconnect. This happens if the app has been deleted, the WhatsApp Business account or the number has been removed from Meta, or the platform connection has been broken manually. Meta then applies a waiting period of one to two months before the number can be connected again.
As long as this block is shown, the Reconnect connection button is hidden. Do not keep trying again. Note the time and the channel number (the phone number shown in the red bar and under Display phone number) and contact the aishaa team via the aishaa support chat in aishaa (menu Chat, conversation aishaa support) or via support@aishaa.nl.
The red block Reconnecting is currently not possible on Organisation > Channels > WhatsApp > Settings with the explanation about Meta’s waiting period.
Number in Full Cloud API mode
If the number is connected with Full Cloud API, there is no dependency on the app and therefore no coexistence status or red bar. If the connection still stops working, Connection status shows WhatsApp is not connected yet. Connect a WhatsApp Business account to enable this channel. or This connection requires re-authentication. instead of WhatsApp is connected., usually because access at Meta has expired or been revoked. Also look at Status at Meta (see below).
- Go to Organisation > Channels > WhatsApp > Settings and click Connect WhatsApp.
- Go through the Meta pop-up again with the same business, the same WhatsApp Business account and the same number. The connection mode of an existing number cannot be changed; so do not choose coexistence this time.
- Click Refresh and check that WhatsApp is connected. appears.
Status at Meta
The same page has the Status at Meta block: what Meta itself says about the number, with Last read at Meta: and the time. This block applies to every WhatsApp number, also in Full Cloud API mode.
| Status | Meaning |
|---|---|
| Delivering | Meta delivers messages from this number. |
| Limited | Meta delivers, but with limitations. What Meta reports (under What Meta reports:) lowers the sending limit until it is resolved. |
| Blocked | Meta refuses messages that start from the business (templates). If the cause is the payment method of the WhatsApp Business account, the block says so. Resolve it in Meta Business Manager. |
| Unknown at Meta | Meta no longer knows this account or number. The connection probably no longer works: check it and reconnect if needed. |
If it says Not read at Meta yet. The first reading follows within the hour., wait a little. If Meta refuses templates from this number, the composer also warns you about it as soon as you want to send a template. See WhatsApp settings.
What happens to messages during the disruption
- As long as the connection is Possibly broken, the red bar already says so: messages may be missing until the coexistence connection has been restored. During that period, customer messages may only arrive in the WhatsApp Business app and not in aishaa. After the recovery, check the app for messages from that period and reply to them from the app if needed.
- The WhatsApp Business app on the phone itself keeps working as normal; only the relay to aishaa is faltering.
- Existing tickets and messages in aishaa are kept. Restoring or reconnecting deletes nothing.
- If you cannot send a reply from aishaa, you see this in the composer at the sending route (Send via). See WhatsApp in the inbox.
Preventing it from happening again
- Designate a Phone manager on the WhatsApp page: the colleague who manages the primary phone. They receive the reminder first and may reconnect themselves. See Phone manager and default agent.
- Make a habit of opening the WhatsApp Business app on the primary phone every week, even if you only reply from aishaa.
- Keep the app installed and up to date, and do not leave the phone switched off for weeks.
- If you do not want a dependency on the app, consider the Full Cloud API mode for a future connection. See Connect WhatsApp.
Good to know
- The red bar disappears by itself as soon as the connection is healthy again; you cannot dismiss it yourself.
- A click on Open WhatsApp Business app suppresses the reminders for three days, but restores nothing. Only real activity in the app on the primary phone resets the status.
- The date and time at Last seen app-side activity and under Connection status (Updated at, Last Business app send) help the aishaa team investigate. Mention them in your report.
- Meta sets the conditions and the waiting periods, not aishaa. aishaa cannot shorten a waiting period at Meta.