Troubleshooting WhatsApp message delivery issues
The instructions below are for desktops and laptops only.
This guide helps you troubleshoot the most common WhatsApp message delivery problems in the tawk.to Inbox. It covers the most common troubleshooting areas, including:
- Message delivery status indicators
- WhatsApp connection status
- The 24-hour messaging window
- Message template requirements
- Phone number validation issues
- File attachment limits
- Template sending and sync errors
- Contact selection and common error messages
Check your WhatsApp connection status
Your WhatsApp number must be connected to tawk.to before messages can be sent or received.
How it works
Each WhatsApp number connected to your tawk.to property has a connection status. If the number becomes disconnected, messaging is disabled until it’s reconnected.
Each WhatsApp number connected to your tawk.to property has a connection status. If the number becomes disconnected, messaging is disabled until it’s reconnected.
How to check the status
Go to Administration > Integrations > Messaging > WhatsApp > Settings.
Click the WhatsApp Numbers tab, and check the Status column:
- Connected — the number is ready to use.- Disconnected — messages cannot be sent.
How to fix connection issues
“Inbox is disconnected”
This means the WhatsApp number is no longer connected. Click the three-dot menu (⋮) next to the number and select Connect. Then, complete Facebook (Meta) authentication.
Number stays disconnected after authentication
Disconnect the number first, then reconnect and authenticate again.
Repeated connection failures
Ensure that your Meta Business account is active with admin access to the WhatsApp Business Account (WABA).
See this guide for steps on disconnecting and reconnecting WhatsApp numbers: Updating WhatsApp settings
Disconnect the number first, then reconnect and authenticate again.
Repeated connection failures
Ensure that your Meta Business account is active with admin access to the WhatsApp Business Account (WABA).
See this guide for steps on disconnecting and reconnecting WhatsApp numbers: Updating WhatsApp settings
Understand the 24-hour messaging window
WhatsApp limits when businesses can send free-form messages to customers.
How it works
You can send free-form (non-template) messages for 24 hours after the customer’s last message. Once the window expires, the conversation becomes inactive.
How to recognize an inactive conversation
How it works
You can send free-form (non-template) messages for 24 hours after the customer’s last message. Once the window expires, the conversation becomes inactive.
How to recognize an inactive conversation
- The message input shows “Conversation is inactive”, or
- A Select Template button appears in the Reply field.
How to reopen the conversation
- Click Select Template.
- Choose a pre-approved WhatsApp Message Template.
- Fill in any required fields and send.
When the customer replies, the conversation becomes active again and the 24-hour window resets.
Resolve template sending errors
Templates must meet WhatsApp approval requirements before they can be sent.
How it works
WhatsApp only allows outbound template messages that have been approved in Meta Business Manager. Each template may also include required parameters.
When templates are required
Why template messages fail
How to fix it
Go to the WhatsApp Settings page and open the Templates tab.
How it works
WhatsApp only allows outbound template messages that have been approved in Meta Business Manager. Each template may also include required parameters.
When templates are required
- First message to a new contact: You must use a pre-approved WhatsApp Message Template.
- After the customer replies: You can send free-form messages within the 24-hour window.
Why template messages fail
- The template isn’t approved.
- Required parameters are missing.
- Parameter values are invalid.
- The template was deleted or expired.
How to fix it
Go to the WhatsApp Settings page and open the Templates tab.
Confirm the template status is Approved.
Ensure all required parameters are filled correctly.
If needed, check the template in Meta Business Manager to verify it’s still active.
Troubleshoot template sync issues
Templates must sync correctly from Meta Business Manager to appear in tawk.to.
Why templates may not appear
How to fix template sync problems
Open the WhatsApp Settings page and select the Templates tab.
Why templates may not appear
- Templates aren’t approved.
- The WABA lacks permissions.
- The WhatsApp account authorization has expired.
How to fix template sync problems
Open the WhatsApp Settings page and select the Templates tab.
Click Sync Templates.
Check that all WhatsApp Message Templates are approved in Meta Business Manager. Only templates with an Approved status will sync and appear in tawk.to.
Ensure the WhatsApp Business Account connected to tawk.to has the required permissions. The Meta account used during connection must have admin access to the WABA.Check your WABA account permissions.
If available, check the sync logs for more details. These logs can help you identify whether the issue is related to permissions, authorization, or template approval.
Common error: “Failed to sync templates”
This error usually means the WhatsApp account is no longer authorized.
How to fix: Re-authenticate the WABA account by disconnecting and reconnecting it in the WhatsApp Numbers tab, then try syncing the templates again.
Ensure the WhatsApp Business Account connected to tawk.to has the required permissions. The Meta account used during connection must have admin access to the WABA.Check your WABA account permissions.
If available, check the sync logs for more details. These logs can help you identify whether the issue is related to permissions, authorization, or template approval.
Common error: “Failed to sync templates”
This error usually means the WhatsApp account is no longer authorized.
How to fix: Re-authenticate the WABA account by disconnecting and reconnecting it in the WhatsApp Numbers tab, then try syncing the templates again.
Understand message delivery status indicators
Each WhatsApp message shows its delivery progress using status icons.
What the statuses mean
What to do if a message fails
What the statuses mean
- Sending (◯) — The message is being sent.
- Sent (✓) — The message reached WhatsApp servers.
- Delivered (✓✓ grey) — The message reached the recipient’s device.
- Read (✓✓ green) — The recipient opened the message.
- Failed (⚠️) — The message could not be delivered.
What to do if a message fails
- Check the WhatsApp connection status.
- Verify the phone number format.
- Confirm the customer hasn’t blocked your business.
- Retry the message after correcting the issue.
Fix phone number validation errors
WhatsApp requires phone numbers to follow a strict format. Each contact must have a valid WhatsApp-enabled phone number saved in the correct format before you can send a message.
Phone number format requirements
Common errors and how to fix them
Phone number format requirements
- Use E.164 format
- Include the country code with a leading +
Example: +1234567890
Common errors and how to fix them
- “Please select a phone number before sending”
Select a phone number from the contact’s phone list in the Inbox.
- Invalid phone number
Confirm the number includes the correct country code and follows E.164 format.
- Message still fails after correction
Make sure the phone number is active on WhatsApp and can receive messages.
File attachment limits and supported formats
WhatsApp applies limits to the size and type of files you can send. Each file type has a maximum size and specific supported formats. Messages will fail if a file exceeds the limit or uses an unsupported format.
Supported file types and limits
Common upload errors and solutions
Supported file types and limits
- Images: JPG, PNG — up to 5 MB
- Videos: MP4, 3GP — up to 16 MB
- Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT — up to 50 MB
- Voice messages: OGG/OPUS — up to 16 MB
- Audio files: AAC, AMR, MP3, M4A, OGG — up to 16 MB
Common upload errors and solutions
- “File size exceeded”
Compress the file or send a smaller version.
- “File type not supported”
Convert the file to one of the supported formats and try again.
Fix contact selection errors
A contact must be selected before you can send a WhatsApp message.
How it works
Each message is tied to a contact record. If no contact is selected, messaging is disabled.
Common errors and solutions
If the contact doesn’t exist, create a new contact and add their phone number before messaging.
How it works
Each message is tied to a contact record. If no contact is selected, messaging is disabled.
Common errors and solutions
- “Please select a contact before sending”
Select a contact from the contact selector first.
- Contact missing a phone number
Add a valid WhatsApp-enabled phone number to the contact.
If the contact doesn’t exist, create a new contact and add their phone number before messaging.
Fix authentication and authorization errors
Authentication issues prevent WhatsApp features from working correctly.
Common errors
How to re-authenticate
Go to WhatsApp Settings > WhatsApp Numbers.
Common errors
- “whatsapp provider account unauthorized”
- “Failed to sync templates… Please re-authenticate the connection.”
How to re-authenticate
Go to WhatsApp Settings > WhatsApp Numbers.
Click the three-dot menu (⋮) next to the account and select Disconnect. Then, click Connect and complete Facebook authentication using an admin account.
Message input disabled — what it means
Sometimes the message box is disabled with a placeholder message.
- “Inbox is disconnected” — Reconnect the WhatsApp number.
- “Please select a phone number first” — Choose a phone number for the contact.
- “Conversation is inactive” — Send a template to reopen.
- “Select a Message Template to start the conversation” — First message requires a template.
Common error codes and how to resolve them
- provider account not found
Verify the Account ID in Meta Business Manager.
- phone number resource not found
Confirm the phone number is fully registered with the WhatsApp API.
- phone number resource already connected
The phone number is linked to another property or service.
- invalid provider account token
The token has expired. Re-authenticate the WhatsApp connection.
- whatsapp provider account unauthorized
Reconnect the WhatsApp Business Account with admin permissions.
Best practices to avoid delivery issues
- Check your WhatsApp connection status regularly.
- Keep templates approved and up to date.
- Watch message delivery statuses and act on failures early.
- Save phone numbers in E.164 format.
- Use templates for first contact and inactive conversations.
- Compress files before uploading to stay within size limits.
Additional considerations
If issues continue:
- Confirm the correct WhatsApp Business Account is connected to your tawk.to property.
- Make sure the Meta account used during authentication has admin permissions.
- If a phone number appears already connected, it may still be linked to another property and must be disconnected before reuse.
Related guides
Connecting WhatsApp to tawk.to
Connecting multiple WhatsApp numbers
Updating WhatsApp settingsWhatsApp’s guide for sending and receiving messages
Connecting multiple WhatsApp numbers
Updating WhatsApp settingsWhatsApp’s guide for sending and receiving messages
If you have feedback about this article, or if you need more help:
- Click the green live chat icon
- Schedule a call with us
- Visit our community