Skip to main content

​
Messages not delivering

WhatsApp requires numbers in international format with country code, no leading zeros, no dashes or spaces:
  • Correct: 14155551234 (US)
  • Correct: 447911123456 (UK)
  • Wrong: (415) 555-1234
  • Wrong: 07911 123456
In HoopAI, check the contact’s phone field and ensure it includes the country code.
Not every phone number has WhatsApp. If the number is a landline or the person hasn’t installed WhatsApp, messages will fail. HoopAI will show a delivery failure indicator.
If you’re sending a free-form message and the 24-hour window has closed, the message will fail. Use an approved template instead.
If you’ve hit your daily sending limit (based on your tier level), messages will queue or fail. Wait 24 hours or request a tier upgrade by sending more messages with high quality.
Check your Meta Business Suite for any account restrictions, payment issues, or policy violations that may block sending.
If a contact has blocked your WhatsApp number, messages will show as sent but never delivered (single gray check mark). You won’t receive an explicit “blocked” notification.

​
Template rejected

Templates cannot contain:
  • Misleading or deceptive content
  • References to prohibited products (alcohol, tobacco, weapons, adult content, gambling)
  • Requests for sensitive personal data
  • Threatening or abusive language
Review Meta’s commerce policy and rewrite your template.
If you submit a promotional message as “utility”, Meta will reject it. Choose the correct category:
  • Marketing — promotions, offers, re-engagement
  • Utility — transactional updates, confirmations, reminders
  • Authentication — OTPs and verification codes
Ensure all dynamic content uses proper syntax: {{1}}, {{2}}, etc. Provide realistic sample values when submitting.
Don’t resubmit the same template with minor word changes. Make meaningful changes to address the rejection reason.
Meta may reject templates that are too generic or don’t clearly communicate their purpose. Be specific about what the message is for.
See the advanced templates guide for detailed rejection reasons and fixes.

​
Quality rating dropped

If many recipients block your number after receiving messages, your quality drops. Fix:
  • Only message contacts who have opted in
  • Reduce message frequency
  • Make content more relevant and valuable
  • Include clear opt-out instructions
Recipients reporting your messages as spam damages quality. Common causes:
  • Messaging contacts who don’t recognize your brand
  • Sending too frequently
  • Content that feels spammy or irrelevant
  1. Pause all marketing campaigns immediately
  2. Review which templates have low quality ratings
  3. Delete poorly performing templates
  4. Reduce volume — only send to your most engaged contacts
  5. Wait — quality ratings recover over 7 days of improved behavior
  6. Resume gradually — slowly increase volume while monitoring quality
If a specific template’s quality drops to Red, Meta may pause it for 3-6 hours. If quality doesn’t improve, the template is disabled. Create a new, improved template to replace it.

​
Can’t connect WhatsApp

WhatsApp Business API requires a verified Meta Business account. Go to Meta Business Suite > Settings > Business verification to start or check the status.Verification requires:
  • Business registration documents
  • Utility bill or bank statement matching the business name
  • Typically takes 1-5 business days
If your number is already connected to the WhatsApp Business API through another platform, you must disconnect it there first. A number can only be registered with one Cloud API provider at a time (unless using coexistence with the WhatsApp Business App).
During setup, you’ll receive an SMS or voice call with a verification code. If it doesn’t arrive:
  • Make sure the phone number can receive SMS or calls
  • Try the voice call option instead of SMS
  • Check if the number has any call/SMS blocking enabled
  • Wait 5 minutes and retry
The Meta user connecting WhatsApp must have Admin access to the Meta Business account. Check permissions in Meta Business Suite > Settings > People.
If two-step verification (2FA PIN) was previously set on the WhatsApp account, you’ll need to enter or reset the PIN during API registration. If you don’t know the PIN, you’ll need to wait 7 days for the PIN to reset, or use the email address associated with the 2FA to reset it.

​
Contacts not receiving messages

WhatsApp requires that contacts opt in to receive business messages. If a contact hasn’t opted in, you should not send them messages — and if recipients report you, your quality rating suffers.Valid opt-in methods:
  • Contact messages you first on WhatsApp
  • Contact fills out a form with WhatsApp consent checkbox
  • Contact opts in via SMS or email
  • In-person or phone verbal consent (with documentation)
Check if the contact has been marked as DND (Do Not Disturb) in HoopAI. Go to the contact record and check their communication preferences.
The contact’s number may be formatted incorrectly, disconnected, or not a mobile number. Verify the number includes the correct country code and is a valid mobile number.

​
WhatsApp number disconnected

Meta may disconnect your number if you violate WhatsApp’s business policies. Common violations:
  • Sending spam or unsolicited messages
  • Consistently low quality rating
  • Using WhatsApp for prohibited use cases
To reactivate: Review the violation notice in Meta Business Suite, address the issue, and submit an appeal.
If your Meta payment method fails, API access may be suspended. Update your payment method in Meta Business Suite.
If you accidentally disconnected the number in HoopAI or Meta Business Suite, reconnect by going through the WhatsApp setup flow again in Settings > WhatsApp.

​
Webhook errors

If HoopAI isn’t receiving inbound WhatsApp messages:
  1. Check that the webhook URL is correctly configured in Meta Business Suite
  2. Verify the webhook verification token matches
  3. Check for any firewall or network issues blocking Meta’s webhook calls
  4. Review Meta’s webhook status in the App Dashboard
If you’re receiving duplicate messages, check for:
  • Multiple webhook subscriptions pointing to the same endpoint
  • Retry logic processing the same event twice
  • Multiple connected WhatsApp numbers receiving the same message

​
Media not loading

Media typeMax size
Images (JPEG, PNG)5 MB
Videos (MP4)16 MB
Audio (AAC, MP3, OGG, AMR)16 MB
Documents (PDF, DOC, etc.)100 MB
Stickers (WebP)500 KB (static), 100 KB (animated)
If your file exceeds these limits, compress it before sending.
WhatsApp supports specific file formats:
  • Images: JPEG, PNG (not HEIC, TIFF, BMP)
  • Videos: MP4 with H.264 codec and AAC audio (not MOV, AVI, MKV)
  • Audio: AAC, MP3, MP4 audio, OGG with Opus codec, AMR
  • Documents: PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, TXT
Convert unsupported formats before sending.
When receiving media from customers, WhatsApp provides a temporary download URL that expires after a period. HoopAI automatically downloads and stores media, but if there’s a delay, the URL may expire. Contact support if media attachments appear broken.

​
Two-factor verification issues

WhatsApp two-step verification is a 6-digit PIN that protects your WhatsApp Business account from unauthorized registration. It’s separate from your Meta Business account password.
If you set a 2FA PIN and forgot it:
  1. If you associated an email address, use it to reset the PIN
  2. If no email was set, you must wait 7 days before you can re-register the number without the PIN
  3. During the 7-day waiting period, the number cannot be registered on any platform
You can update or disable the 2FA PIN in Meta Business Suite under your WhatsApp account settings. We recommend keeping it enabled and storing the PIN securely.

​
Migrating WhatsApp number between accounts

To migrate your WhatsApp number to a different Meta Business account:
  1. Request migration from the new Meta Business account
  2. Approve migration from the current account
  3. The number will be disconnected from the old account and connected to the new one
  4. Message history does not transfer — only the number registration moves
During migration, there may be a brief period where the number cannot send or receive messages. Plan migrations during low-traffic periods.
To move a WhatsApp number between HoopAI sub-accounts:
  1. Disconnect the number from the current sub-account
  2. Connect it to the new sub-account using the standard setup flow
  3. Re-verify the number if prompted
  • Template approvals do not transfer — you’ll need to recreate and resubmit templates
  • Quality rating and tier level do transfer with the phone number
  • Active conversations may be interrupted during the transition

​
Reference tables

​
Supported file types

TypeFormatsMax size
ImageJPEG, PNG5 MB
VideoMP4 (H.264, AAC)16 MB
AudioAAC, MP3, OGG (Opus), AMR, MP4 audio16 MB
DocumentPDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, TXT100 MB
StickerWebP500 KB (static), 100 KB (animated)

​
Message limits

LimitValue
Text message length4,096 characters
Caption length (on media)1,024 characters
Template body length1,024 characters
Template header length60 characters
Quick reply button text20 characters per button
CTA button text20 characters per button
Maximum buttons per template3 quick reply OR 2 CTA
Maximum list items10 sections, 10 rows per section

​
Error codes

ErrorMeaningFix
131047Re-engagement message outside windowUse an approved template
131026Message undeliverableCheck number format and WhatsApp registration
130429Rate limit hitWait and retry, or request tier upgrade
132000Template parameter count mismatchCheck variable mapping in workflow
132012Template not foundVerify template name and language code
133010Phone number not registeredNumber isn’t registered on WhatsApp
368Temporarily blocked for policy violationReview Meta policy notice and appeal

​
Frequently asked questions

In Meta Business Suite, go to WhatsApp Manager > Phone numbers. Your current tier and quality rating are displayed next to each number.
Permanent bans are rare and typically result from severe policy violations. You can submit an appeal through Meta Business Suite, but success isn’t guaranteed. It’s often faster to register a new number and rebuild your quality.
One check mark means the message was sent from HoopAI to WhatsApp’s servers. Two check marks mean it was delivered to the recipient’s phone. If it stays at one check, the recipient’s phone may be off, they may have no internet, or they may have blocked you.
Template appeals typically take 24-48 hours. In some cases, it may take up to 5 business days.
Templates are tied to a WhatsApp Business Account (WABA), not a specific phone number. If your numbers are under the same WABA, they share the same templates. Different WABAs require separate template submissions.
Last modified on March 6, 2026