WhatsApp Issues

Diagnose and fix WhatsApp messaging issues with AD Unlock.

Messages Not Received by AD Unlock

Check Z-API Status

1. Go to Z-API dashboard 
2. Verify instance shows Connected
3. Check webhook configuration

Verify Webhook URL

In Z-API dashboard:

• Webhook URL should match what’s shown in Admin Portal
• Events should include on-message-received

Test Webhook

In Admin Portal → Settings → WhatsApp:

1. Click Test Webhook
2. Verify it shows success

Messages Not Sent to Users

Check Z-API Credits

Verify you have message credits in Z-API dashboard.

Test Send

In Admin Portal → Settings → WhatsApp:

1. Click Send Test Message
2. Enter your phone number
3. Click Send

Check Logs

Look for send errors in Admin Portal audit log.

Z-API Disconnected

Symptoms

• Z-API dashboard shows Disconnected
• Messages stop being sent/received

Solutions

1. Rescan QR code:

   • In Z-API dashboard, click Reconnect
   • On phone, WhatsApp → Linked Devices → Link a Device
   • Scan the QR code

2. Check phone:

   • Phone must have internet connection
   • WhatsApp must be running
   • Battery optimization shouldn’t kill WhatsApp

3. Consider dedicated phone:

   • Use a dedicated phone for production
   • Keep plugged in and on WiFi

Wrong Phone Number Format

Symptoms

• Users not found
• “Phone number not enrolled”

Solution

Use international format without spaces or dashes:

Always include:

• + sign
• Country code (e.g., 55 for Brazil)
• Area code
• Number (no spaces or dashes)

Duplicate Messages

Symptoms

• User receives multiple responses
• Actions performed multiple times

Causes and Solutions

Message Delays

Symptoms

• Long delay between user message and response
• OTP takes time to arrive

Solutions

1. Check Z-API latency:

   • Z-API dashboard shows message latency

2. Check AD Unlock processing:

   • Admin Portal → Requests shows processing time

3. Check connector response time:

   • Connector logs show job duration

OTP Not Received (Email)

Note: OTP is sent via email, not WhatsApp.

Check Email Configuration

1. Admin Portal → Settings → Email
2. Verify email provider settings
3. Test email delivery

Check User’s Email

1. Verify user has email in AD
2. Check spam folder
3. Verify email address is correct

Get-ADUser -Identity testuser -Properties mail | Select-Object mail

Rate Limiting

Symptoms

• “Too many requests” errors
• Messages being blocked

Solutions

1. Check Z-API rate limits in dashboard
2. Implement message queuing (contact support)
3. Consider WhatsApp Business API for higher limits

Quick Diagnostic

# Test Z-API webhook endpoint
$webhookUrl = "https://api.adunlock.me/webhook/zapi"  # Replace with your URL
 
try {
    $response = Invoke-WebRequest -Uri $webhookUrl -Method GET -UseBasicParsing
    Write-Host "Webhook endpoint reachable: $($response.StatusCode)" -ForegroundColor Green
} catch {
    Write-Host "Webhook endpoint error: $_" -ForegroundColor Red
}

For Production

Consider upgrading to WhatsApp Business API:

• More reliable (no phone needed)
• Higher rate limits
• Official support
• Contact support@adunlock.me for integration